Processing Lists of Items with the ForEach Step

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

Example

In our example, we will:

  1. Collect a list of names with a form and submit them to our application.
  2. Break apart the list into individual names.
  3. 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.

Two forms, Input Collection and Display Individual Item, were created for this example. The Input Collection form is configured with a Text Area component, as follows:
 formForCollection
 
 
 
The Display Individual Item form is configured with a Label component, as follows:
 IndividualItemForm
 

Begin by navigating to a Designer Folder and clicking the Create Flow button.

createFlow

 

Name the flow and click OK to open the flow in the Flow Designer.

 
nameFlow 
Begin building the new flow by first adding the forms for entering user names and for displaying them, found in the Flow Designer’s startup window, in the category Flows, Rules, Forms and Reports > Forms [Interaction] > [Current Folder]. Select an Input Collection component. Click Add to add it to the workspace. Next, add a Display Individual Item component. 
flowStarts
 
To split the list of user names gathered in the [Form] Input Collection step into discrete user names, in the Data category, drag a Split String by New Line component to the workspace.
To process the list of names in the flow, In the Flow Management category, drag a ForEach component to the workspace.
dragAllComponents
 

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.

clickTypeSflForeach

 

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.

flowConnected

 

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 Split String by New Line 1, map CollectedNames to its input collection, source.
mappingToSplitString
 

For the step ForEach Step 1, map SplitStringByNewLine1_Output to its input collection, Collection.

mappingForEach

 

For [Form] Display User Names, map Item to its input collection, names.

mappingToEndForm

 

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.

3.5 Test Flow Shot

We are presented with a form where we can list the names we’d like to add to our collection.

debugEnterList

 

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.

debugResult2

 

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.

debufDiagram

 

 

Additional Resources