Functionality - While Loops

Minimum PPA Version: 2.10.0

Summary

The while loop allows you to:

• Repeat a step until criteria has been satisfied
• Restart the loop early if a certain condition is met (optional)

After each action in the step is complete, the value of the supplied variable will be checked.

As soon as it's value is not equal to the loop condition, the step will finish.

You can only use while loops in a step.

Configuration

Name

The name of the flag to check after each action in the step.

When the step begins the flag is created & has its value set to the supplied value.

This cannot be the same as anything previously saved or set.

while:
  name: confirmed
  value: false

This flag is removed once the loop has completed

Value

An initial value to give the name loop flag.

The step will finish as soon as the flag's value is not equal to this.

while:
  name: confirmed
  value: false

Restart [optional]

Optional flag name used to restart the loop early.

When supplied this flag will be created with a default value of false.

If an action inside the step sets the flag to true, the loop will restart immediately.

while:
  name: confirmed
  value: false
  restart: user_exists  # optional

This cannot be the same as anything previously saved or set.

This flag is removed once the loop has completed

Loop Counters

PPA makes counter & index variables available inside a loop.

The index variable starts at 0, & the counter variable starts at 1.

They are both incremented by 1 each time through the loop.

• step_index
• step_counter

Counter variables are removed once the loop has completed

Examples

1 - Looped Step

This example uses while to repeat a step until some supplied details are confirmed.

If the user clicks Yes in the final action, the confirmed flag is set to true, finishing the loop.

- name: Supply Details
  while:
    name: confirmed
    value: false
  actions:

    - ppa.ui.input_text:
        text: Username
        required: true
      save: username

    - ppa.ui.input_email:
        text: Email Address
      save: email

    - ppa.ui.output_markdown:
        doc: >
          ### User Details

          **Username:** {{ username }}

          **Email:** {{ email }}

    - ppa.ui.input_confirm:
        text: Is this correct?
      save: confirmed

2 - Looped Step With Restart

This example adds a restart flag to example 1.

It's used to restart the loop if the supplied username is already taken.

Note the restart flag is set to true after displaying a useful message to the user.

- name: Supply Details
  while:
    name: confirmed
    value: false
    restart: user_exists
  actions:

    - ppa.ui.input_text:
        text: Username
        required: true
      save: username

    - active_directory.users.exists:
        search_params:
          sAMAccountName: "{{ username }}" 
      load:
        domain_controller: domain_controller
      save: exists

    # Display a message before restarting the loop.
    - ppa.ui.output_error:
        text: A user already exists with username {{ username }}!
      when: exists

    # This action will restart the loop early if the user exists.
    - set:
        name: user_exists
        value: true
      when: exists

    - ppa.ui.input_email:
        text: Email Address
      save: email

    - ppa.ui.output_markdown:
        doc: >
          ### User Details

          **Username:** {{ username }}

          **Email:** {{ email }}

    - ppa.ui.input_confirm:
        text: Is this correct?
      save: confirmed