IMPORTANT: This documentation has been discontinued. Read the updated For Each documentation on our new documentation portal.
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.