ORCFLO Documentation

Overview

The For Each Loop component lets you run one or more steps on every item in a list — individually and automatically. Instead of manually duplicating steps for each record, you drop a For Each node on the canvas, point it at a list from a previous step (or a workflow input), and add the steps that should run per item inside the loop body.

Results are collected and made available to downstream steps as a structured array — one entry per item, keeping your outputs neatly matched to their inputs.

No code required

The For Each Loop is purely visual. You configure every aspect — the items source, sub-steps, parallelism, and error handling — directly on the workflow canvas.

Canvas Layout

The For Each node appears as a resizable container on the canvas. The loop body lives inside — sub-step nodes are full, draggable workflow nodes positioned within the container bounds.

Header bar

Shows the loop name, a "For Each" type badge, a sub-step count badge, and the current execution state. The items source is shown here so you can see at a glance what list is being iterated.

Loop body

The dashed interior area. Drag to reposition sub-step nodes here. When the container is selected, resize handles appear at the corners — drag them to make the loop body larger or smaller.

Footer toolbar

Contains the + Add step button (opens a menu to pick a sub-step type) and the Configure button (opens the loop settings panel to set the items source, parallelism, error strategy, and output key).

Adding Sub-steps

There are two ways to add a step to the loop body:

Using the + Add step button

Click + Add step in the footer of the For Each container. A small menu appears with three options: AI Task, AI Agent, and Transform. Select one and a new sub-step node is immediately placed inside the container.

Drag from the component library

Drag any compatible component from the left-side component library and drop it inside the For Each container. The node is automatically added as a sub-step with its parentId set to the container.

Sub-steps behave exactly like regular workflow steps — you can click them to open their configuration panel, connect them to each other with edges, and style them independently. They are simply scoped to run once per item rather than once per workflow run.

Sub-steps stay within the container

Sub-step nodes use ReactFlow's extent: 'parent' constraint — they cannot be dragged outside the For Each container. Resize the container if you need more room.

Configuring the Loop

Click Configure in the footer of the For Each container to open the loop settings panel. This is a right-side slide-in panel with four sections:

Loop name

A human-readable name shown on the node header and in execution history.

Items source

Choose the list to iterate over. Use the Insert Variablebutton to reference a previous step's output or a workflow-level input. The items picker shows all available sources with a preview.

Processing mode

Controls how many items run simultaneously — see the Parallelism & Error Handling section below.

Advanced

Set a maximum item cap (default: 100) to protect against accidental runaway loops, choose an error strategy, and configure the output key used to collect per-item results.

Referencing Items in Sub-steps

Inside a sub-step, use the Insert Variable button in prompt fields to reference the current item being processed. Under the Loop Context section you will find the current item, index, and other loop variables. The selected variable is automatically replaced with the actual value at runtime.

If each item is an object (e.g. a JSON record from a previous step), you can also access its individual fields through the Insert Variable menu.

Parallelism & Error Handling

Processing mode

The Processing mode setting controls how many items run at the same time:

One at a time

Sequential. Each item waits for the previous one to finish. Safest for rate-limited APIs or when order matters.

5 at a time

Up to 5 items run simultaneously. Good balance of throughput and resource usage.

10 at a time

Up to 10 items run simultaneously. Higher throughput, higher resource usage.

All at once

Fully parallel. All items start simultaneously. Fastest possible execution; use only when your downstream APIs can handle the burst.

If an item fails

Individual item failures are handled by the error strategy:

Keep going, record the error

All items are attempted. Failed items appear in the output as error records alongside successful ones. Default.

Keep going, skip failed items

All items are attempted. Failed items are silently omitted from the output array.

Stop immediately

The entire loop fails on the first item error and downstream steps are skipped.

Maximum item cap

By default, the loop processes a maximum of 100 items per run. Items beyond this limit are silently skipped. Increase the cap in the Advanced section of the loop configuration if your list can exceed 100 entries.

Collecting Results

The Results section of the loop configuration controls how per-item outputs are aggregated and exposed to downstream steps.

Result type

Text response

Default.Collects the AI's full written response for each item. Best for summaries, drafts, or any free-text output. The output handle label reads items · text[].

Structured fields

