Multi-instance allows for certain BPMN elements to be repeated within a process. There are two options for how to execute multi-instance elements: sequentially or in parallel.
Sequential executions only ever have a single instance running at any one time. The next instance will only start after the previous one has been completed.
Parallel executions start all instances at once, meaning they are all active and can all be worked on at the same time.
Multi instance elements are graphically represented by three parallel lines at the bottom of the original element. Sequential lines are horizontal and parallel lines are vertical.
The XML representation of multi instance includes a child property in the original element.
For sequential multi-instance elements:
<bpmn2:multiInstanceLoopCharacteristics isSequential="true" />
For parallel multi-instance elements:
<bpmn2:multiInstanceLoopCharacteristics isSequential="false" />
or
<bpmn2:multiInstanceLoopCharacteristics />
The following BPMN elements can have multiple instances:
Each multi-instance execution contains the following three variables:
Variable | Description |
---|---|
nrOfInstances | The total number of instances |
nrOfActiveInstances | The number of currently active instances. For sequential multi-instances the value will always be 1 |
nrOfCompletedInstances | The number of instances that have already been completed |
Note: These variables can be used in multi-instance expressions without having to be declared as process variables.
Each instance in the multi-instance execution also has an instance-local variable that is not visible to other instances, nor to the process instance:
Variable | Description |
---|---|
loopCounter | The index in the for-each loop of that particular instance |
The number of instances to be executed can be set by the cardinality of the multi-instance item. This can be set as a static value, a process variable or calculated as an expression.
The XML representation of cardinality if the following:
<bpmn2:multiInstanceLoopCharacteristics> <bpmn2:loopCardinality>5</bpmn2:loopCardinality> </bpmn2:multiInstanceLoopCharacteristics>
A collection can be used to set the number of instances to be executed by referencing a list of items.
An element variable can optionally be used with a collection. An element variable is used to create a variable for each instance of the multi-instance element and each variable created by the element variable is assigned one value from the collection.
The following XML is an example of a user task using a collection:
<bpmn2:userTask id="UserTask_1n1uk4a" activiti:assignee="${user}">
<bpmn2:incoming>SequenceFlow_5</bpmn2:incoming>
<bpmn2:multiInstanceLoopCharacteristics activiti:collection="${userList.users}" activiti:elementVariable="user">
</bpmn2:multiInstanceLoopCharacteristics>
</bpmn2:userTask>
The activiti:collection
references a process variable called userList
that contains the following JSON:
{"users":["user1", "user2", "user3"]}
In the example:
activiti:collection
uses.users
with the values user1
, user2
and user3
because the activiti:elementVariable
is set to "users"
. activiti:assignee
is set to {users}
which is the name of the variable created in each instance by the element variable.A completion condition can be optionally included for multi-instances. When the completion condition evaluates to true
, all remaining instances are cancelled and the multi-instance activity ends.
In the following example, the completion condition will be met when 60% of instances have been completed and the remaining 4 instances will be cancelled:
<bpmn2:multiInstanceLoopCharacteristics> <bpmn2:loopCardinality>10</bpmn2:loopCardinality> <bpmn2:completionCondition>${nrOfCompletedInstances/nrOfInstances >= 0.6 }</bpmn2:completionCondition> </bpmn2:multiInstanceLoopCharacteristics>
A result collection can be set to aggregate the results from instances into a variable. The result collection is created as a process variable after instance execution has finished.
The result element variable is used to select the field or variable from the BPMN element to aggregate into the result collection.
In the following example, the user task will run 4 times sequentially and the values of flavor
from the form will be stored as a JSON object in the variable choices
:
<bpmn2:userTask id="UserTask_1n1uk4a" activiti:assignee="${users}">
<bpmn2:multiInstanceLoopCharacteristics isSequential="true">
<bpmn2:loopCardinality>4</bpmn2:loopCardinality>
<bpmn2:loopDataOutputRef>choices</bpmn2:loopDataOutputRef>
<bpmn2:outputDataItem name="flavor" />
</bpmn2:multiInstanceLoopCharacteristics>
</bpmn2:userTask>
The process variable choices
will contain a list of results similar to the following:
["chocolate", "mint", "strawberry"]
© 2023 Alfresco Software, Inc. All Rights Reserved.
By using this site, you are agreeing to allow us to collect and use cookies as outlined in Alfresco’s Cookie Statement and Terms of Use (and you have a legitimate interest in Alfresco and our products, authorizing us to contact you in such methods). If you are not ok with these terms, please do not use this website.