Looping activities allow you to repeat a set of activities a fixed number of times or until a condition is met. Every looping activity has a subworkflow where you configure the set of activities to repeat.

VertiGIS Studio Workflow has two looping activities, Loop and For Each. The Loop activity is used for repeating a set of activities until an external condition is met, for example, the user says to stop. The For Each activity is a specialized looping activity that steps through a collection one item at a time. We recommend using the For Each activity whenever possible.

Use the For Each Activity

The For Each activity is used to step through each item in a collection. This allows you to perform some action on each item, one at a time. The activity exits after it has operated on the last item in the collection.

To configure a For Each activity, you set the Items input to the collection that you want to step through, and then create the subworkflow that will run for each item. The items can be any type, for example, they could be numbers, strings, or objects, including features.

Typically, the For Each subworkflow examines or updates the item that the activity is currently operating on. You can access the current item in the subworkflow using the item output. To access the item output, use a term similar to $forEach1.item in an expression.

Another use for the For Each activity is to step through the keys in an object. In this case, instead of passing in a collection as input, you pass in an object. For example, you could pass in a feature and step through the feature's attributes. The key output provides the name of the current attribute.

In some circumstances, you may want to exit a For Each activity before it has operated on every item in the collection. For example, if you use a For Each activity to find a particular item, you could exit the activity after you have found the item. For more information, see Exit a Looping Activity.

The following examples illustrate how to use the For Each activity with collections:

▪Example 1 - Step Through the Items in a Collection illustrates how to use a For Each activity to step through every item in a collection, operating on each item.

▪Example 2 - Find a Particular Item in a Collection illustrates how to use a For Each activity to find a particular item in a collection, store the item so it is available in the main workflow, and then exit the For Each activity.

See also...

Example - Step Through the Features Returned by a Query

Example - Find a Particular Feature Returned by a Query

Example 1 - Step Through the Items in a Collection

This example shows you how to use a For Each activity to step through a collection of objects. The objects are roads.

The collection is defined manually using a Create Value activity in the main workflow. The For Each subworkflow uses an Alert activity to display the pass output and some of the current item's values, so you can watch the activity step through each item. The pass output counts the number of loops, starting at zero.

 

Workflow Logic

The workflow has the following activities, in the order shown:

▪Create Value (value1): Create the collection of items to step through.

▪For Each (forEach1): Step through each item in the collection, running the subworkflow for each item, until the end of the collection is reached.

The subworkflow has the following activity:

•Alert: Display some of the item's values so you can watch the For Each activity step through each item.

 

Open the Workflow

https://latitudegeo.maps.arcgis.com/home/item.html?id=1eea36c566884789bd6cbd978553d8ab

To open the completed workflow in Workflow Designer, copy the workflow's URL given above, click File | Open by URL in Designer, paste in the URL, and click Open. When you are asked whether you want to open a copy of the workflow, click OK.

To step through each item in a collection:

1.Open Workflow Designer.

2.In a new, blank workflow, add the following activities and connect them in the given order:

▪Create Value (value1)

▪For Each (forEach1)

3.Create Value (value1): Set the Create Value activity's Expression input to an expression that defines a collection of objects, for example:

=[

{ name: "Main", designator: "Street", type: "Municipal", zoning: 5, registered: true },

{ name: "Frontage", designator: "Road", type: "Municipal", zoning: 2, registered: false },

{ name: "Coast", designator: "Highway", type: "Provincial", zoning: 1, registered: null }

]
To access this collection, use the term $value1.result.

4.For Each (forEach1):

▪Set the Items input to: =$value1.result
This makes the For Each activity operate on the items in the collection that you created.

▪Double-click the For Each activity to open its subworkflow.

▪Add the following activity:

▪Alert: Set the Text input to a string that includes the values you want to display, for example:

="Pass " + $forEach1.pass + ": " + $forEach1.item['name'] + " " + $forEach1.item['designator']

▪Click Start in the breadcrumbs to return to the main workflow.

5.Run the workflow in the Sandbox.
The subworkflow runs once for each item, starting with the first item (). Click OK to close the alert and proceed to the next item ().

