Array Iterators
Array iterators provide a mechanism for looping through data values within arrays. A common example is the line items within an order.
Array iterators are unlike programming loops in that there is no variable with a starting value being incremented until an ending value or criteria is met. Iteration is performed for as many times as the largest array emitted by action configured for iteration.
Let's walk through a simple example. We will use this action to emit an array of 3 values consisting of 'first', 'second', and 'third':
Array iterators are added by clicking on a "plus" icon and choosing the option:
Click the action field and select the action:
Within the iterator we'll add a Transform Data action convert those three array elements to uppercase:
The input value to uppercase will be the array output from the first action:
When the automation runs, the Array Iterator makes 3 iterations and uppercases the output from the first action:
Iterators can contain conditional branches and other nested iterators as needed.
The scope of an Array Iterator is its selected action, which the iterator investigates at runtime to determine the largest array emitted. It then iterates that many times, once for each element of the largest array. For each iteration, any mapped array fields are accessed in succession.
A common source of trouble is if other actions having array output are mapped to items within the iterator. If those mapped actions emit arrays that are mapped then the automation execution engine also processes them in the same manner when field mappings are substituted. But if the other actions have larger arrays than the iterator's selected action, those extra array elements won't be processed. So always remember that the largest array emitted by the iterator's selected action is what controls the number of iterations and the subsequent processing of array elements within the iterator.
