Multi-Instance Task

A multi-instance task loops over a collection, running the same task once per item.

<serviceTask id="processItem" name="Process Item">
  <multiInstanceLoopCharacteristics
    isSequential="false"
    activiti:collection="${items}"
    activiti:elementVariable="item" />
</serviceTask>

Execution behavior

When the engine reaches a multi-instance task:

1. It reads the array variable named in activiti:collection (e.g. items)
2. It initializes an internal loop counter stored in __loop_state__
3. For each iteration, activiti:elementVariable (e.g. item) is set to the current element
4. The built-in variable __loop_index__ (0-based integer) tracks the current iteration
5. After each task completion the engine increments the index and re-enters the same element
6. Once all iterations are done the engine advances to the next element

Sequential vs. parallel

Both isSequential="true" and isSequential="false" currently execute one iteration at a time — one task is created per iteration and workers process them in order. True parallel fan-out (simultaneous tasks for all items) is planned for a future release.

Loop variables