Alert in a For Each subworkflow that displays values for the current item
 

6.Press Ctrl+S to save the workflow.

Example 2 - Find a Particular Item in a Collection

To find a particular item in a collection, use a For Each activity to step through and examine each item until you find the item you want. Then, if you need to do something quick like display the item, you can do that directly in the For Each subworkflow. If, however, you need the item to be available later in the workflow, you can use a Create Value activity to pass the item or its index back to the main workflow. After that, you can exit the For Each activity. This prevents the For Each activity from doing any unnecessary processing.

This example shows you how to use a For Each activity to find a particular item in a collection of objects. The objects are provinces in the Netherlands. The example finds the Gelderland object and displays the province's name and capital city.

The collection is defined manually using a Create Value activity. To find the Gelderland object, the For Each subworkflow has an If activity that compares the name of the current item to "Gelderland". If the current item matches, the subworkflow does the following:

▪It makes the For Each activity's Exit input true so the For Each activity exits when it steps to the next item.

▪It stores the Gelderland object so the object can be used later in the main workflow.

Workflow Logic

The workflow has the following activities, in the order shown:

▪Create Value (value1): Create an intermediate value to control exiting the For Each activity. Set it to false.

▪Create Value (value2): Create the collection of objects.

▪For Each (forEach1): Check each item in the collection one at a time, running the subworkflow for each item, until you find the item you want or the end of the collection is reached.

The subworkflow has the following activities:

•If: Check whether the current item is the item you want.

If you found the item:

•Evaluate Expression: Set the intermediate value to true.

•Create Value: Store the item so you can use it in the main workflow.

▪Alert: Display some of the item's values so you can verify that the workflow found the correct item.

Open the Workflow

https://latitudegeo.maps.arcgis.com/home/item.html?id=6487404c1c7d40389efc25ceb17f228f

To open the completed workflow in Workflow Designer, copy the workflow's URL given above, click File | Open by URL in Designer, paste in the URL, and click Open. When you are asked whether you want to open a copy of the workflow, click OK.

To find a particular item in a collection:

1.Open Workflow Designer.

2.In a new, blank workflow, add the following activities and connect them in the given order:

▪Create Value (value1)

▪Create Value (value2)

▪For Each (forEach1)

▪Alert

3.Create Value (value1): Set the Expression input to: =false
The Exit input will depend on this value, so this makes Exit false.

4.Create Value (value2): Create the collection by setting the Expression input to an expression that defines a collection of objects, for example:

=[

{ province: "South Holland", capital: "The Hague", area: 2860, coastal: true },

{ province: "North Holland", capital: "Haarlem", area: 2660, coastal: true },

{ province: "Utrecht", capital: "Utrecht", area: 1356, coastal: false },

{ province: "Limburg", capital: "Maastricht", area: 2167, coastal: false },

{ province: "North Brabant", capital: "Hertogenbosch", area: 4938, coastal: false },

{ province: "Gelderland", capital: "Arnhem", area: 4995, coastal: false },

{ province: "Overijssel", capital: "Zwolle", area: 3337, coastal: false },

{ province: "Flevoland", capital: "Lelystad", area: 1426, coastal: true },

{ province: "Groningen", capital: "Groningen", area: 2344, coastal: true },

{ province: "Zeeland", capital: "Middelburg", area: 1792, coastal: true },

{ province: "Friesland", capital: "Leeuwarden", area: 3361, coastal: true },

{ province: "Drenthe", capital: "Assen", area: 2652, coastal: false }

]
To access this collection, use the term $value2.result.

5.For Each (forEach1):

▪Configure the inputs:

▪Items: =$value2.result
This makes the For Each activity operate on the items in the collection that you created.

▪Exit: =$value1.result
This makes the Exit input depend on the intermediate value, so when the intermediate value becomes true, Exit also becomes true.

▪Double-click the For Each activity to open its subworkflow.

▪Add the following activities and connect them in the given order:

▪If

▪Evaluate Expression: Connect this activity to the If activity's True branch.

▪Create Value (value3): Connect this activity to the Evaluate Expression activity.

