Workflow Triggers and Actions - For Each Collection Element Action
The For Each Collection Element Action is a special action in Flux that allows you to loop over a collection of data (for example, a Set, List, or Map) and pass each element of the collection, one item at a time, into the flow context. Typically this action is used to iterate through a collection of results returned by a previous action and pass the result along to be used by subsequent actions and triggers.
Properties
Loop Index
Specifies the name of the flow context variable that will be used to store each element of the collection that is being iterated over. The default value is “i”.
Each time a flow enters the For Each Collection Element Action, the action gets the next element of the collection (the first execution will retrieve the first collection element, the second execution retrieves the second element, and so on). This element is then placed into a flow context variable, whose name is specified by the loop index.
So, for example, if the For Each Collection Element Action was iterating over a collection of integer values, and the loop index was set to “i”, then each integer in the collection could be obtained from the flow context variable named “i”.
You can then access that value using Variable Substitution or by Using the Flow Context Java APIs to retrieve the value.
Results
The For Each Collection Element Action returns its results in two flow context variables: “result”, and a variable whose name is determined by the loop index. The “result” variable is a boolean value indicating whether there are any more results available, while the loop index variable contains the current item being iterated over in the collection. You can access the result from the following fields:
| Flow Context Variable | Java Type | Description | Prescript / Postscript Example |
|---|---|---|---|
| RESULT | boolean | Indicates whether there is still more data to process. If this value is true, then the action’s collection element contains more elements to iterate over; if this value is false, then the end of the collection has been reached. By default, any flow you create from the For Each Collection Element Action will have the condition “RESULT.result”, meaning that the flow will only be followed if there is still data to iterate over. If you create a flow with the else condition or the condition “NOT RESULT.result”, then the action will only follow that flow when there is no more data in the collection. This is useful for continuing on in the workflow once you have processed the last element in the collection. It is not appropriate to use an unconditional flow with the For Each Collection Element Action. Unconditional flows will cause unexpected behavior in the workflow (for example, the action may repeatedly loop over the same set of data without exiting). All other types of flows can be used with the For Each Collection Element Action. | boolean result = flowContext.get("RESULT"); System.out.println("More Results? " + result); |
| <Loop index setting> | Object | The current item in the collection. The name of the variable depends on the value specified for the loop index on the action; by default, the variable is named “i”. | Object currentItem = flowContext.get("i"); System.out.println("Current Item: " + currentItem); |
Passing Results with a Runtime Data Map
You can use a Runtime Data Map to copy the result field into a new variable (for future reference or to reuse the data later in the workflow).
To copy the result, you can use a data map like:
Resetting a Collection after the First Run
When the For Each Collection Element Action runs, it stores all the values from its collection in the database (whether the action runs using data generated at runtime or data that is statically defined in the workflow design). As the action runs, it removes each item from the database as it iterates over that item, to prevent the engine from repeatedly using the same data.
This means that if you are using a static value for the collection (that is, your collection value is not generated at workflow runtime), and you want the action to start over from the beginning of the collection again at some point in the workflow, you will need to store a separate copy of the collection somewhere outside of the action. This will allow the action to access the original connection later on (since the action only stores the data it has not yet operated on, and not an original copy of the map, it is not possible for the action to reconstruct the original collection).
The best way to do this is to use a workflow variable to store the collection, then use a runtime data map on a flow going into the For Each Collection Element Action to pass the variable to the action each time it should start over with the collection.
Transaction Breaks
It is important to consider the effects of transactions breaks on a For Each Collection Element Action. If an error occurs that causes Flux to roll back to the last transaction break, and Flux had not finished processing all of the data in the collection, then the roll back will cause Flux to move back to the beginning of the collection and start over.
The best way to avoid this is to set the For Each Collection Element Action itself as a transaction break - that way, if a rollback occurs, only the current item in the collection will be re-executed (rather than the entire collection).