Using the Loop Native Action

17 min

The Loop native action in Swimlane Turbine enables orchestrators to apply one or more actions to each item in an array or object. This makes processing collections more efficient by iterating over each element and applying the necessary actions. Loops provide orchestrators with flexibility while maintaining clarity and control.

Overview

The Loop action provides a streamlined way to process arrays and objects by iterating through each element. This allows users to apply actions systematically, ensuring consistency and efficiency in handling repetitive tasks within workflows. Loops can iterate over arrays, objects, or strings, and provide access to iteration context (index, key, value) within the loop body.

Key Benefits of the Loop Action

Native Action: Easily accessible within the playbook builder.

Efficient Array Processing: Simplifies operations on arrays by automating repetitive tasks.

Flexible Integration: Works seamlessly with other actions and connectors in the playbook.

Supports Nested Arrays: Capable of handling complex data structures through nested loops.

Parallel and Sequential Processing: Offers asynchronous and synchronous processing options for forEach loops to suit different workflow requirements.

Conditional Iteration: Allows for conditional processing using while loops.

Nested loop depth: You can nest up to five loops inside a single playbook (one loop plus four nested levels).

Using the Loop Action

As an orchestrator, you may need to apply one or more actions to each item in an array or object. By using the forEach loop or while loop, you can process items efficiently. Loops allow you to:

Receive an array, object, or string as input and process each element using a playbook property or expression.

Access iteration context (index, key, value) within loop actions using $loop or $loops expressions.

Aggregate loop action outputs.

Process nested collections by using loops within loops.

Implement action branching where necessary.

Use the output array from a loop in downstream actions.

Accessing Loop Iteration Data

Within a loop, you can access the current iteration's data using expressions:

$loop.value - The current iteration's value (the array element or object value)

$loop.key - The current iteration's key (array index as string, or object property name)

$loop.index - The current iteration's numeric index (0-based)

For nested loops, use the $loops prefix with the loop action name:

$loops.loopActionName.value - Access the value from a specific nested loop

$loops.loopActionName.key - Access the key from a specific nested loop

$loops.loopActionName.index - Access the index from a specific nested loop

Example: If you have a loop iterating over ['apple', 'banana', 'cherry']:

First iteration: $loop.value = 'apple', $loop.key = '0', $loop.index = 0

Second iteration: $loop.value = 'banana', $loop.key = '1', $loop.index = 1

Adding Loops to a Flow

Open your playbook in the Turbine Canvas.

From the list of native actions on the left-hand panel, locate Loop action.

Drag and drop the Loop action into your flow.

Once added, the loop will appear as part of the flow, waiting for configuration.

Providing a Title and Description for the Loop

Adding a Title:

When you select the Loop action in your flow, the configuration panel will open.

Locate the Title field at the top of the panel.

Enter a descriptive title that reflects the purpose of the loop (for example, Process User Records or Iterate Over IP Addresses).

Adding a Description:

Below the Title field, you will find the Description field.

Use this field to provide additional details about the loop's purpose and function (for example, This loop processes each user record to validate login attempts).

Click the Contains sensitive data checkbox if you have any sensitive data.

Tip: Use meaningful and concise titles and descriptions to improve the readability and maintainability of your playbooks.

Types of Loops

There are two types of loops:

forEach Loops: These loops iterate over each item in an array, object, or string. There are two modes available:

Parallel forEach Loops: Actions are applied to items asynchronously, using inputs from a playbook property or expression. The collection is processed in parallel with a default maximum concurrency of 5 (configurable). However, output elements may not maintain their input sequence. Parallel loops are useful for independent operations that don't require sequential processing.

Sequential forEach Loops: Process items in sequence, one after the other, using inputs from a playbook property or expression. The output array maintains the input sequence. Sequential loops are useful when order matters or when operations depend on previous iterations.

while Loops: These loops iterate based on a condition and process items sequentially. A condition must be configured, and the loop continues until the condition evaluates to false. While loops support:

Condition: A boolean expression that determines whether the loop continues

Limit: Maximum number of iterations (default: 5000, configurable)

Duration: Maximum execution time in milliseconds