▪If: Set the Condition input to: =$forEach1.item.province == "Gelderland"
This compares (==) the current item's province ($forEach1.item.province) to the province you are looking for ("Gelderland").
For information about the == operator, see Comparison operators.

▪Evaluate Expression: Set the Expression input to: =$value1.result = true
This sets the intermediate value to true, which makes the Exit input true, so the For Each activity will exit at the beginning of the next loop.
In the Expression input =$value1.result = true, the first "=" signals to VertiGIS Studio Workflow that what follows is an expression. In this case, the expression is $value1.result = true. The second "=" assigns the right side of the expression (true) to the left side of the expression ($value1.result).

▪Create Value (value3): Set the Expression input to: =$forEach1.item
This allows you to pass back the item to the main workflow. You will access the item using the term $value3.result.

▪Click Start in the breadcrumbs to return to the main workflow.

6.Alert: Set the Text input to a string that includes the values you want to display, for example:
="The capital of " + $value3.result['province'] + " is " + $value3.result['capital']
 

7.Run the workflow in the Sandbox.
The following alert displays:

Alert in the main workflow after locating the Gelderland item in the collection
 

8.Press Ctrl+S to save the workflow.

Get the Index for a Particular Item in a Collection

If you specify a collection as the input to the For Each activity, then you can use the pass output to get the index of the current item. The pass output counts the number of times that the For Each activity has looped, starting at 0 for the first item in the collection, 1 for the second item, 2 for the third item, and so on. If you created the collection using a Create Value activity, then the items in the collection are indexed starting at 0, so the item's index is the same as the value of pass.

The pass output will be undefined when you return to the main workflow, so you will not be able to access it. To pass it back to the main workflow, add a Create Value activity and set its Expression input to an expression similar to =$forEach1.pass. You will be able to access the index in the main workflow using an expression similar to $value2.result.

Use the Loop Activity

The Loop activity is useful for repeating a set of actions until some external condition becomes true. For example, you could repeat some actions until the user says to stop. You use the Exit input to force the activity to exit. For more information, see Exit a Looping Activity.

The Loop activity also has a Limit input that allows you to set an upper limit on the number of times the activity can loop, in case the user never says to stop. This prevents the activity from looping endlessly.

Example - Loop until the User Says to Stop

This example shows you how to use a Loop activity to repeat a set of actions until the user says to stop. The workflow builds a collection of names entered by the user.

You will use a Prompt activity to get names from the user and a Confirm activity to ask if the user wants to enter another name. If the user clicks OK in the Confirm dialog box, you will continue looping and prompt for another name. If the user clicks Cancel, you will exit the Loop activity.

 

Workflow Logic

The workflow has the following activities, in the order shown:

▪Create Value (value1): Create an intermediate value to control exiting the Loop activity. Set it to false.

▪Create Value (value2): Create an empty collection to add names to.

▪Loop (loop1): Set a limit on the number of times to loop. Get names from the user until the user says to stop or the limit is reached.
The subworkflow has the following activities:

•Prompt (prompt1): Get a name from the user.

•Add Item: Add the name to the collection.

•Confirm (confirm1): Ask whether the user wants to enter another name.

•If: Check the user's response.
If the user said to stop entering names:

•Evaluate Expression: Set the intermediate value to true.

▪Log: Log the collection to the browser's console so you can verify it.

 

Open the Workflow

https://latitudegeo.maps.arcgis.com/home/item.html?id=86bcb2e5d25c41e2a4866b3fa295356c

 

To open the completed workflow in Workflow Designer, copy the workflow's URL given above, click File | Open by URL in Designer, paste in the URL, and click Open. When you are asked whether you want to open a copy of the workflow, click OK.

To repeat a set of actions until the user says to stop:

1.Open Workflow Designer.

2.In a new, blank workflow, add the following activities and connect them in the given order:

▪Create Value (value1)

▪Create Value (value2)

▪Loop

▪Log

3.Create Value (value1): Set the Expression input to: =false
The Exit input will depend on this value, so this also makes Exit false.

4.Create Value (value2): Set the Expression input to: =[]
This creates an empty collection to accumulate the names that the user enters.

