Configuring a foreach task in the Graphical Designer

In the Graphical Designer, you can configure a task to run once for each item in a list, enabling a single task definition to fan out into multiple parallel child instances at run time.

About this task

The foreach capability enables a single task to process every item in a collection without duplicating logic. When the workflow runs, the platform evaluates the foreach expression and creates one child task instance per value, inserting the child instances after the parent task in the plan. Each child inherits the original task settings — run conditions, resources, and repeat rules — and also receives metadata describing the current list item.

When all child instances complete, their output properties are collected into an entries array on the parent task. Successor tasks can read all child results using ${J:jobs.TASKNAME.entries}.

Procedure

  1. In the Graphical Designer, open the workflow that contains the task you want to configure.
  2. Select the task to open its properties panel, and navigate to the Scheduling options section.
  3. Enable Repeat for each value and provide a source expression.

    The expression must resolve to a JSON array. Use the J: prefix whenever the source is a value from the task context. Without it, a list of strings is concatenated and then re-split on whitespace, producing incorrect iteration values. Common expression patterns:

    • Literal array: ["SMALL","MEDIUM","LARGE"]
    • Output property from a predecessor task: ${J:jobs.COLLECTOR.result.data}
    • CSV string converted to an array: ${J:$split(jobs.EXPORT.payload, ',')}
    • Large array sliced to limit fan-out: ${J:jobs.API.result.items[0..99]}

    Within the task definition, each child instance can reference its current item using ${entry.value} (the item value) and ${entry.idx} (the 1-based index).

    Tip: If the foreach expression evaluates to null or an empty array, no child instances are created and the task completes with a success status.
  4. Optionally, define output properties on the parent task to aggregate the results from all child instances.

    Use $this().entries inside the parent task's output properties to access the collected child output properties without hardcoding the task name. The entries field is an array; dot notation such as entries.p1 uses JSONata array projection to automatically collect the value of the user-defined output property p1 from every child instance into a new array. You can then apply any standard JSONata aggregation expression. For example:

    • Collect all values: ${J:$this().entries.result}
    • Sum a numeric property: ${$sum($this().entries.amount)}
    • Count child instances: ${$count($this().entries)}
    Note: Successor tasks can reference the aggregated output property by name — for example, ${J:jobs.PARENT_TASK.summary} — without needing to access the internal entries structure directly.

Results

When the workflow runs, the task fans out into one child instance per item in the source list. Each child runs independently with its own status, retries, and output. The parent task completes after all child instances finish, and any configured output properties are available to successor tasks.

What to do next

To configure the same foreach behavior using the Orchestration CLI, see Managing a task definition from the Orchestration CLI. For details about the $this() function and JSONata array projection, see Proprietary functions for JSONata.