Configuring Multi Instance Loops

This guide needs review for expression variables and syntax. Also, the location where loop variables can be accessed needs better clarity for user task, sub-process and service task.

In process flow diagrams, it is sometimes needed to execute the same task several times before continuing the flow. This could either be like executing a task for fixed number of times (each time with different arguments) or executing a task again and again until a certain condition is met. This can be achieved by

  • defining a simple task, followed by a gateway with one branch looping back to the task
  • defining a simple task and specifying multi instance loop characteristics on task.

The second approach has two benefits compared to the first:

  1. Process definition is simpler and less complicated
  2. The gateway approach will always execute task sequentially. Multi-instance loops allow executing tasks sequentially or in parallel.

This guide will help you understand how to configure workflow for Multi-Instance execution and proper data passing.


Parameters Definition
Loop Cardinality Directly define how many times certain Task should execute, no explicit data-passing
Collection Defining collection of Objects to be passed to individual tasks/processes
Element Variable Defining the name of property through which collection elements enters the task/process
Completion Condition Interrupt remaining instances of Multi Instance on completion condition

Loop Cardinality

Loop cardinality is used when data passed to the task is irrelevant, and the only motive is fork multiple instances of the same Task or Sub Process. If loop cardinality is defined, collection and element variable need not be defined. Loop cardinality field can be a fixed number (e.g. 4) or an expression evaluating to a number (e.g. ${pv('processCount')*2}).

Collection & Element Variable

Collection can be used when separate task has to be executed corresponding to each element in a collection. Total number of tasks executed depends on the elements in collection and each task is passed one item from the collection as context data. You can define a fixed collection or an expression refering process-variable or message-variable of array type. For each instance of the multi instance, corresponding collection item is passed as payload. For a sub process, the payload is available as process variable within a property name that matches Element Variable. For a User Task, the collection item can be refered by element variable assuming the variable is coming from process variables.

Allowed Syntax

  • Collection : pv(“products”)

User can choose the collection from process-variables or message using pv("*") / msg("*")

  • Element Variable : product

Additionaly an extra variable named _iteration is created and passed to instances of multi instance to define which element index it is acting upon.

Completion Condition

Completion condition will be evaluated everytime any of the multiple instances completes its execution. If the completion condition holds true, all the ongoing instances executing as part of Multi-Instance-Loop will be interrupted. An example would be, say we have a parallel Multi-Instance User task that is assigned to 4 users, whose assignee list has been given as part of collection definition. In this case our completion condition might be continue the flow after atleast half of the tasks are completed. Thus, when two of the four user tasks are complete, the other tasks are interrupted and process flow moves forward.

Following three additional properties can be used as part of conditional completion expression

  • nrOfInstances
  • nrOfCompleteInstances
  • nrOfActiveInstances

Allowed Syntax

  • ${nrOfCompleteInstances/nrOfInstances >= 0.5 }
  • ${count > 2} // assuming count is available from process-variables