For Each

Discover more about the For Each connector and how to use it on the Digibee Integration Platform.

For Each makes a loop inside a JSON structure, processing each element of the array in a subpipeline. The configured expression must return an array. Otherwise, the For Each loop will not execute. Find out more about practical applications of For Each.

Parameters

Configure the connector using the parameters below. Fields that support Double Braces expressions are marked in the Supports DB column.

Parameter	Description	Type	Supports DB	Default
Alias	Name (alias) for this connector’s output, allowing you to reference it later in the flow using Double Braces expressions.	String	✅	for-each-1
Expression	The expression used to filter and retrieve the JSON structure for iteration. Supports Double Braces expressions and JSON Path expressions.	String	✅	$
Element Identifier	Unique element that identifies the line under processing (for example, "id" element).	String	❌	N/A
Parallel Execution	If enabled, this parameter processes up to 10 array elements concurrently. As each execution finishes, the next begins automatically until completion. If disabled, processing is serial, requiring each element to finish before the next starts.	Boolean	❌	False
Advanced	Enable advanced options.	Boolean	❌	False
Max Number Length	Maximum allowed length for numeric values in JSON. If not specified, the default limit defined by Jackson (1000) is applied.	Integer	✅	N/A
Fail On Error	When enabled, this parameter suspends the pipeline only if a critical error occurs within the iteration structure, preventing its completion. It does not trigger for errors within the onProcess or onException subpipelines. For interruptions based on any occurrence, use the Do While connector instead.	Boolean	❌	False

Syntax options

The For Each connector allows two methods to define the input array:

• JSON Path expressions: The traditional path (ex: $.body.items).

• Double Braces expressions: Allows you to use direct references from previous steps or integrated functions.

JSON Path Expression examples

$.[?(@.status == 'EXPIRED')]

The expression above shows how the message received by the connector can be filtered. In this example, the array is the root of the object and only the elements whose status attribute is EXPIRED will be processed by For Each.

$.body.*

Obtains all the received message body content.

$.body.products.*

Obtains the content of an array of products that's inside the received message body. We recommend that the expressions used in the JSON Path Expression parameter be validated using the following reference: https://jsonpath.com/.

Double Braces examples

For Each connector supports all existing Double Braces functions that return array values for array iteration.

{step.stepName.response.array}}

The expression above represents a reference or array coming from a specific component. You can use step.stepName in the For Each configuration form.

Accessing the current iteration element

When using the For Each connector in the Digibee Integration Platform, each iteration processes one element of the input array.

During execution, connectors inside the iteration may overwrite the payload. When that happens, the original element being processed may no longer be accessible using {{$.}}.

To ensure consistent access to the current element, the platform provides a reserved reference:

{{iterators.<for-each-alias>.current}}

Example:

If your For Each alias is for-each-1, you can access the current element using:

{{iterators.for-each-1.current}}

This reference remains available throughout the entire iteration, even if other connectors return new payloads.

Defining the subpipeline to be executed at each iteration

To define the subpipeline to be executed at each iteration, just click on the onProcess icon of For Each.

When clicking on this icon, a subpipeline will be created (or shown, if it already exists). Then build the desired flow according to the execution need of each iteration.

If Session Management connectors are used to manipulate the data of each array element in the For Each subpipeline and the Parallel Execution option is enabled, the Scoped option must also be enabled to ensure that each concurrent execution accesses its respective data.

Handling errors in loop

The standard behavior of For Each is to interrupt the execution if some error is found. Errors are atypical situations in the execution of a pipeline that result in a stop. For example, the use of an Assert V2 connector causes an error in the pipeline when the assertion condition isn't met. Other error situations occur when connectors are used with the Fail On Error configuration enabled.

As previously explained, it's possible to define a subpipeline to handle errors. The definition of this subpipeline is made through the onException icon of For Each:

Read the subpipelines article to better understand how it works.

It is not possible to interrupt the entire For Each loop. The interruption can only be done at the current iteration via connectors where the Fail On Error parameter is enabled in the onProcess and onException subpipelines.

Serious structural error during the onException subpipeline

• The loop will be interrupted;

• The error will be thrown to the next connector to which For Each is associated;

• If For Each is in the main pipeline flow, then the pipeline will be interrupted;

• If For Each is inside a pipeline that has a subpipeline, then the onException subpipeline will be informed in this pipeline input.

Messages flow

Input

For Each accepts any JSON structure that contains an array. This array can be located via JSON Path or injected via Double Braces. If the expression (regardless of the syntax chosen) does not return a valid array, no iteration will be performed.

Output

• total: total number of processed elements.

• success: total number of successfully processed elements.

• failed: total number of elements that couldn't be processed.

To inform that a line has been correctly processed and iterate the value of the "success" field, each execution of the onProcess subpipeline must respond with { "success": true } by the end. That's the only way for the output message to correctly represent the result of the processings.