Functionality - For Loops

Summary

This type of loop repeats one or more operations for each item in a list.

Use for loops in a Playbook by defining a sequence in an action or step.

Read more about for loops on w3schools.

Steps & Actions

A sequence can be used to repeat both steps & actions.

It's also possible to have repeated actions inside repeated steps.

To support this functionality, the following sets of variables are used.

Step Sequence Variables

These can be used in all actions inside a repeated step.

Item Value

  • Jinja2: loop.step.item.value

  • Python: loop["step"]["item"]["value"]

Item Position

  • Jinja2: loop.step.item.index

  • Python: loop["step"]["item"]["index"]

Run a Step 3 Times
1
2
3
4
5
6
7
8
9
steps:
  name: I will run 3 times
  sequence:
    - 1
    - 2
    - 3
  actions:
    - ppa.ui.output_info:
        text: This is step sequence number {{ loop.step.item.value }}

Action Sequence Variables

These can be used in a repeated action.

Item Value

  • Jinja2: loop.action.item.value

  • Python: loop["action"]["item"]["value"]

Item Position

  • Jinja2: loop.action.item.index

  • Python: loop["action"]["item"]["index"]

Run an Action 3 Times
1
2
3
4
5
6
7
8
9
steps:
  name: I will run once, but my action will run 3 times
  actions:
    - ppa.ui.output_info:
        text: This is action sequence number {{ loop.action.item.value }}
      sequence:
        - 1
        - 2
        - 3

Examples

Repeated Actions

This example uses a sequence to delete each Active Directory group in a list.

1. Create the Sequence

  • An action is used to find empty groups whose names start with Test
  • The output is saved as the groups variable
Find the Groups
1
2
3
4
5
6
7
actions:
  - active_directory.groups.search:
      member: null
      cn: Test*
    load:
      domain_controller: domain_controller_info
    save: groups

2. Use the Sequence

  • The groups variable is used as a sequence in the next action

  • This action requires the distinguishedName parameter

  • The parameter is supplied using the action item value Jinja2 syntax

Delete the Groups
1
2
3
4
5
  - active_directory.groups.delete:
    load:
      distinguishedName: loop.action.item.value.distinguishedName
      domain_controller: domain_controller_info
    sequence: groups

Saving Output

Saving dynamic variables works differently when using sequenced actions.

Single Actions

An action that is not sequenced will run once & output a single piece of data.

Regardless of the type (list, dictionary, string, etc), there will only be one output.

The contents of a saved variable in this scenario will be the single output.

Sequenced Actions

A sequenced action will, nearly always, run more than once.

Each time the action is run its output is added to a list.

The contents of a saved variable in this scenario will be a list of all the outputs.

Examples

Multiplying Numbers

This example runs the eval action with a sequence of numbers:

  • The eval expression uses the action item value Python syntax

  • The output from the action is saved as the results variable

Sequenced Eval Action
1
2
3
4
5
6
7
8
actions:
  - eval:
      expression: loop['action']['item']['value'] * 2
    sequence:
      - 1
      - 2
      - 3
    save: results

Given the action was sequenced, the results variable will contain:

Output List
1
2
3
- 2
- 4
- 6