Processing Lists of Items using ForEach Step

Last Updated: 12/05/2018 Introduced in Version: 2.0

The For Each Step passes individual items from a collection to a flow loop. The flow loop will then perform the same actions on each item. When every item has been processed, the loop forwards the finished collection to any subsequent steps outside of the loop.

You can find the For Each 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 purpose of our example, each name is shown in a form. 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 wait for an input from the user. This input data is sent from the form by means of an action button. You don’t have to use forms in your For Each loop 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 Box Multi Line component.
 
collectednameslist 
The Display Individual Item form is configured with a Label component.
 
individualitemlabel

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.

 
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 the Input Collection form. Click Add to add it to the workspace. Next, add the Display Individual Item form. 
 
 
The Input Collection form will provide us with discrete user names. We want to split these discreet names in the Data category, drag a Split String by New Line component to the workspace. In the Flow Management category, drag a For Each Step component to the workspace. This will be used to process the list of names in the flow.
 
 

The For Each Step needs to know the data type of items it will process. Select the For Each Step and, in the Properties panel, under Data, click the Type selector.

 

The For Each Step will be processing user names. Since these user names 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 pass them into 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 allows us to use the new line characters as breaking points to create multiple strings from the single string outputted by the Input Collection form. 

The next step of our flow is drawn from Input Collection to Split String by New Line.

Once our list of names is broken up, it is necessary to display each name on a form. If we were to draw our path directly from Split String by New Line to Display User Names, we would direct all of our names as a single output to one form. Instead, the Display Individual Item form will display each name separately, and enable the user to click a button to display the next name in the list on the same form. To place Display Individual Item form within a loop controlled by For Each Step, draw our path from Split String by New Line to For Each Step.

Drawing our path from For Each Step to Display Individual Item form requires us to make a choice. The For Each Step 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. We can draw this path to our end step. The Next path will be used to create our for each 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 the For Each Step to Display Individual Item form, direct our flow back to ForEach Step 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 Split String by New Line, map CollectedNames to its input collection source.

For the step For Each Step, map Split String By New Line_Output to its input collection, Collection.

For the Display User Names form, map Item to its input collection, Individual Item.

This completes our flow; save it and run it in the Debugger.

Note that in Decisions version 4.0 you will need to click on Debug 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 For Each Step, it returns the outcome Done, and our flow is at an end.

Additional Resources