1. Activate scripting on the gateway you wish to write an expression for.
2. Add expressions to the possible outcomes of the gateway.
In these examples there are process applications that you can download here as a zip-file that contains the the .bpmn files of the process models for you to try. Simply upload the .bpmn file to a new process on Barium Live to use and try this yourself:
The form in the process application looks like this and that you can download here as a zip-file that contains the form definition code. Simply create a form in your application and paste the form definition into your forms definition:
How to activate scripting on a gateway
First you need to activate scripting for the gateway. All gateways are manual until scripting has been activated.
1. Model the process that you wish to automate
2. Click on the tab Business Components
3. Use the Business Component called "Activate Gateway Scripting".
4. Drag and drop it onto your Gateway. A small icon will show up on the top right corner of your gateway indicating that it has a business component added to it.
You have now tranformed your gateway from being a manual decision into a gateway that will choose its path based on expressions (which you still need to add as the next step).
5. Right click on the first sequence flow, click on Link Condition Type and choose Expression. This makes it possible to add an expression to the sequence flow.
Note! BPMN best practice is to always define one sequence flow from your gateway as the default path. This ensures that the process can continue even if your expressions fail.
6. Right click on the sequence flow that you want to be a default path ,click on Link Condition Type and choose Default.
Adding expressions to sequence flows
Expressions are added to a sequence flow in the properties pane.
1. Right click on a sequence flow and click on Properties.
2. In the top of the properties pane there is a section of properties called ConditionalSequenceFlow with a field called Exp.
This is where you add your expression. If the expression is true, the process will continue along this sequence flow.
In the above example, add an expression on my sequence flow to take choose the path to Task 2 if the value in the metadata field My decision is yes
You don't need to add an expression to the default sequence flow since it will automatically choose that path if yes is not chosen.
Expressions are not added to the Gateway itself, instead you add expressions to the sequence flow(s) that are connected from the Gateway. It's the expressions on the sequence flow(s) that will decide which path to take.
Expressions must be created in a way that they can be either true or false. For example:
- "The value of the field in the form is yes"
- "The number in the field is greater than 10"
If the expressions is true then the process will continue along the path of the sequence flow with the expression set on it.
Note! You do not need to add an expression on your default sequence flow. Usually you have one path to follow if a value is set to true, otherwise you should follow the default path. This means that you don't have to bother adding an expression on both paths.
Choosing path based on form data content
If you want to choose a path based on data that is filled in a form you can add an expression for that. You need to know the DataID for the form in your process model and the name of the field that you want to check the value of. Read the Picking up form data: DataID & FieldName article to find out more about DataIDs and field names.
Syntax: instance.GetDataObject("[DataID]")["[FieldName]"] == "[Value to check against]"
You must replace the bold text above to the specific form information in your process application.
Check if the value of a field is something specific:
instance.GetDataObject("DataID")["fieldName"] == "fieldValue"
If you want to check if a certain value of a super combo box is selected, you can use ".include?":
Or if you want to check if two or more values in a super combo box are selected, you can use:
instance.GetDataObject("DataID")["fieldName"].include? "fieldValue" && instance.GetDataObject("DataID")["fieldName"].include? "fieldValue2"
If you want to see if a checkbox is checked or not you need to use the following expression:
instance.GetDataObject("DataID")["checkboxFieldName"] == "on"
When using metadata fields you must use the KeyValue as the Value to check against. In the example above the KeyValues are yes and no (small letters). This is because metadata fields have support for multiple languages. If you have a swedish language chosen for Barium Live the texts in the drop down will be Ja and Nej, but KeyValues will be the same (yes and no). It is important that you know the KeyValues of the metadata fields that you use in expressions. Contact whoever has created the metadata field for this information.
instance.GetDataObject("DataID")["metadataFieldName"] == "keyValue"
Choosing path based on which end event an earlier sub ended on
You can choose a path through a gateway based on how the previous sub process ended by checking which end event the sub process ended on.
This is done by creating an expression that looks at the ObjectID of the end event that the previous sub process end on. This will work for both embeded sub processes and independent sub processes.
Syntax: token.GetLastWorkitem("SubProcess").Result == "[ObjectId of end element]"
You must replace the bold text in the syntax above to the objectId in your process application.
In the above example the expression would be this:
token.GetLastWorkitem("SubProcess").Result == "19651ab2-e5c3-4067-8807-bf19d57824ea"
To get the objectId of an end event, simply right click on it and click on properties. The objectId can be found in the property ObjectID.
Expressions can sometimes be pretty advanced. Some examples of areas of use are:
Mathematical expressions (more than, less than, equals)
Combinations of more than one expression on a sequence flow (AND, OR)
More than one path from the gateway (Inclusive OR decision gateway)
Here are some examples of more advanced expressions:
It's necessary to convert to an integer before evaluating the expression by adding .to_i after the expression
MORE THAN - If the value in a number field is greater than 1000:
instance.GetDataObject("myForm")["myNumberFieldName"].to_i > 1000
EQUAL TO OR MORE THAN - If the value in a number field 1000 or more:
instance.GetDataObject("myForm")["myNumberFieldName"].to_i >= 1000
LESS THAN - If the value in a number field is less than 1000:
instance.GetDataObject("myForm")["myNumberFieldName"].to_i < 1000
EQUAL TO OR LESS THAN - If the value in a number field is 1000 or less:
instance.GetDataObject("myForm")["myNumberFieldName"].to_i <= 1000
It is possible to do mathematical calculations in your expressions as well.
Multiple expressions on one sequence flow
AND - Two fields must each have a specific value for the entire expression to be true:
instance.GetDataObject("myForm")["myDecision"] == "yes" && instance.GetDataObject("myForm")["fieldName"] == "some-value"
OR - On field or the other may be a specific value for the expression to be true:
instance.GetDataObject("myForm")["myDecision"] == "yes" || instance.GetDataObject("myForm")["fieldName"] == "some-value"
Split process into one or more paths
Inclusive OR decision is a type of gateway that allows your process to split up into one or more paths. If you add expressions to each sequence flow leaving the gateway the process will split up and follow all the paths where the expressions are true.
Remember! You must be careful when using quotations around your values " ". Quotations indicate a string value, no quotations indicate a number (or integer).
Finding and fixing expression errors
Expressions can be complex and small details in the expression may be the difference of your expression working correctly or not. If an expression does not make your process follow the path that you expected it would you can check the process application Event Log for any errors that your process application encountered, including expressions that failed to run.
An example for this would be the following:
1. Add an expression that would definitively not work, like in the process below:
2. Run the process application (after publishing the process model and upgrading the process application).
To see any errors that occured in the process application, follow step 3-7:
3. Click on Build > Process apps.
4. Double click on your application.
5. In the Manage process application overview there is a button on the bottom right called Event log.
Here you will find a list of all the important events that have occurred in your process application so far. Specifically it will show errors that have occurred.
6. Double click on the event:
7. The error details will tell you more about what went wrong and where.
This information may be a little technical, but it gives you a good indication on what went wrong. If you need additional help solving your expression problem, don't hesitate to contact our support team and supply them with the error code. Sometimes it requires an expert to fully understand.