ForEach

1. Overview

The ForEach component (foreach) repeats the execution of a set of steps for each item in a list, similar to a loop in programming languages. It's used when the flow receives a list (for example, items of an order, spreadsheet rows, API records) and needs to run the same sequence of actions for each one of them.

Use it when you need to process a collection item by item. Not suited for simple conditional decisions (use Choice) nor for reading Excel files directly (the Excel Reader component already iterates row by row on its own, without needing an external ForEach).

2. Prerequisites

No credentials or external access required — it's an internal engine component.

3. Authentication and Connection

Not applicable.

4. Configuration / Supported Operations

ForEach has a single operation: iterate over a list and run a sub-flow for each item.

Field	Required	Type	Description	Example
items	Yes	Expression	Path/expression that resolves to the list to iterate over. If the result isn't a list (JSON array), the component treats the value as a single item.	An expression pointing to the order's item list
step	Yes	Sub-flow	Sequence of components run for each item in the list.	A step that sends each item to an external system
isParallel	No	Text ("true"/"false")	If true, items are processed in parallel; if false (default), one item at a time, in order.	"true"
stopOnError	No	Text ("true"/"false")	If true (default), an error on any item stops the whole processing. If false, that item's error is logged and the loop continues with the next ones.	"false"
isAggregatedResult	No	Text ("true"/"false")	If true, the final result carries the response body of each processed item. If false (default), the result carries only counters (total, success, error).	"true"

Error behavior: if stopOnError is enabled and an item fails, the entire processing is interrupted with an error. If disabled, the failed item is marked as failed in the result, but the others continue being processed normally.

5. Practical Examples

Simple example: a flow receives a list of emails and uses ForEach to send a notification to each one, one at a time (isParallel off), stopping everything if one send fails (stopOnError on, default behavior).

Input:

{
  "emails": ["ana@example.com", "bruno@example.com", "carla@example.com"]
}

Component configuration:

{
  "componentName": "foreach",
  "configurations": {
    "items": "{$.body.emails}",
    "step": {
      "componentName": "http",
      "configurations": { "url": "https://api.example.com/notify", "method": "POST" }
    }
  }
}

Response (counters, isAggregatedResult default behavior):

{
  "itemsSize": 3,
  "success": 3,
  "error": 0
}

Advanced example: the same scenario, but processing sends in parallel (isParallel on) to gain speed, without stopping the process if a specific email fails (stopOnError off), and returning the detailed result of each send at the end (isAggregatedResult on) to allow later auditing of which items succeeded or failed.

Component configuration:

{
  "componentName": "foreach",
  "configurations": {
    "items": "{$.body.emails}",
    "isParallel": "true",
    "stopOnError": "false",
    "isAggregatedResult": "true",
    "step": {
      "componentName": "http",
      "configurations": { "url": "https://api.example.com/notify", "method": "POST" }
    }
  }
}

Response (one item, Bruno's email, failed but processing continued):

{
  "items": [
    { "body": "{\"status\":\"sent\"}" },
    { "body": "{\"error\":\"Failed to connect to email server\"}" },
    { "body": "{\"status\":\"sent\"}" }
  ]
}

6. Common Errors and Troubleshooting

Error / Symptom	Likely Cause	How to Fix
Flow stops mid-way through processing a list	stopOnError is enabled (default) and one of the items caused an error.	If the goal is to continue despite isolated failures, disable stopOnError.
Final result doesn't show item details	isAggregatedResult is disabled (default), returning only counters.	Enable isAggregatedResult to get the response body of each item.
ForEach processes the entire list as a single item	The items expression didn't resolve to a valid JSON list.	Check whether the expression correctly points to an array in the input message.