Use a Loop Step

Loop steps allow you to execute a series of steps within a loop.

Configure a Loop Step

To add a loop to your workflow:

1. Give the loop a name and description.
2. Choose the type of loop to use.
   • "Repeat Over" loops iterate over a finite collection of items and executes the loop for each of those items.
   • "Repeat Until" loops execute the loops for a configured number of times, at specific time intervals
3. Configure the loop type details.
   • For "Repeat Over" loops, choose which input variable contains the data set you'd like to iterate over.
   • For "Repeat Until" loops, first define the number of times you want the loop to run, then configure the "Repeat Delay," or the length of the time interval between each loop execution. Then choose the unit of time to run for the length you provided, out of seconds, minutes, or hours.
4. Click Save Step and Enter Loop. This will take you to a new workflow builder canvas that only shows steps for your loop.
5. Add steps to iterate over, just like you would when adding steps to the master workflow.
   • Within loops, your input variables will include [<Loop Name>].[$item] by default. You can add more input from your workflow's previous steps as needed, but steps that access variables from each loop iteration require the $item default variable.
6. If needed, add a Break Loop Step, which acts like a Filter Step to exit the loop if the filter conditions are met. Without a Break Loop Step, the loop will keep executing until it completes iterating over a "Repeat Over" collection or the required number of "Repeat Until" executions.
7. To collect data from inside the loop to use in steps following the loop, add Loop Outputs on the 2nd page of the configuration panel. To learn more about setting up loop outputs, read the following section.

Access Loop Data

There are several ways to access loop data.

Accessing Items in a Repeat Over Loop

With the “Repeat Over” loop type selected, the steps inside the loop run for each item in the input array that you’ve selected.

The current array item the loop is operating on is stored in an $item variable for use within the loop. To access the data for the current iteration, use [Loop Name].[$item] as the variable for steps requiring the current iteration’s array item.

If your input is an array of objects with additional data in keys, use the ["Loop Name"].[$item].[key name] format to access object data.

Accessing Loop Output Variables in Future Steps

Outside of the loop, you may use a Loop Output Variable just like you would any step variable. Click the [+] on another step downstream from the loop, select the loop step, and click your output variable name to add it to an expression.

Using Break Output

When you use a Break Loop step, you can refer to content from the last run iteration in a simpler way using the ["Loop Name"].[$item] variable. You can only use ["Loop Name"].[$item] in steps after a loop if you use a Break Loop step to exit the loop.

Defining Loop Outputs

For all loop types, the best way to access results of your loop for later use is to define loop output variables.

From inside the loop

From outside of the loop

Hover over the loop step icon and click the edit (pencil) icon.

Adding a Loop Output

Once you are configuring the loop in the right-hand panel, you may add outputs on the 2nd page of the panel. You must have at least one step in your loop to define outputs.

Click “Add an Output” to set up the data you can access from this loop.

You can add up to 10 output variables that let you combine and collect data from each iteration or run of the loop. For example, an output variable might count all iterations where a match was found, or pull the output generated by a particular action into a new Array for later use.

This allows you to bring all the iterations of your loop together into a summary form that you can easily use in future steps.

Loop Output Types

There are 4 types of loop outputs, each giving you different combination and processing abilities.

Array

The Array output type makes the output variable a new array of items, which may include any data from within your loop, and may optionally be filtered to only entries for loop iterations that match a specified expression.

• Value to include in array: enter an expression for what data from the loop iteration will be added to the array (required)
• Only include if…: optionally, you can enter an expression that must evaluate to true in order to include the entry in the output array (optional)

Boolean

The Boolean output type evaluates a condition on every loop iteration, and determines a single Boolean (true or false) output value for the entire loop, if either all of the iterations match, or any of the iterations match.

• Output true if…: select whether the variable should be true on any iterations matching the expression, or all iterations matching the expression given (required)
• Matching expression: define the condition to match on each iteration (required)

Sum

The Sum output type lets you add up numbers within your loop iterations. The resulting value will be the sum of all the values for every loop iteration (required)

• Numeric value to add up: select a value (that must be a numeric type) to add up for every iteration of the loop.

Count

The Count output type allows you to count up matching iterations of your loop. The resulting value will be the number of loop iterations matching the given expression.

• Count loop runs that match…: an expression (true or false) that will be evaluated for each loop iteration. If the expression is true for that iteration, the variable will be incremented by one. If it’s false, it won’t be incremented.

Loop $item Example Use Case

Consider a security process for provisioning a user for an organization that builds usernames on a first initial, last name format like @jdoe for Jane Doe, and builds extra aliased accounts for the same employee for different needs (like @jdoe1, @jadoe, etc). You would first need to check every alias against provisioned user data to find one that was not provisioned, then provision the alias in your preferred directory tool.

In InsightConnect, you can place the user lookup within a loop, feeding the list of Jane Doe’s usernames to the loop as an array of strings. To access the current iteration’s input data in a loop called “CheckUsername,” you would use ["CheckUsername"].[$item] within the input field for the lookup. To exit the loop when an unprovisioned username is found, you would add a “Break Loop” step with the condition that the lookup result for the current iteration was false`.

In steps following the loop, you can reference the discovered unique username with the same [Loop Name].[$item] variable format. This is useful for steps that might provision the alias or perform other operations to the discovered username.

Additional Resources

If you have further questions relating to InsightConnect, try starting a discussion in the Rapid7 Discuss community forum.

Related Posts

• Using Loops in Workflows