- Introduction
- Getting started
- Process modeling with BPMN
- Process modeling with Case Management
- Designing a persistent case entity schema
- Defining case keys (system vs. external)
- Establishing task I/O and write-back contracts
- Exit rules and early stage termination
- Modeling primary and secondary stages
- Triggering a case from Data Fabric
- Implementing stage-level personas and permissions
- Setting SLAs and automated escalation rules
- Configuring a rework loop (re-entry)
- Managing live case instances: pause, migrate, and retry
- Maestro case management component dictionary
- Process modeling with Flow
- Getting started
- Core concepts
- Node reference
- Build guides
- Best practices
- Reference
- Process implementation
- Debugging
- Simulating
- Publishing and upgrading agentic processes
- Common implementation scenarios
- Extracting and validating documents
- Process operations
- Process monitoring
- Process optimization
- Reference information
Maestro user guide
What it does
Iterates over a collection and runs the nodes in the loop body once for each item.
When to use this
Use a Loop when you have a collection of items to process, such as a list of records returned by an API, a list of files, or a list of IDs. The loop runs once per item and stops when the collection is exhausted.
To exit before the collection is exhausted, use Break on condition or a break handle, both described below.
Configuration reference
| Field | Required | Default | Description |
|---|---|---|---|
| Collection | Yes | None | Array to iterate over. Enter an expression that resolves to an array, for example $vars.listCustomers1.output. |
| Parallel | No | Off | Runs all iterations at the same time instead of one after another. When off, the loop runs sequentially and waits for each iteration to finish before starting the next. |
| Break on condition | No | None | Expression that exits the loop early when it becomes true after an iteration completes. This applies to sequential loops. |
| Show break handle | No | Off | Adds a break handle to the loop so nodes inside the body can exit the loop early. Connect a node's output to the break handle to stop iterating from inside the body. |
Sequential iteration preserves order and is required for Break on condition to work, since the condition is checked after each iteration completes. Parallel iterations don't run in a guaranteed order.
The loop body
Drag nodes inside the Loop boundary to add them to the body. Nodes in the body can read the current item and iteration, along with any variables in scope outside the loop.
Current item and iteration
Inside the body, reference the loop's progress with these expressions:
$vars.<loopName>.currentItemis the item for the current iteration. Access its fields with dot notation, for example$vars.loop1.currentItem.id.$vars.<loopName>.currentIterationis the current iteration number, starting at1.
These are available only inside the loop body.
Output
After all iterations complete, the loop's aggregated results are available at $vars.<loopName>.output. Execution then continues from the node after the loop.
currentItem and currentIteration are not accessible outside the loop body.
Examples
Example 1 — Call an API for each item
The loop iterates over $vars.listCustomers1.output. The loop body contains an HTTP Request node with the URL:
https://api.example.com/customers/{{ $vars.loop1.currentItem.id }}
https://api.example.com/customers/{{ $vars.loop1.currentItem.id }}
Example 2 — Build a result array across iterations
A Script node in the loop body returns a value for each item. The loop collects each iteration's result into $vars.loop1.output:
return { id: $vars.loop1.currentItem.id, processed: true };
return { id: $vars.loop1.currentItem.id, processed: true };
After the loop, $vars.loop1.output is an array of those results.
Example 3 — Stop early once a match is found
A Decision node in the loop body checks the current item. With Show break handle enabled, the Decision's matching branch connects to the loop's break handle to stop iterating as soon as the match is found.
Common issues
The loop body never runs.
The collection is empty or undefined. Check the upstream node's output in the execution trace to confirm the array has items. An empty collection skips the body and continues after the loop.
Break on condition never triggers in a parallel loop. Break on condition is evaluated after each iteration completes in order, so it applies to sequential loops. Turn off Parallel if you need to break on a running condition.
Editing the collection inside the body doesn't change what's iterated. The collection is captured when the loop starts. Modifying the array variable inside the body doesn't change which items are iterated. This is by design.