This feature is meant to make it easy to start new process instances with a custom form for end users to fill in. Barium Live does support external start that makes it easy to share a public form where people can fill in information in a form and start new instances. However, the design and layout changes that you can do in an external start is limited to what is possible to configure in Barium Live.
If you have a need to have full control of the design and user experience of a form, this feature lets you create a custom form and easily trigger a new process instance. See more examples at the bottom of this article.
There are a couple of things that you need to do to get this to work.
- Create a form using HTML or other language that looks and works like you want it to.
- On the app you want to trigger, make a start event "External".
- Configure your custom form and Barium Live form to exchange form data.
- Configure what should happen after posting.
1. Create a custom form
Your custom form is something that you create outside of Barium Live. Perhaps you have a public web site or an internal intranet portal where you want your users to fill in information in a form. How you create an external form is out of scope for this article but below is an example in HTML
<html> <title>My custom form</title> <body> This is my custom form<br/><br/> <form method="post" action="[ENTER URL HERE]"> Name: <input type="text" name="name"/><br/><br/> E-mail: <input type="text" name="e-mail"/><br/><br/> Message: <textarea rows="2" name="description"></textarea><br/><br/> <button type="submit" value="Submit">Submit</button> </form> </body> </html>
In the action attribute (where it says [ENTER URL HERE]), you need to place the correct URL to the external start that you wish to send the data to.
2. Create and send to an External Start event
- Create an external start event for the app you wish to trigger
- In your custom form, in the action attribute in your form tag, add the URL for the external start from Barium Live (below is an example of what it might look like)
<form method="post" action="https://live.barium.se/Link/ExternalForm/134f234edgdfg-2134hgdfgsdfgfth-23435yfgdg-1435w">
Note! It's important that you use the method post, otherwise the user will simply be redirected to the external start page on Barium Live.
3. Configure your custom form and Barium Live form
In your receiving Barium Live apps start event you need to have a form attached that can receive the data that is filled in and posted from your custom form. The scenario is that you want the data filled in the custom form transferred into the corresponding fields in the Barium Live form.
The way you do that is by ensuring you use the same name in both the custom form and the Barium Live form. All the data will be posted to the start event and Barium Live will look at the data that was posted and lookup all the fields in the Barium Live form. All fields that have the same name in the custom form and Barium Live form will have its data transferred.
All the common fields are supported: textfield, textarea, datefield, attachment field, drop-downs.
Input validation on form fields
All validation in the custom form needs to be built in the custom form. Any validation that exists in the Barium Live form on the external start does not have any impact on the form. Barium Live will trigger a new instance even if there is a field in the Barium Live form that is mandatory but where there is missing data from the custom form.
4. Configure what should happen after posting
By default, a confirmation message will show up on the screen after successfully posting and triggering a new instance in the process. If you wish to change what should be presented you can add a hidden field in your form that has the name _redirect_url and where the value is the URL that you wish to redirect the user to after a post has been made.
<input type="hidden" name="_redirect_url" value="http://www.myCustomUrl.com">
After the form has been posted the user will be redirected to the URL that you input into value.
Barium Live will return the following response codes if you have managed to post data to an external start event link including an ID. The response code reasons are described below.
- The post was successful
- The external start event could not be found
- The application has been stopped
- The provided ID in the URL is not a GUID
- If there is a _return_url parameter present in the form and the user will be redirected to that URL
- Barium Live failed to start a new instance due to an internal error on Barium Live
You can use AJAX to post data. This can be useful in those scenarios where you want to have more control over the user experience when people fill in your form.
When to use this feature
We have customers that have specific requirements on their web sites. Their forms need to support assistive technology, such as screen readers. This is not possible to configure in Barium Live forms and therefore, creating custom forms with support for aria-labeled properties is common and can be used to collect data to post it to Barium Live apps.