For Each makes a loop inside a JSON structure, processing each element of the array in a subpipeline.

Take a look at the configuration parameters of the component:

  • 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 receival only of the ones who attend a specific condition.

  • Element Identifier: unique element that identifies the line under processing (eg.: "id" element).

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

  • 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. Click here to read about this component and check if it applies to your scenario.

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.

IMPORTANT: if Session 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 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 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:

Click here to better understand how subpipelines work.

Use scenarios of the For Each component with errors handling

Enabled "Fail on Error" property and no subpipeline defined in onException

  • the pipeline will be immediately interrupted

  • an error will be thrown from For Each

  • no other component will be invoked after For Each

Enabled "Fail on Error" property and a subpipeline defined in onException

  • the pipeline will be immediately interrupted

  • the subpipeline defined in onException will be executed and its output will feed the component that follows For Each

  • the component that follows For Each will be invoked

Disabled "Fail on Error" property and no subpipeline defined in onException

  • the iteration where the error occurred will be interrupted

  • a standard error message will be informed in the input of the next iteration and the loop will keep being normally executed

Disabled "Fail on Error" property and a subpipeline defined in onException

  • the iteration where the error occurred will be interrupted

  • the subpipeline defined in onException will be executed and its output will feed the next iteration

  • the loop will keep being normally executed

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

IMPORTANT: 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.

Did this answer your question?