A multi-instance activity is executed multiple times - once for each element of a given collection (like a foreach loop in a programming language).
The following activities can be marked as multi-instance:
On the execution level, a multi-instance activity has two parts: a multi-instance body, and an inner activity. The multi-instance body is the container for all instances of the inner activity.
When the activity is entered, the multi-instance body is activated and one instance for every element of the
inputCollection is created (sequentially or in parallel). When all instances are completed, the body is completed and the activity is left.
A multi-instance activity is executed either sequentially or in parallel (default). In the BPMN, a sequential multi-instance activity is displayed with three horizontal lines at the bottom. A parallel one with three vertical lines.
In case of a sequential multi-instance activity, the instances are executed one-by-one. When one instance is completed, a new instance is created for the next element in the
In case of a parallel multi-instance activity, all instances are created when the multi-instance body is activated. The instances are executed concurrently and independently from each other.
A multi-instance activity must have an
inputCollection expression that defines the collection to iterate over (e.g.
= items). Usually, it accesses a variable of the process instance that holds the collection. The expression is evaluated on activating the multi-instance body. It must result in an
array of any type (e.g.
To access the current element of the
inputCollection value within the instance, the multi-instance activity can define the
inputElement variable (e.g.
item). The element is stored as a local variable of the instance under the given name.
inputCollection value is empty, the multi-instance body is completed immediately and no instances are created. It behaves like the activity is skipped.
The output of a multi-instance activity (e.g. the result of a calculation) can be collected from the instances by defining the
outputCollection and the
outputCollection defines the name of the variable under which the collected output is stored (e.g.
results). It is created as a local variable of the multi-instance body and is updated when an instance is completed. When the multi-instance body is completed, the variable is propagated to its parent scope.
outputElement is an expression that defines the output of the instance (e.g.
= result). Usually, it accesses a variable of the instance that holds the output value. If the expression only accesses a variable or a nested property, it's created as a local variable of the instance. This variable should be updated with the output value; for example, by a job worker providing a variable with the name
result. Since the variable is defined as a local variable, it is not propagated to its parent scope and is only visible within the instance.
When the instance is completed, the
outputElement expression is evaluated and the result is inserted into the
outputCollection at the same index as the
inputElement of the
inputCollection. Therefore, the order of the
outputCollection is determined and matches to the
inputCollection, even for parallel multi-instance activities. If the
outputElement variable is not updated,
null is inserted instead.
inputCollection value is empty, an empty array is propagated as
Interrupting and non-interrupting boundary events can be attached to a multi-instance activity.
When an interrupting boundary event is triggered, the multi-instance body and all active instances are terminated. The
outputCollection variable is not propagated to the parent scope (i.e. no partial output).
When a non-interrupting boundary event is triggered, the instances are not affected. The activities at the outgoing path have no access to the local variables since they are bound to the multi-instance activity.
Every instance has a local variable
loopCounter. It holds the index in the
inputCollection of this instance, starting with
Input and output variable mappings can be defined at the multi-instance activity; they are applied on each instance on activating and on completing.
The input mappings can be used to create new local variables in the scope of an instance. These variables are only visible within the instance. It is a way to restrict the visibility of variables. By default, new variables (e.g. provided by a job worker) are created in the scope of the process instance and are visible to all instances of the multi-instance activity as well as outside of it.
In case of a parallel multi-instance activity, this can lead to variables that are modified by multiple instances and result in race conditions. If a variable is defined as a local variable, it is not propagated to a parent or the process instance scope and can't be modified outside the instance.
The input mappings can access the local variables of the instance (e.g.
loopCounter); for example, to extract parts of the
inputElement variable and apply them to separate variables.
The output mappings can be used to update the
outputElement variable; for example, to extract a part of the job variables.
Example: We have a call activity marked as a parallel multi-instance. When the called process instance completes, its variables are merged into the call activity's process instance. Its result is collected in the output collection variable, but this has become a race condition where each completed child instance again overwrites this same variable. We end up with a corrupted output collection. An output mapping can be used to overcome this, because it restricts which variables are merged. In the case of:
- Parallel multi-instance call activity
- Multi-instance output element:
- Variable in the child instance that holds the result:
The output mapping on the call activity should be:
source: =xtarget: output
A sequential multi-instance service task:
<bpmn:serviceTask id="task-A" name="A"> <bpmn:multiInstanceLoopCharacteristics isSequential="true"> <bpmn:extensionElements> <zeebe:loopCharacteristics inputCollection="= items" inputElement="item" outputCollection="results" outputElement="= result" /> </bpmn:extensionElements> </bpmn:multiInstanceLoopCharacteristics></bpmn:serviceTask>