Skip to content

Loops and Multi-Instance

A workflow’s precondition graph is acyclic: a step waits for the steps before it, and a cycle would mean steps waiting for each other forever — the validator still rejects one. Three step blocks say, explicitly, that something runs more than once:

Chapter 6 of EventConductor in N minutes (2:56) · English, with English and Spanish subtitles

BlockSaysTypical use
forEachrun this step once per item of a listreserve every room of a booking, call an API per order line, ask each approver
repeatrun this step again until a condition holdspoll a payment until it settles
loopBackrun the steps from to to here again while a condition holdsdraft → review → rework → draft…

Every pass and every iteration is its own step execution with its own task id, so workers, retries, timeouts, cancellation and compensation work exactly as they do for any step.

- id: reserve-room
type: ACTION
name: Reserve each room
topic: booking
preconditionStepId: start
retries: 2 # per iteration
timeout: PT30S # per iteration
compensable: true
compensationStepId: release-room # once per completed iteration
forEach:
items: rooms # JEXL → a list
as: room # default: item
indexAs: roomIndex # default: index
mode: parallel # parallel (default) | sequential
maxConcurrency: 3 # parallel only; default: no limit
output: reservations # collected into this variable, in item order
outputElement: reservationId # what each iteration contributes; default: all it reported
completion: all # all (default) | any | a JEXL condition
onIterationFailure: failFast # failFast (default) | continue | compensateAll
label: "'Hab. ' + room" # names each iteration in the console: "reserve-room · Hab. 101"

forEach is allowed on ACTION, USER_TASK, PROCESS, HTTP_CALL, LLM_CALL, RULE and AGENT steps. An AGENT runs one invocation of its agent per item, each with its own invocation id, its request rendered with item and index.

Items. items is evaluated once, when the step starts, over the process variables. Variables are strings in EventConductor, so here — and only here — a variable holding a JSON array or object is read as one: items: order.lines works when order holds {"lines": [...]}. A literal works too: items: "['EUR', 'USD']". A missing list is an empty one.

What an iteration sees. The process variables, with as (the item) and indexAs (its 0-based position) laid over them — for that iteration only. A worker receives the item as a variable: text as is, objects and arrays as JSON. HTTP_CALL and LLM_CALL templates get it as structure, so url: "https://pms/rooms/${room.number}" works. A PROCESS iteration starts one child process per item, each with the item among its variables.

What an iteration reports is not written to the process. Parallel iterations would race on the same variables. It is kept on the iteration, and output collects it when the step completes: a JSON array with one element per item, in item order — null for an iteration that did not complete. Each element is outputElement evaluated over what that iteration reported (plus as and indexAs), or, without one, an object of everything it reported.

Labels. Without one, an iteration is “item 2” in the console. label is a JEXL expression that names it instead — evaluated once, when the iteration is created, over the process variables with as and indexAs laid over them (the item as structure: "'Hab. ' + room.number"). The result is kept on the iteration (cut to 80 characters), shown in the Steps tab — reserve-room · Hab. 101 — and returned as itemLabel by the REST API and MCP. A label that gives nothing, or fails to evaluate, leaves the iteration without one and is logged on the step; it never fails the iteration. It is made from the item, so in a process with sensitive variables it is stored encrypted, like the item.

Completion.

  • all — the step completes when every iteration has.
  • any — the first completed iteration completes the step; the others are cancelled.
  • a JEXL condition — checked after each completed iteration, over the process variables, the output gathered so far (under its own name) and completedIterations, totalIterations, activeIterations, failedIterations. When it holds the step completes and the rest are cancelled: completion: "completedIterations >= 2".

Failure. Each iteration has the step’s own retries. What an iteration that fails for good (or times out for good) does to the others is the forEach’s onIterationFailure:

onIterationFailureWhile iterations are still runningOnce every iteration has ended
failFast (default)The first failure fails the step at once: the iterations not yet started are cancelled, the ones at a worker are sent a cancellation, and the step ends ERROR (TIMEOUT for a timeout, so onTimeoutStepId routes it). The saga compensates the completed ones.—
continueA failure stops nothing; the rest run on (sequential ones too).The step completes, whatever failed. output tells the items apart (below).
compensateAllA failure stops nothing; the rest run on.If any failed, the step fails and the saga compensates every completed iteration; if none did, the step completes as usual.

