Processing Lists of Items with the ForEach StepLast Updated: 08/18/2016 Introduced in Verision: 2.0
The ForEach component passes individual items from a collection to a flow loop which performs the same actions on each item. When every member has been processed, the loop forwards the finished collection to any subsequent steps outside of the loop.
You can find the ForEach Step component in the Toolbox panel in the Flow Designer, under Flow Management.
In our example, we will:
- Collect a list of names with a form and submit them to our application.
- Break apart the list into individual names.
- For each name in the collection, display the name in a form.
For the purposes of our example, each name is shown in a form because if we were to display the names as pages or raw output, the display steps would happen so fast we wouldn’t be able to see them. Forms are designed to await input from the user, most often in the form of a button press to submit the form’s data. You don’t have to use forms in your ForEach loops for them to work properly.
Begin by navigating to a Designer Folder and clicking the Create Flow button.
Name the flow and click OK to open the flow in the Flow Designer.
The ForEach step needs to know the data type of items it will process. Select the ForEach step and, in the Properties panel, under Collection, click the Type selector.
Since the ForEach step will be processing user names which are strings, select String and click OK.
Next, draw the outcome path of our flow through each of our steps. First, the form will collect our list of names and passes that in to the flow. The flow will break apart this list into individual names. The output of the first form in its current state is a single string of names, each separated by an invisible new line character. Split String by New Line lets us use these new line characters as breaking points to create multiple strings from the single string outputted by [Form] Input Collection.
The next step of our flow is drawn from [Form] Input Collection to Split String by New Line 1.
Once our list of names is broken up, it is necessary to display each name in a form. If we were to draw our path directly from Split String by New Line 1 to [Form] Display User Names, we would direct all of our names as a single output to just one form. Instead, [Form] Display Individual Item will display each name separately, and enable the user to click a button to display the next name in the list on the form. To place [Form] Display Individual Item within a loop controlled by ForEach Step 1, draw our path from Split String by New Line 1 to ForEach Step 1.
When we’re ready to draw our path from ForEach Step 1 to [Form] Display Individual Item, there is a choice; ForEach Step 1 allows for two different exit states: Done and Next. Done is the path we will want to use after every name in our collection has been processed, so we can draw this path to our end step. This leaves Next as the path we’ll use to build our ForEach loop. An exit state of Next means that until the collection is empty the next item should be passed as output to the steps along that path.
Once we’ve used the Next path to connect ForEach Step 1 to [Form] Display Individual Item, direct our flow back to ForEach Step 1 so that it can continue processing the rest of our collection.
Now that our flow diagram is completed, update the input mappings for all of our steps expecting input. Do this by selecting each step in turn and, in the Properties pane, clicking Show Mapping Editor.
For the step ForEach Step 1, map SplitStringByNewLine1_Output to its input collection, Collection.
For [Form] Display User Names, map Item to its input collection, names.
This completes our flow; save it and run it in the Debugger.
Note that in Decisions version 3.5 and above, you’ll need to click on Test Flow to access the Debugger.
We are presented with a form where we can list the names we’d like to add to our collection.
Once we’ve submitted our names, our application will present us with a new form that’s been populated with the first name on our list.
Each time we click the button, our flow presents another form containing the next name on the list.
When every name our list has been processed by ForEach Step 1, it returns the outcome Done, and our flow is at an end.