Collects specific typed fields for each item. Best for classification, extraction, or scoring tasks. You define the fields (name, type, optional description) and the AI is required to fill them in. The output handle label reflects your field names, e.g. items · { sentiment, category }[].

Defining fields (structured mode)

When Structured fields is selected, a field editor appears. Each row has three columns:

Field name

Type

Description

A short identifier in camelCase or snake_case (e.g. sentiment). Required; must be unique.

String, Number, or Boolean.

Optional hint sent to the AI, e.g. "positive, negative, or neutral". Helps the model fill the field correctly.

Click Add field to append a row. Click the × button on a row to remove it. At least one field is required when structured mode is active.

Collect results from

Expand the Collect results fromdisclosure (available in both modes) to choose which sub-step's output is collected per iteration. By default this is the Last step in the loop body. If your loop has multiple sub-steps you can pick any specific sub-step by name.

Downstream variable references

When a step downstream of the For Each loop references its output, use the Insert Variablebutton to select the loop's collected array (suitable for another For Each or Transform step) or its text output for use in a standard model step.

Use Cases

Batch document summarization

Fetch a list of documents from a prior step, then loop through them with an AI Task sub-step that summarizes each one. The collected summaries are available to the next step as an array.

Per-customer report generation

Retrieve a list of customers, then for each customer run an AI step that drafts a personalized weekly report. Run up to 10 at a time to balance speed and API rate limits.

Data enrichment pipeline

Iterate over a list of product records, run a Transform sub-step to normalize each record, then an AI step to generate a marketing description for each. Chain both sub-steps inside one For Each loop.

Support ticket triage

Pull all open support tickets from an API, loop through them with an AI Task that classifies each ticket by category and priority, then pass the classified array to an output step.

Best Practices

Keep sub-steps focused

Each sub-step should do one thing. If you need to summarize and then categorize, use two sub-steps chained together rather than one large prompt.

Use Transform before looping

If your input list has noise (duplicates, empty entries, wrong shape), add a Transform step before the For Each loop to clean the data first. This reduces wasted iterations and model calls.

Start sequential, then tune parallelism

Begin with "One at a time" to verify your loop works correctly, then increase parallelism once you're happy with the output quality. This avoids wasting credits on a misconfigured parallel run.

Set a realistic item cap

The default cap of 100 prevents accidental runaway loops. If you need more, raise the cap deliberately rather than setting it to an arbitrarily large number.

Name your loop and sub-steps

Clear names make execution history much easier to read. "Summarize each ticket" is more useful than "For Each" with unnamed sub-steps.

Execution View

When you click a For Each loop in the step navigator during or after a workflow run, the execution pane shows a dedicated view with real-time iteration progress and a final summary.

While running

A live progress banner shows how many iterations have been processed and the configured parallelism mode. Below it, per-iteration lanes appear as they start — each lane shows all the sub-steps for that iteration. Expand a lane to reveal its sub-steps, then click any sub-step row to open the sub-step detail panel to the right. This floating popout shows the resolved task, full output or error, and per-step metrics (execution time, credits) — exactly like the tool call detail view for agent steps.

After completion

The Iteration Summary section shows a three-column card with total / succeeded / failed counts and a progress bar visualizing the success rate. Expand any iteration lane and click a sub-step to inspect its full output or error in the detail panel on the right. You can resize the split by dragging the handle between the two panels.

Large result sets

If your For Each loop produces more than a threshold number of iterations, the full result is automatically archived to storage. The execution view will display a notice with the total iteration count and note that only a preview is shown inline.

Troubleshooting

Loop shows "Not configured"

The items source has not been set. Click Configure on the loop node and select a list from the Items source section.

Sub-steps do not appear on canvas

Make sure you saved the workflow after adding sub-steps. Sub-step nodes are rendered as children of the For Each container — if the container is very small, try resizing it by selecting the node and dragging the resize handles.

Only some items processed

Check the Maximum items cap in the loop's Advanced configuration. If your list has more items than the cap, the extras are silently skipped. Raise the cap or add a Transform step before the loop to slice the list to the desired size.

Loop item variable not resolving

Loop context variables are only available inside sub-steps that are nested within a For Each container. They cannot be used in regular top-level workflow steps. Check that your step is positioned inside the loop body and connected with an edge from the For Each node.