Absent means failFast — how forEach always behaved.

Under continue, each element of output says how its item ended, and outputElement (or, without one, everything the iteration reported) moves under value:

[
{"status": "COMPLETED", "value": "R1"},
{"status": "FAILED", "error": "ERROR"},
{"status": "COMPLETED", "value": "R3"}
]

status is COMPLETED, FAILED (error is ERROR or TIMEOUT), CANCELLED (by an operator, or because a completion ended the forEach first) or NOT_RUN. Under failFast and compensateAll, output keeps its plain shape. The failure’s message is in the iteration’s log, not in output.

How it combines with the rest:

  • completion: any or a condition ends the forEach early and cancels what is still running. With continue that is fine — the failures before it are tolerated, and the condition can read failedIterations; if every iteration fails, nothing ever completes it and continue completes the step with every element FAILED. With compensateAll it makes no sense — the decision needs every iteration to have ended — and the definition is refused.
  • mode: sequential and maxConcurrency keep working: under continue and compensateAll the next item starts after a failure as it would after a success.
  • A compensation never tolerates a failure: compensating iterations always fail fast.

Retrying the failed step from the UI (or RetryStepExecution on any of its iterations) re-runs only the failed and cancelled iterations, each with a fresh retry budget; the completed ones stand.

Compensation. The unit of compensation is the completed iteration. When the saga rolls back — because a later step failed, or because the forEach itself failed after some iterations completed — the compensation step runs once per completed iteration, newest first, one at a time, each seeing that iteration’s item and index and everything it reported:

- id: release-room
type: ACTION
name: Release a room
topic: booking # receives room, roomIndex and reservationId

A cancellation races with the work it cancels. An iteration that was cancelled while its worker was already booking the room, or while its child process was finishing, can still report COMPLETED afterwards. When its step declares a compensation, that late answer is kept as a completed iteration and undone with the rest. If the rollback had already finished, a new run of the compensation undoes just that iteration, and the process ends COMPENSATED again. Late answers for a step without a compensation are ignored. Your worker should still be idempotent, and your compensation must tolerate the work it undoes having completed late.

An iteration over PROCESS whose child is still running when the forEach fails fast is cut short the other way round: its child is rolled back — it compensates what it had already done (the room it held) and ends COMPENSATED — and the parent’s rollback waits for it. The iteration stays CANCELLED, so the step’s own compensation does not undo it a second time. See A child process cut short.

Each iteration — and each compensation — can reach the target system more than once, so give it a per-item key it can recognise: see Not creating duplicates in the target system.

Empty list, limits. An empty list completes the step at once, with output []. A list longer than workflow.foreach.max-items (default 1000) fails the step at start.

Timeouts and cancellation. timeout and deadline apply to each iteration. Cancelling the process cancels every iteration in flight; an END reached on another branch cancels the forEach and its iterations.

A dynamic fork: forEach over an inline PROCESS

Section titled “A dynamic fork: forEach over an inline PROCESS”

When each item needs several steps — create the booking, then confirm it — put the forEach on a PROCESS step and write those steps in line, under steps:. Each item runs the body in a child process of its own: N branches, one per item, each with its own variables, joined when the forEach completes.

- id: rooms
type: PROCESS
name: Book one room
preconditionStepId: start
compensable: true
compensationStepId: cancelRoom # once per completed room
outputVariables: [roomBookingId] # what each branch hands back
forEach:
items: rooms
as: room
output: roomBookings
outputElement: roomBookingId
onIterationFailure: compensateAll # all rooms or none
steps: # the branch, in line
- { id: start, type: START, name: Start }
- { id: create, type: ACTION, name: Create the booking, topic: create-booking, preconditionStepId: start }
- { id: confirm, type: ACTION, name: Confirm it, topic: confirm-booking, preconditionStepId: create }
- { id: end, type: END, name: End, preconditionStepId: confirm }

It is exactly a PROCESS step with a child workflow, written where it is used — see PROCESS with an inline body. A branch never writes the parent’s variables while it runs: what it reports reaches the parent through outputVariables and output.

Inside the body, each branch reads its item as structure — ${room.number} in an HTTP_CALL, its compensation or a guard — and ${businessKey} is the parent’s business key, not the branch’s own parent:<id>; so Idempotency-Key: "${businessKey}-${room.number}" gives one stable key per room.

