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
| Block | Says | Typical use |
|---|---|---|
forEach | run this step once per item of a list | reserve every room of a booking, call an API per order line, ask each approver |
repeat | run this step again until a condition holds | poll a payment until it settles |
loopBack | run the steps from to to here again while a condition holds | draft → 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.
forEach — once per item
Section titled “forEach — once per item”- 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
outputgathered so far (under its own name) andcompletedIterations,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:
onIterationFailure | While iterations are still running | Once 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. | — |
continue | A failure stops nothing; the rest run on (sequential ones too). | The step completes, whatever failed. output tells the items apart (below). |
compensateAll | A 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: anyor a condition ends the forEach early and cancels what is still running. Withcontinuethat is fine — the failures before it are tolerated, and the condition can readfailedIterations; if every iteration fails, nothing ever completes it andcontinuecompletes the step with every elementFAILED. WithcompensateAllit makes no sense — the decision needs every iteration to have ended — and the definition is refused.mode: sequentialandmaxConcurrencykeep working: undercontinueandcompensateAllthe 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 reservationIdA 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.
repeat — one step until a condition
Section titled “repeat — one step until a condition”- 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: PT30SEach 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.
loopBack — run a section again
Section titled “loopBack — run a section again”- 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 branchWhen 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;
towaitsdelaybefore 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:
tomust exist, must not be the step itself (userepeat), 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,repeatorloopBack. forEachcannot be combined withawaitReply(every iteration would wait on the same correlation key); start a PROCESS per item whose child does the request/reply instead.repeatwithawaitReplyis 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:
| Cap | Where |
|---|---|
maxIterations | on the repeat / loopBack block — required |
maxSuccessfulExecutions | on any step: how many times it may complete in one process; enforced when a loop would run it again |
defaultMaxStepExecutions | on the workflow: the default for every step without its own |
workflow.loops.max-iterations | engine configuration (default 1000): bounds every loop whatever it declares |
Seeing it run
Section titled “Seeing it run”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.
Configuration
Section titled “Configuration”| Property | Default | |
|---|---|---|
workflow.foreach.max-items | 1000 | the longest list a forEach may run over |
workflow.loops.max-iterations | 1000 | the most runs any loop may make |
Not yet
Section titled “Not yet”- a deadline for the whole forEach (today
timeout/deadlinebound each iteration); - tolerating failed iterations (
onIterationError: continue); forEachon SEND_MESSAGE, PUBLISH_EVENT, WAIT_FOR_MESSAGE, or on a step withawaitReply.