Using the Iterator in an Activity

When creating a flow, you may want to iterate a certain piece of logic multiple times. For example, you may want to send an email to multiple people based on the output of a certain activity (let's call it activity1) in your flow. You can do this by adding a SendMail activity following activity1 in your flow and configure the SendMail activity to iterate multiple times when activity1 outputs the desired result. Each iteration of the SendMail activity is used to send an email to one recipient. This saves you the effort of creating multiple SendMail activities.

Keep the following in mind when using the Iterator feature:

Iteration is supported for an activity only. You configure the iteration details in the Iterator tab of the activity.
There are certain activities that inherently do not require iteration, for example the Return activity whose purpose is to exit the flow execution and return data to the trigger. The Iterator tab is not available in such activities.
You cannot iterate through a trigger.
For apps that were created in Project Flogo™ and imported into TIBCO Cloud Integration- Flogo (PAYG), the key type in the Iterator tab is converted from string to relevant data type of value in TIBCO Cloud Integration- Flogo (PAYG).

To configure multiple iterations of an activity, do the following:

Procedure

Click the activity in the flow to expose its configuration tabs.
Click the Iterator tab.
The input tree is displayed with a single property, iterator, which is a mandatory field if you want to set up the activity for iteration.
Click iterator to open the mapper to its right.
Set the expression for the iterator by either entering the expression manually or mapping the output from the preceding activities or trigger. You can also use available functions along with the output from previous activities and/or manually entered values to form the iterator expression. The iterator expression determines the number of times the activity iterates.

Important: The iterator expression must either return a number or an array. The array can be of any data type. Currently, you cannot iterate through an object so the array expression cannot either be an object or return an object. If your iterator expression returns a number, for example 3, your activity will iterate three times. If your iterator expression returns an array, the activity will iterate as many times as the length of the array. You can hover over the expression after entering the expression to make sure that the expression is valid. If the expression is not valid, you will see a validation error pop up.

After you enter the iterator expression, the iterator icon appears on the top right corner of the activity leaf as follows:

If an activity has been set up for iteration, the Input tab of the activity displays the $iteration scope in the output area of the mapper. It contains two properties, key and value. key is used to hold the index of the current iteration and value holds the value that exists at the index location of the current iteration if the iterator expression evaluates to an array. If the iterator expression evaluates to an array of objects, value also displays the schema of the object. If the iterator expression evaluates to a number, the value will contain the same integer as the key for each iteration. To examine the result of each iteration of the activity, you can map key and value to input properties and use the LogMessage activity to print the key and value. However, you can map only to the output of the last iteration. Mapping to the output of an intermediate iteration is currently not supported.