chesterdocs

#Run a step once per item

Multi-instance runs a user task, service task, send task, sub-process or call activity once for every item of a list or every member of a user group, and hands the results on as a list.

#What happens

flowchart LR
  L["StartEvent_1.orders<br/>[A, B, C]"] --> M{{"Multi-instance step"}}
  M --> R1["Run for A<br/>__loop.index = 0"]
  M --> R2["Run for B<br/>__loop.index = 1"]
  M --> R3["Run for C<br/>__loop.index = 2"]
  R1 --> D["Completion rule met"]
  R2 --> D
  R3 --> D
  D --> N["Next step reads<br/>Activity_x[0], Activity_x[1] …"]

When the process reaches the step, Chester reads the list once and starts one run per item. Each run sees its item as __loop.item and its position as __loop.index. When the completion rule is met, the runs still open are withdrawn and the process moves on.

#Where it is available

Element Multi-instance
User task ✅ One task per item or per group member
Service task, send task ✅ One call or email per item
Sub-process ✅ Completion rule fixed to all runs
Call activity ✅
An agent, a plain task, a message throw event ❌ Runs once
The loop marker ❌ Has no effect: the step runs once

#Set it up

Select the step and open the Multi-instance group:

  1. Switch on Enable multi-instance.
  2. Execution mode: Parallel or Sequentiell (sequential) — see below.
  3. Collection type:
    • Context variable — a list from the process data. Enter it in Collection Quelle, for example StartEvent_1.orders or Activity_fetch.items.
    • User group — pick the group under User group. Its members are read when the process reaches the step; each run gets one member as __loop.item.
  4. Abschlussbedingung (completion condition): First completion, All completions, or Number of completions with the number in Required completions.

⚠️ Sequentiell, Collection Quelle and Abschlussbedingung are German whatever the language of the screen.

#Pass the item on

In the step's own fields, use __loop.item — or a field of it, such as __loop.item.email — and __loop.index. A sub-process or call activity does not see the list at all: pass the item in as an input parameter.

⚠️ In a multi-instance user task, __loop.item is probably empty in Form data input, Option data and the Display title. Who gets each task is not affected.

#Parallel or sequential

Element Parallel Sequentiell
Service task, send task All runs at once One call after the other
User task All tasks at once One task at a time: the next appears once the one before is completed
Sub-process, call activity All runs at once One run at a time: the next starts once the one before has ended

With Sequentiell, a run that fails and is retried also holds back the next one. While a sequential step runs, monitoring shows its progress as 2 of 5 and the runs still to come as pending — see the instance details.

#The results

Under the step's id, the next steps find a list: Activity_x[0].field, Activity_x[1].field … The variable list offers the fields in that form. A step whose run returns nothing gives {} for it; an empty list of items gives [], and the process continues straight away.

⚠️ With First completion or Number of completions, the list holds only the runs that finished, in the order of the items — so [0] is the first finished run, not necessarily the first item, and nothing tells you which item an entry belongs to.

#When a run fails

One failed run fails the whole step, and with it the instance — unless an error boundary event on the step catches it.

#Limits

  • ⚠️ Number of completions larger than the list. The step never finishes.
  • ⚠️ A number of completions from an expression is lost when the process is reopened in the editor. Use a fixed number.
  • ⚠️ Assignee expression on a user task is not used. Each task goes to the fixed User if one is set, and otherwise to the item itself — a user id, or an object with an id or userId. See the user task.
  • ⚠️ Validation. Missing multi-instance settings are shown in the panel only; they do not stop the deployment. A multi-instance user task over a context variable always shows the error that an assignment expression is required, even when nothing is missing.
  • ⚠️ Monitoring can keep showing withdrawn runs as waiting after the step has finished.
  • ⚠️ The same step twice. If a loop in the diagram brings the process back to the same multi-instance step in the same instance, the step may not finish the second time.
  • A list from a computed expression must really be a list; a single object from a plain reference, such as Activity_fetch.customer, runs once.

#What validation checks

The panel asks for the list, the user group or the number of completions, depending on what you chose. The messages are shown in German. See Check that a process can run.