---
title: "Playbooks Iterator Operator Knowledge Base Article | ThreatConnect"
slug: "playbooks-iterator-operator"
description: "The Iterator Operator iterates through items in an input array or set of arrays, applies Playbook logic to each item, and returns the output to the Playbook. This article describes how to configure and use the Iterator and Break Iterator Operator."
tags: ["Orchestration and Automation"]
updated: 2024-11-06T19:16:00Z
published: 2024-11-06T19:16:00Z
---

> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.threatconnect.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Playbooks Iterator Operator

## Overview

The Playbooks Iterator Operator in ThreatConnect® iterates through items in an input array or set of arrays, applies any logic available with [Playbooks](https://knowledge.threatconnect.com/docs/playbooks) to each item, and returns the output to the Playbook. This capability expands Playbook applications beyond set-based use cases.

## Before You Start

| Minimum Role(s) | - Organization role of Read Only User to view Playbooks with an Iterator Operator - Any other Organization role to use the Iterator Operator in a Playbook |
| --- | --- |
| Prerequisites | Playbooks enabled by a System Administrator |

## Iterator Operator

To illustrate the process of creating and configuring an Iterator Operator, we use an example in which we want to iterate through a set of attachments to an email and send the attachments that contain the word “bad” further through the Playbook.

1. On the top navigation bar, click **Playbooks**to display the**[**Playbooks** screen](https://knowledge.threatconnect.com/docs/the-playbooks-screen).
2. Create a new [Playbook](https://knowledge.threatconnect.com/docs/playbooks) or open an existing one.
3. Add [Triggers, Apps, and Operators](https://knowledge.threatconnect.com/docs/parts-of-a-playbook) to the [Playbook](https://knowledge.threatconnect.com/docs/the-playbook-designer) as desired. In this example, we add and configure a [Mailbox Trigger](https://knowledge.threatconnect.com/docs/playbooks-the-mailbox-trigger)so that the Playbook will take an email as its input (Figure 1).NoteThis article does not cover configuration of the [Mailbox Trigger](https://knowledge.threatconnect.com/docs/playbooks-the-mailbox-trigger).![Figure 1_Playbooks Iterator Operator_7.7.1](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Figure%201_Playbooks%20Iterator%20Operator_7.7.1.png)

NoteThe **Validations** ![Validations icon](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Validations%20icon.png) icon on the side navigation bar will show one error, at minimum, until the Playbook has been fully created and [validated](https://knowledge.threatconnect.com/docs/validations).
4. Click **![Playbook Designer Operators icon](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Playbook%20Designer%20Operators%20icon.png)** **Operators**on the side navigation bar of the **Playbook Designer**and select **Iterator**from the list. An Iterator Operator will be displayed in the **Playbook Designer**.
5. Position the Iterator Operator as desired, and then connect the Mailbox Trigger to the Iterator Operator by dragging the Trigger’s blue circle node to the Iterator Operator (Figure 2). ![Figure 2_Playbooks Iterator Operator_7.7.1](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Figure%202_Playbooks%20Iterator%20Operator_7.7.1.png)
6. Double-click the Iterator Operator to display the **Edit App**configuration pane on the left side of the **Playbook Designer** (Figure 3). ![Figure 3_Playbooks Iterator Operator_7.7.1](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Figure%203_Playbooks%20Iterator%20Operator_7.7.1.png)
  - **Job Name**: Enter a name for the Iterator Operator.
  - **Inputs**: In the **Key** field, enter a name for the array on which the Operator will iterate (e.g., “Filename”). In the **Value** field, enter a hashtag (#) to display a list of all upstream array variables, and then select an array from the list. Click the **plus**![Plus icon_Black](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Plus%20icon_Black.png)button to the right, and a table with the key/value pair will be displayed (Figure 4). Add as many inputs as desired. Click the ![Pencil icon_Black](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Pencil%20icon_Black.png), ![Copy Endpoint icon - Playbooks Screen](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Copy%20Endpoint%20icon%20-%20Playbooks%20Screen.png), or ![Trash icon_Black](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Trash%20icon_Black.png) icon to edit, duplicate, or delete a key/value pair, respectively. ![Figure 4_Playbooks Iterator Operator_7.7.1](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Figure%204_Playbooks%20Iterator%20Operator_7.7.1.png)

ImportantWhen more than one input array is defined, all input arrays must match in length or else the iteration operation will fail when the Playbook runs.NoteWhen editing an entry in the table, the **Iterate On** fields will populate with the key/value pair. Make the changes in those fields, and then click the checkmark or **X** icon to accept or reject the changes, respectively. You can duplicate a key/value pair and then edit the copy in order to create a new pair based on an existing pair. If you duplicate the same pair more than once without changing the first copy’s key, duplicate entries will be displayed in the table, an error notification will be displayed at the bottom left of the screen, and you will be prevented from saving the Iterator Operator’s configuration until you change the name of all copies with the same key. To copy only the contents of a key or value field in the table, use your browser’s copy functionality (e.g., Command-C).
7. Click the **SAVE** button without adding output variables. The Iterator Operator has two nodes at the bottom (see Figure 2) that are used to create a loop to send items sequentially through an operation or series of operations and then return the results to the Iterator Operator. Output variables are used to pass information back to the Iterator Operator from this loop, but first the loop must be created, and the list of potential values must be populated by the Apps that form the loop. As such, the output variables must be added after the loop has been created. On the other hand, input variables for the Iterator Operator must be configured in order to start the loop.
8. Create and configure the Apps and Operators that compose the loop operations for the Iterator Operator, and connect them to the Iterator Operator. The white circle node is the start point of the loop, and the red square node is the end point of the loop. In Figure 5, the Iterator Operator sends each file from the Mailbox Trigger to an App that checks the filename. If the term “bad” is found, then an App reports the file as malicious, and the loop closes with a return to the Iterator Operator, which moves to the next item in the array sent by the Mailbox Trigger.ImportantWhen dragging a connection to the red square node, make sure to connect to the square node itself rather than the Iterator as a whole.![Figure 5_Playbooks Iterator Operator_7.7.1](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Figure%205_Playbooks%20Iterator%20Operator_7.7.1.png)
9. Double-click the Iterator Operator to edit it again in order to add outputs (Figure 6). The outputs of the Iterator Operator are non-array variables that are collected into a single array and exposed to downstream Apps.ImportantArray values are not allowed in this parameter.![Figure 6_Playbooks Iterator Operator_7.7.1](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Figure%206_Playbooks%20Iterator%20Operator_7.7.1.png)
  - **Outputs**: In the **Key** field, enter a name for array that the Operator will return to the rest of the Playbook (e.g., “Bad_Files”). In the **Value** field, enter a hashtag (#) to display a list of all non-array variables that are available inside the loop logic, and then select a variable from the list. Click the **plus**![Plus icon_Black](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Plus%20icon_Black.png)button to the right, and a table with the key/value pair will be displayed (Figure 7). Add as many outputs as desired. These output variables will be available as arrays for downstream Apps. Click the ![Pencil icon_Black](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Pencil%20icon_Black.png), ![Copy Endpoint icon - Playbooks Screen](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Copy%20Endpoint%20icon%20-%20Playbooks%20Screen.png), or ![Trash icon_Black](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Trash%20icon_Black.png) icon to edit, duplicate, or delete a key/value pair, respectively. ![Figure 7_Playbooks Iterator Operator_7.7.1](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Figure%207_Playbooks%20Iterator%20Operator_7.7.1.png)

NoteWhen editing an entry in the table, the **Array Outputs** fields will populate with the key/value pair. Make the changes in those fields, and then click the checkmark or **X** icon to accept or reject the changes, respectively. You can duplicate a key/value pair and then edit the copy in order to create a new pair based on an existing pair. If you duplicate the same pair more than once without changing the first copy’s key, duplicate entries will be displayed in the table, an error notification will be displayed at the bottom left of the screen, and you will be prevented from saving the Iterator Operator’s configuration until you change the name of all copies with the same key. To copy only the contents of a key or value field in the table, use your browser’s copy functionality (e.g., Command-C).
10. Click the **SAVE**button to save the configuration. To view the loop variables, hover the cursor over the ![Loop Variables icon](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Loop%20Variables%20icon.png)icon of the Iterator Operator (Figure 8).NoteLoop variables are available to all Apps and Operators inside the loop.![Figure 8_Playbooks Iterator Operator_7.7.1](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Figure%208_Playbooks%20Iterator%20Operator_7.7.1.png)
11. Continue to build the Playbook by adding Apps or Operators that connect to the success and/or failure paths (i.e., the blue and orange dots, respectively) of the Iterator Operator.

## Break Iterator Operator

The Break Iterator Operator is used after the If/Else Operator to define a break condition for a loop or break from a loop directly after an App failure.

1. Click **![Playbook Designer Operators icon](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Playbook%20Designer%20Operators%20icon.png)** **Operators** on the side navigation bar of the **Playbook Designer**and select **Break Iterator**from the list. A Break Iterator Operator will be displayed in the **Playbook Designer** (Figure 9). ![Figure 9_Playbooks Iterator Operator_7.7.1](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Figure%209_Playbooks%20Iterator%20Operator_7.7.1.png)
2. Move the Break Iterator Operator as desired, and connect the orange circle node of an If/Else Operator (**“bad” Found?**in this example) to the Break Iterator Operator (Figure 10). ![Figure 10_Playbooks Iterator Operator_7.7.1](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Figure%2010_Playbooks%20Iterator%20Operator_7.7.1.png)
3. Double-click the Break Iterator Operator to display the **Edit Operator**configuration pane on the left side of the **Playbook Designer** (Figure 11). ![Figure 11_Playbooks Iterator Operator_7.7.1](https://cdn.document360.io/dfc206c8-1c9f-4725-b74d-a66f83432320/Images/Documentation/Figure%2011_Playbooks%20Iterator%20Operator_7.7.1.png)
  - **Job Name**: Enter a name for the Break Iterator Operator.
  - Click the **SAVE** button to save the configuration.
4. If the condition that leads to the Break Iterator Operator occurs, the loop will exit and continue to the success path of the Iterator Operator (i.e., the path coming from the blue dot of the Iterator Operator, which is not yet configured in this example).NoteWhen the Break Iterator Operator is executed, all iterations will stop, not just the one that led to the execution of the Break Iterator Operator.

---

*ThreatConnect® is a registered trademark of ThreatConnect, Inc*.

20085-01 v.03.C

## Related

- [Parts of a Playbook](/parts-of-a-playbook.md)
- [The Playbook Designer](/the-playbook-designer.md)