> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-cloud/studio/tasks/reference/for-each/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# forEach

> Use the forEach task to execute a loop inside a job, iterating over an array and running a series of tasks for each element.

The `forEach` task executes a loop inside a job. It iterates over a passed array, and for each element, it executes a series of tasks. The `forEach` task is helpful when using tasks that operate on one thing, such as a device, but then you need to repeat those steps over a set of devices. Building a loop in the workflow is more efficient than writing new tasks.

The `forEach` task is unique as it supports transitions that follow the loop value. When a transition is created to follow the loop, it is distinguished with a blue arrow. The series of tasks at the end of the blue arrow dictates what will be executed for every iteration of the `forEach` task. A `forEach` task also supports transitions bound to the success and error finish states. When `forEach` completes its iterations (barring any errors), it returns with a success finish state and the job then follows the transitions bound to that finish state.

## Properties

| Direction | Property                | Description                                                                                                                                                                                                                                                                                                                                                                                     |
| --------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Incoming  | `data_array` (required) | Specify the array of items `forEach` will use in its iterations. The value can come from a job variable, a static value, or an earlier task's outgoing variable. If the reference task is a job variable or earlier task, the reference variable shows a dropdown of available variable names for selection. If the reference task is static, the reference variable becomes a text edit field. |
| Outgoing  | `current_item`          | In each iteration, the `forEach` task copies the next `data_array` element's value into its outgoing variable `current_item`. You may create a job variable from `current_item`. The immutable outgoing variable `current_item` remains, and a new mutable job variable is created. When creating a job variable, provide a new name to avoid name conflicts and provide clarity.               |

## Examples

### Replace retired device group

Use the `forEach` workflow operation task for a job that replaces a retired device group used on every device with a new group.

![](/_fern-img/2cdacd928bff5011004ed23937633f41cd6fa3f2247550ba419ef1905bc94701.webp)

When the job begins, the first automatic task returns a list of all devices. The device list is passed to a `forEach` task which executes four tasks for every device passed. The four tasks in the example above remove each device from the retired device group, add each device to the new device group, and then concurrently get any configuration on the device not in sync with its modeled configuration while getting all groups for the device. After the last device is processed, the `forEach` task returns with a success finish state, and the job completes.

### Handle errors inside forEach loops

Use the following to handle errors inside `forEach` loops.

#### Create a newVariable task

Create a **newVariable** task and name the variable `saved_errors` as an empty array.

#### Add a push task inside the loop

Inside the `forEach` loop, create a **push** task to transition `saved_errors` from the task where errors occur (task X) to the **push** task. Push the errors into the array.

#### Evaluate the errors after the loop

After the `forEach` loop, query the job variable and evaluate if the length is zero or not. Handle accordingly if the evaluation state is not successful.

![](/_fern-img/63798308f84a1fbb25f4bf65e4ee4bfb4d604b847868fd7d30df6150b67efaf4.webp)

## Tasks within forEach branches

Tasks within a `forEach` branch should not connect to the `END` task. The `forEach` branch is akin to a tree branch. It is best to think of `END` tasks as "inside" of the `forEach` loop — they should not interact with any other task or branch of the workflow, only within the loop. The workflow builder will allow you to connect a task, but doing so will yield unintuitive results.

> Use the forEach task to execute a loop inside a job, iterating over an array and running a series of tasks for each element.