Workflow Activities

A multi-instance activity is a way of defining repetition for a certain step in a business process. In programming concepts, a multi-instance matches the for each construct: it allows the execution of a certain step or even a complete subprocess for each item in a given collection, sequentially or in parallel.

A multi-instance is a regular activity that has extra properties defined (so-called "multi-instance characteristics'') which will cause the activity to be executed multiple times at runtime. Following activities can become a multi-instance activity:

• User Task
• Script Task
• Manual Task
• Mail Task
• Receive Task
• (Embedded) Sub Process
• Call Activity

A Gateway or Event cannot become multi-instance.

As required by the specification, each parent execution of the created executions for each instance will have following variables:

• nrOfInstances: the total number of instances
• nrOfActiveInstances: the number of currently active, i.e. not yet finished, instances. For a sequential multi-instance, this will always be 1.
• nrOfCompletedInstances: the number of already completed instances.

These values can be retrieved by calling the execution.getVariable(x) method.

Additionally, each of the created executions will have an execution-local variable (i.e. not visible for the other executions, and not stored on process instance level) :

• loopCounter: indicates the index in the for-each loop of that particular instance. The loopCounter variable can be renamed by the workflow engine's elementIndexVariable attribute.

Graphical Notation

If an activity is multi-instance, this is indicated by three short lines at the bottom of that activity. Three vertical lines indicates that the instances will be executed in parallel, while three horizontal lines indicate sequential execution.

Boundary Events and Multi-instance

Since a multi-instance is a regular activity, it is possible to define a boundary event on its boundary. In case of an interrupting boundary event, when the event is caught, all instances that are still active will be destroyed. So all instances of any subprocesses will be destroyed when the timer fires, regardless of how many instances there are or which inner activities are currently not yet completed.

Multi-instance and Execution Listeners

There is a caveat when using execution listeners in combination with multi-instance. For a normal BPMN activity, there would be an invocation of listeners when the activity is started and ended. However, when the activity is multi instance, the behaviour is different:

• When the multi-instance activity is entered, before any of the inner activities is executed, a start event is thrown. The loopCounter variable is not yet set (is null).
• For each of the actual activities visited, a start event is thrown. The loopCounter variable is set.

The same reasoning applies for the end event:

• When the actual activity is left, an end even is thrown. The loopCounter variable is set.
• When the multi instance activity has finished as a whole, an end event is thrown. The loopCounter variable is not set.

There's an example of multi-instance tasks in the Multi-Instance Tasks knowledge base article.