Delay: Delay between iterations in milliseconds (applied after the first iteration)

Configuring Loops

Configuring forEach Loops

Click on the Loop action to open its configuration panel.

Select forEach under the Type of Loop.

Choose the process type:

Sequential: Process items one by one in order. Output maintains input sequence.

Parallel: Process items asynchronously. Output may not maintain input sequence. Default maximum concurrency is 5 iterations at a time.

In the Configuration section:

Click Select Property or Expression to define the array, object, or string the loop will iterate over.

The loop can iterate over:

Arrays: Each element becomes $loop.value, with $loop.key as the index string

Objects: Each property value becomes $loop.value, with $loop.key as the property name

Strings: Each character becomes $loop.value, with $loop.key as the index string

Add actions or connectors inside the loop to apply operations to each element.

Use $loop.value, $loop.key, or $loop.index in expressions to reference the current iteration's data.

Configuring while Loops

Click on the Loop action to open its configuration panel.

Select while under the Type of Loop.

Click Edit Condition to define the loop condition using expressions, properties, or variables. The loop continues while the condition evaluates to true.

Configure loop limits (optional but recommended):

Limit: Set the maximum number of iterations (default: 5000). The loop will fail if this limit is exceeded.

Duration: Set the maximum execution time in milliseconds. The loop will fail if this duration is exceeded.

Delay: Set the delay between iterations in milliseconds. This delay is applied after the first iteration.

Add actions or connectors inside the loop to execute for each iteration.

Ensure actions within the loop modify variables or conditions that will eventually cause the condition to evaluate to false.

Test the playbook to ensure the loop exits correctly to prevent infinite loops.

Important: While loops will automatically exit if:

The condition evaluates to false

The iteration limit is reached (default: 5000)

The duration limit is exceeded (if configured)

Configuring the Loop After Setting the Condition

Once the loop condition is set, click the Configure button in the Configuration section.

Use the configuration panel to refine:

Inputs: Specify additional properties or expressions required by the loop.

Outputs: Define how the loop outputs should be used in downstream actions.

Test the playbook to validate the loop's behavior and ensure configurations are correct.

Best Practices

Define Clear Exit Conditions: For while loops, ensure the condition will eventually evaluate to false to avoid infinite loops. Use limit and duration settings as safeguards.

Use Appropriate Loop Types:

Use Sequential loops when order matters or operations depend on previous iterations.

Use Parallel loops for independent operations that can run concurrently.

Set While Loop Limits: Always configure a limit and/or duration for while loops to prevent infinite execution. The default limit is 5000 iterations.

Use Descriptive Variable Names: Use clear names for loop conditions and inputs to improve readability.

Minimize Actions Inside Loops: Keep the number of actions inside loops to a minimum to optimize performance, especially for parallel loops.

Access Loop Data Correctly: Use $loop.value, $loop.key, and $loop.index to access iteration data. For nested loops, use $loops.loopName.value.

Handle Loop Outputs: Be aware that parallel loops may not maintain input sequence in outputs. Use sequential loops if order is critical.

Test with Sample Data: Test loops with various data sizes and edge cases (empty arrays, single items, large arrays) to validate behavior.

Monitor Loop Execution: Use logging or debugging actions to monitor loop iterations and identify performance issues.

Consider Performance: For large arrays, consider using parallel loops for better performance, but be aware of concurrency limits (default: 5).

Configuring Actions Inside the Loop

Inside the loop, drag and drop the next connector/action to the plus icon to add it to the flow.

In the Automated Remediation playbook, a Script native action is used to filter top traffic sites. When the loop action is triggered, the forEach loop iterates over the specified items.

You can nest up to five loops inside one another. Deleting a loop will remove the entire loop, including all nested actions, connectors, and sub-loops.

You have successfully added and configured a loop. For more information on downstream outcomes after configuring loops, refer to the Automated Remediation playbook.

Advanced Examples

Example 1: Processing a List of IP Addresses

Scenario: Use the Loop action to apply a geolocation lookup to each IP address in an array.

Add a Loop action to iterate over the array of IP addresses.

Select forEach and Parallel mode for concurrent processing.

