For Each

Discover more about the For Each component 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. Find out more about practical applications of For Each.

Parameters

Take a look at the configuration parameters of the component. Parameters supported by Double Braces expressions are marked with (DB).

Parameter	Description	Default value	Data type
JSON Path Expression	Expression applied to the JSON structure received by For Each, filtering it. For Each can receive an object that has multiple elements, and the JSON Path expression allows the reception only of those that meet a specific condition. To improve the use of the For Each component, we recommend that the expressions used in the JSON Path Expression parameter be validated using the following reference: https://jsonpath.com/.	$	String
Element Identifier	Unique element that identifies the line under processing (for example, "id" element).	N/A	String
Parallel Execution	When enabled, the option makes the elements of the array received by For Each to be processed in parallel, with a limit of up to 10 concurrent executions. That means if the array received by the component has 20 elements, the first 10 will have the processing started right away. As soon as one of these processings ends, the next element of the array will be processed, and so on, until the whole array is processed. If the Parallel Execution option is disabled, the elements of the array received by For Each will be processed in series. The first one must be processed for the processing of the second one to start.	False	Boolean
Fail On Error	When activated, this parameter suspends the pipeline execution only if there’s a severe occurrence in the iteration structure, disabling its complete conclusion. The Fail On Error parameter activation doesn’t have any connection with the errors occurred in the components used for the construction of the subpipelines (onProcess and onException). If you want the execution to be interrupted for any type of occurrence, consider using Do While.	False	Boolean

JSON Path Expression Examples

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

The expression above shows how the message received by the component 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 products that's inside the received message body.

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 components are used to manipulate the data of each array element in the For Each subpipeline and the Parallel Execution option is enabled, it's necessary for the Scoped option from Session Management to be enabled so 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 component causes an error in the pipeline when the assertion condition isn't met. Other error situations occur when components 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 components 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 component 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 has an array. If the array isn't the root of the object, then a JSON Path expression must be defined to locate and filter the array. If For Each doesn't receive any array, no processing will be executed.

Output

{
    "total": 0,
    "success": 0,
    "failed": 0
}

• 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.