Parallel Loop Node

Overview

A parallel loop is a node in the workflow builder that repeats a set of steps once for every item in a list, running several items at the same time. It's how a workflow handles work like "do this for every piece of equipment on an order" without building the same steps over and over.

In this article, we'll be covering what parallel loops are, when to use them, how they work, how to configure them, and how to troubleshoot common issues.

Understanding when to use a parallel loop

Parallel loops are the right choice when you have a list of items and want to take the same actions on each one.

Use a parallel loop when:

• You need to action an array of customers or accounts
• You need to provision a list of equipment
• You need to work through the procedures on a work order
• You want to process items at the same time rather than one after another

Use a While Loop instead when:

• You don't know ahead of time how many repetitions you need
• You need to page through a large dataset or retry an action until it succeeds

Quick guide: "Do this for each item in this list" → use a parallel loop. "Keep going until we're done" → use a while loop.

Understanding how a parallel loop works

A parallel loop wraps a group of nodes, called the loop body. The body runs once for every item in the list. We call each run an iteration.

1. The loop reads its Iterable, the list of items to loop over.
2. gaiia creates one iteration for each item and starts them in groups. No more than the Max concurrent iterations value run at once.
3. Each iteration runs every node in the loop body in order, working on its own item.
4. As iterations finish, the next ones start until every item has been processed.
5. Once all iterations finish, the workflow continues to the node after the loop.

Working with the current item

Each iteration has access to the item it is processing. Inside the loop, read it with state.currentParallelLoopIterations using your loop's slug:

const item = state.currentParallelLoopIterations['your-loop-slug'];

Iterations don't share data with each other. Each one starts from the same workflow state plus its own item.

When the list is empty

An empty list isn't an error. The loop skips its body and the workflow continues to the next node.

When an iteration fails

If one item fails, the other items keep running. Once every iteration has finished, the loop is marked as failed so you can see that something needs attention. One bad record doesn't stop the rest of the batch.

Configuring the parallel loop node

The parallel loop has one input and two optional settings.

Iterable

The list of items to loop over, required. This is usually a value from an earlier node, such as the equipment returned by a previous step. The field expects an array and opens as a TypeScript function by default. Use the selector next to the field to switch how the value is provided, including a state input.

Max concurrent iterations

How many iterations can run at the same time. The value must be between 1 and 20. If you leave it empty, the default of 5 is used.

• A higher value finishes large lists faster.
• A value of 1 runs the loop one item at a time, like a serial loop.

Higher values can affect how quickly other workflows run, because they share capacity. Start with the default and raise it only if you need to.

Iteration output mapper

An optional TypeScript function that formats each iteration's output before it's saved. The parallel loop's output is an array containing the result from each iteration.

Use it to keep only what later steps need, such as a serial number and a status, instead of every field from every node in the loop.

If you don't set a mapper, each iteration's output is the item it processed, so the loop's output is an array of the original items.

Adding a parallel loop to a workflow

Add the loop first, then build the steps that should run for each item inside it.

1. In the Graph View, click the + icon where you want the loop to start.
2. In the Add node window, select Utilities.
3. Select Parallel loop, then click Add.
4. In the node's side panel, set the Iterable.
5. Set Max concurrent iterations, or leave it at the default of 5.
6. Click Select a node inside the loop to add the nodes that should run for each item, one after another.

A parallel loop must contain at least one node, and it can't be deleted while it still has nodes inside it. Remove the nodes inside first.

Shaping each iteration's output

1. Select End of Parallel loop in the graph.
2. Under Iteration output mapper, click Add function.
3. Write a TypeScript function that returns the value you want saved for each item.

To remove the mapper, click the delete icon next to Iteration output mapper.

Monitoring parallel loop executions

When a workflow runs, the parallel loop node shows every item it processed.

1. Open the execution from Workflows > Executions.
2. Select the parallel loop node.
3. Open the Iterations tab.

The tab lists each iteration with its status. Use the Status filter to show only failed iterations, and select Load more iterations to see the rest of a long list.

Troubleshooting common issues

The loop failed, but most items succeeded

A single failed iteration marks the whole loop as failed once every item has finished. Open the Iterations tab, filter to failed iterations, and open one to see which node failed and why. See Monitoring workflow failures for more on investigating failures.

The loop is too slow

Raise Max concurrent iterations, up to 20. If the nodes inside the loop call an external system, check that it can handle that many requests at once.

Other workflows are running slower

A high Max concurrent iterations value uses more shared capacity. Lower it so other workflows get room to run.

Max concurrent iterations is rejected

The value must be a whole number between 1 and 20. Values outside that range can't be saved.

Nothing happened inside the loop

Check that the Iterable contains items. An empty list skips the loop body without an error.