Configure the loop to iterate over $event.data.ipAddresses (or your array property).

Within the loop, add an HTTP Request action to perform a geolocation lookup using $loop.value as the IP address.

Access results using $actions.loopActionName.result in downstream actions.

Aggregate the results to display or use in downstream actions.

Note: Since this uses parallel processing, the results may not be in the same order as the input array.

Example 2: Nested Loops for Complex Data Structures

Scenario: Process nested arrays (e.g., list of user data, where each user has multiple roles).

Add an outer loop to iterate over users (e.g., $event.data.users).

Within the outer loop, add another Loop action to iterate over roles (e.g., $loop.value.roles).

Access data from both loops:

Current user: $loops.outerLoopName.value

Current role: $loop.value

User name: $loops.outerLoopName.value.name

Perform actions such as logging or applying permissions to each role.

Use variables to aggregate results if needed.

Note: You can nest up to 5 loops. Use descriptive loop names to make $loops references clear.

Example 3: Using a while Loop for Conditional Processing

Scenario: Monitor a task queue until all tasks are marked as "Completed."

Add a while Loop action to the playbook.

Set the condition to check if the task status is not "Completed" (e.g., $variables.taskStatus != 'Completed').

Configure loop limits:

Set Limit to 100 iterations (or appropriate value)

Set Duration to 5 minutes (300000 ms) to prevent infinite execution

Set Delay to 5 seconds (5000 ms) between status checks

Inside the loop, add an action to query the status of tasks and update the $variables.taskStatus variable.

The loop will exit when:

The condition evaluates to false (status becomes "Completed")

The iteration limit is reached

The duration limit is exceeded

Important: Always set limits and duration for while loops to prevent infinite execution.

Example 4: Processing Paginated API Responses

Scenario: Retrieve all pages of an API response and process each item.

Create a variable to store the next page token (e.g., nextPageToken).

Add a while Loop action to the playbook.

Set the condition to continue looping while the next page token exists (e.g., $variables.nextPageToken != null && $variables.nextPageToken != '').

Configure loop limits:

Set Limit to prevent excessive API calls (e.g., 50 pages)

Set Duration to prevent long-running loops

Set Delay if the API has rate limits

Inside the loop:

Add an HTTP Request action to fetch the current page using $variables.nextPageToken.

Process the items from the response.

Update $variables.nextPageToken with the next page token from the response.

The loop exits when there are no more pages or limits are reached.

Alternative Approach: Use a forEach loop with a nested while loop to process items within each page.

Troubleshooting

Infinite Loops: While loops can run indefinitely if the condition never evaluates to false. Always:

Set a limit (default: 5000 iterations)

Set a duration limit

Ensure actions within the loop modify variables that affect the condition

Test with sample data to verify exit conditions

Loop Fails with "Maximum iteration limit exceeded": The while loop has reached its maximum iterations (default: 5000). Either:

Increase the limit if appropriate

Fix the condition so it exits earlier

Review the logic to ensure the condition can become false

Loop Fails with "Duration exceeded": The while loop has exceeded its duration limit. Review the delay settings and loop logic.

Parallel Loop Output Order: Parallel loops may not maintain input sequence. Use sequential loops if order matters, or sort the output if needed.

Loop Variables Not Accessible: Ensure you're using the correct syntax:

Current loop: $loop.value, $loop.key, $loop.index

Nested loops: $loops.loopActionName.value

Variable names are case-sensitive

Performance Issues:

Too many actions inside loops can slow execution

Parallel loops have a concurrency limit (default: 5), so very large arrays may take time

Consider breaking large loops into smaller batches

Empty Array/Object: Loops over empty collections will complete immediately without executing loop body actions.

Common Pitfalls

Infinite loops caused by missing or improper exit conditions in while loops.

Performance bottlenecks with too many actions in parallel loops.

Incorrect configurations of input arrays, objects, or conditions.

Order dependency issues when using parallel loops where sequence matters.

Nested loop confusion when accessing variables from multiple loop levels.

Missing loop limits in while loops leading to excessive execution time.

Additional Resources

Click Automated Remediation Use Case for an example of using loops to automate remediation actions.