- id: poll-payment
type: HTTP_CALL
name: Poll the payment
preconditionStepId: charge
http:
connection: payments
path: "/payments/${paymentId}"
output: { paymentStatus: "body.status" }
repeat:
until: "paymentStatus == 'SETTLED'"
maxIterations: 20
delay: PT30S

Each time the step completes, until is evaluated once, over the process variables — with what the run just reported already written — plus iteration, the 1-based number of that run. True: the flow moves on. False: the step runs again, as a new execution, after delay (milliseconds or an ISO-8601 duration; absent = at once). The step’s retries are per run: a run that fails is retried; a run that completes with the condition still false is repeated.

repeat is allowed on the same step types as forEach, and a step declares one or the other.

- id: draft
type: USER_TASK
name: Write the draft
formId: draft-form
preconditionStepId: start
- id: review
type: USER_TASK
name: Review the draft
formId: review-form
preconditionStepId: draft
- id: decide
type: CHOICE
name: Approved?
preconditionStepId: review
- id: rework
type: ACTION
name: Ask for rework
topic: notifications
preconditions:
- { stepId: decide, expression: "verdict == 'REWORK'" }
loopBack:
to: draft # must be upstream of this step
maxIterations: 5 # the first pass included
- id: publish
type: ACTION
name: Publish
topic: cms
preconditions:
- { stepId: decide } # the CHOICE's default branch

When the step carrying loopBack completes and while holds (absent = always), the section — every step on a path from to to this step, both included — runs again:

  • each step of the section gets a fresh execution, so JOIN barriers, XOR joins and CHOICE latches inside it start over, and a CHOICE picks afresh on every pass;
  • steps outside the section keep what they did, and process variables carry over;
  • anything still in flight inside the section is cancelled;
  • to waits delay before it runs again, when one is given.

Put the loopBack on a CHOICE branch, as above, to make the CHOICE the condition; or put it on any step with a while:

loopBack: { to: fork, while: "again == 'yes'", maxIterations: 3 }

while sees the process variables plus iteration, the 1-based number of the pass that just ended.

Checked when a definition is imported and by the Maven plugin’s validate goal, with the same code:

  • to must exist, must not be the step itself (use repeat), and must be upstream of it;
  • not on a START, END or REPLY; the section may not contain a REPLY (a process replies at most once) or an END;
  • two loops must be nested or apart — sections that share steps without one containing the other are rejected;
  • a compensation step cannot carry forEach, repeat or loopBack.
  • forEach cannot be combined with awaitReply (every iteration would wait on the same correlation key); start a PROCESS per item whose child does the request/reply instead. repeat with awaitReply is fine: each run sends its request and waits for its own reply.

A loop that would run past a cap fails the step — finally, without spending its retries — and the process’s failure handling (compensation, ERROR) takes over:

CapWhere
maxIterationson the repeat / loopBack block — required
maxSuccessfulExecutionson any step: how many times it may complete in one process; enforced when a loop would run it again
defaultMaxStepExecutionson the workflow: the default for every step without its own
workflow.loops.max-iterationsengine configuration (default 1000): bounds every loop whatever it declares

The process Steps tab lists every pass and every iteration (reserve-room · item 2, poll-payment · run 3). On the diagram, a forEach step is drawn as a stack of cards with what it runs over (∥ rooms, ⇣ lines for sequential), a repeating step carries a ↻ until … chip, and a loopBack is a dashed violet back-edge with its condition. While a process runs, a forEach node shows completed/total iterations and a looped node how many times it ran (×3).

In storage, a pass is a step execution with iteration > 0 (the one it replaced superseded), and an iteration is one with a parentExecutionId (its forEach) and an itemIndex. Analytics count every pass and every iteration as a run of its step; a forEach’s container is not one — a forEach of N items is N runs (their durations included), and the definition graph counts a process once per step.

PropertyDefault
workflow.foreach.max-items1000the longest list a forEach may run over
workflow.loops.max-iterations1000the most runs any loop may make
  • a deadline for the whole forEach (today timeout/deadline bound each iteration);
  • tolerating failed iterations (onIterationError: continue);
  • forEach on SEND_MESSAGE, PUBLISH_EVENT, WAIT_FOR_MESSAGE, or on a step with awaitReply.