The Playbooks Iterator Operator in ThreatConnect® iterates through items in an input array or set of arrays, applies any logic available with Playbooks to each item, and returns the output to the Playbook. This capability expands Playbook applications beyond set-based use cases.
In the use case employed in this example, the user wants to iterate through a set of attachments to an email and send the attachments that contain the word “bad” further through the Playbook.
- On the top navigation bar (Figure 1), click Playbooks to display the Playbooks tab of the Playbooks screen (Figure 2).
- Create a new Playbook or open an existing Playbook. (See Playbooks.) Add Triggers, Apps, and Operators to the Playbook as desired. In this example, a Mailbox Trigger is added so that it will take an email as its input (Figure 3).
- Add an Iterator Operator by clicking the + OPERATOR button on the left-hand side of the Playbook Designer and selecting Iterator from the list. An Iterator operator will appear (Figure 4).
- Position the Iterator Operator as desired, and then connect the Mailbox Trigger to the Iterator Operator (Figure 5).
- Double click on the Iterator Operator, and the Edit Operator configuration panel will appear on the left-hand side of the Playbook Designer (Figure 6).
- 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, use the hashtag (#) to bring up a list of all upstream array variables, and then select an array from the list. Click the Plus button to the right, and a table will appear listing the newly created key/value set. Add as many inputs as desired.
NOTE: When 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.
NOTE: When dragging a connection to the red square, make sure to connect to the square itself rather than the Iterator as a whole.
NOTE: Array values are not allowed in this parameter.
- Key: Enter a name for array that the Operator will return to the rest of the Playbook (e.g., “Bad_Files”).
- Value: Use the hashtag (#) to bring up 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 button to the right, and a table will appear listing the newly created key/value set. Add as many outputs as desired. These output variables will be available as arrays for downstream apps.
NOTE: Loop variables are available to all Apps and Operators inside the loop.
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.
- Add a Break Iterator Operator by clicking the + OPERATOR button on the left-hand side of the Playbook Designer and selecting Break Iterator from the list. A Break Iterator Operator will appear. Connect it to the orange node of an If/Else Operator (Figure 14).
- Double click on the Break Iterator Operator, and the Edit Operator configuration panel will appear on the left-hand side of the Playbook Designer (Figure 15).
- Job Name: Enter a name for the Break Iterator.
- Click the SAVE button to save the configuration.
NOTE: When the Break Iterator Operator is executed, all iterations will stop, not just the one that led to the execution of the Break Iterator Operator.