5.Loop:

▪Configure the inputs:

▪Exit: =$value1.result
This makes the Exit input depend on the intermediate value, so when the intermediate value becomes true, Exit also becomes true.

▪Limit: =5
This prevents the activity from looping more than 5 times.

▪Double-click the Loop activity to open its subworkflow.

▪Add the following activities and connect them in the given order:

▪Prompt (prompt1)

▪Add Item

▪Confirm (confirm1)

▪If

▪Evaluate Expression: Connect this activity to the If activity's True branch.

▪Prompt: Set the Description input to string that prompts the user, for example: ="Enter a name"

▪Add item: Configure the inputs:

▪Collection: =$value2.result
This specifies the collection for the Add Item activity to add names to.

▪Item: =$prompt1.result
This makes the Add Item activity add the name that the user just entered.

▪Confirm: Set the Text input to a string that asks if the user wants to continue: ="Do you want to enter another name?"

▪If: Set the Condition input to: =$confirm1.result === false
This compares (===) the user's answer ($confirm1.result) to false. The Confirm activity's result output is false when the user clicks the Cancel button, indicating that it is time to stop looping.
For information about the === operator, see Comparison operators.

▪Evaluate Expression: Set the Expression input to: =$value1.result = true
This sets the intermediate value to true, which makes the Exit input true, so the For Each activity will exit at the beginning of the next loop.
In the Expression input =$value1.result = true, the first "=" signals to VertiGIS Studio Workflow that what follows is an expression. In this case, the expression is $value1.result = true. The second "=" assigns the right side of the expression (true) to the left side of the expression ($value1.result).

▪Click Start in the breadcrumbs to return to the main workflow.

6.Log: Set the Message input to a string containing the values you want to log, for example: ="The names are: " + $value2.result

7.Follow the instructions in the workflow to enter some names, for example, Lee, Quin, and Gerry.

8.Run the workflow in the Sandbox.

9.Press F12 to open the console. Expand the entry for the Add Item activity in the final loop.

▪ shows the verbose log entry for the collection built by the workflow.

▪ shows the entry produced by the Log activity.

Log entries for a collection built using a Loop activity, shown in the Chrome console
 

10.Press Ctrl+S to save the workflow.

Exit a Looping Activity

Looping activities must have some condition that causes them to exit so they don't loop endlessly. For the For Each activity, the condition is built in—the activity exits when there are no more items in the collection to step through. For the Loop activity, you should set a limit on the number of times the activity can loop, so the activity exits if the limit is reached.

In addition, both looping activities have an Exit input that allows you to force the activity to exit early. For example, if you use a For Each activity to find a particular item, you can force the activity to exit once the item is found. If you use a Loop activity to repeat some actions until the user says to stop, you can force the activity to exit when the user says to exit.

To use the Exit input, you make Exit false initially. As long as Exit remains false, the activity continues looping. When Exit becomes true, the looping activity exits and the workflow continues running at the next activity.

You cannot directly assign a value to the Exit input at run time. Instead, you must use an intermediate value created using a Create Value activity.

To use an intermediate value to exit a looping activity:

1.Add a Create Value activity before the looping activity and set its Expression input to false.
The intermediate value is the Create Value activity's result output, for example, $value1.result.

2.Set the looping activity's Exit input to the intermediate value.
This makes the value of Exit depend on the intermediate value. While the intermediate value is false, Exit is false. When the intermediate value becomes true, Exit becomes true.

3.In the looping activity's subworkflow, check whether it is time to exit.
For example, if you are using a For Each activity to find a particular item, you would exit when you have found the item you want. In a Loop activity, you would exit when the user says to stop or some other external condition is met.
If it is time to exit, set the intermediate value to true. To do this, add an Evaluate Expression activity to the subworkflow and set its Expression input to =$value1.result = true. This causes Exit to become true, which causes the looping activity to exit at the beginning of the next loop.
In the Expression input =$value1.result = true, the first "=" signals to VertiGIS Studio Workflow that what follows is an expression. In this case, the expression is $value1.result = true. The second "=" assigns the right side of the expression (true) to the left side of the expression ($value1.result).