Functionality - Actions

Built-In Actions

These actions are part of the PPA task environment & don't belong to a specific plugin.

log

Add a new message to the task log.

Input

message: the message to log

log_level: the log level for the message (defaults to info)

Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
  - ppa.ui.input_choice:
      text: Select a Number
      options:
        - 1
        - 2
        - 3
    save: number

  - log:
      level: debug
      message: The user selected number {{ number }}

debug

Add a new message to the task log containing the details of a variable.

Input

identifier: the name of a set or previously saved variable

log_level: the log level for the message (defaults to info)

Output

Nothing is outputted by this action.

Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
  - ppa.ui.input_choice:
      text: Select a Number
      options:
        - 1
        - 2
        - 3
    save: number

  - debug:
      level: debug
      identifier: number

eval

Run an inline Python expression & save its output.

All task variables are available to use in the expression.

Input

expression: a single Python expression

Output

The value returned by the Python expression.

Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
actions:
  - ppa.ui.input_choice:
      text: Select a Number
      options:
        - 1
        - 2
        - 3
    save: number

  - eval:
      expression: "number % 2 == 0"
    save: number_is_even

Tip

See Inline Code for more information

exit

Exit a task with a supplied exit code.

Input

exit_code: the exit code number

Output

Nothing is outputted by this action.

Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
actions:
  - ppa.ui.input_choice:
      text: Select a Number
      options:
        - 1
        - 2
        - 3
    save: number

  - eval:
      expression: "number % 2 == 0"
    save: number_is_even

  - exit:
      exit_code: 1
    when: "not number_is_even"

Tip

Use with metadata exit_codes to give each exit code a business description

fail

Fail a task with a reason.

The reason will be displayed as an error in the task interface.

Input

reason: the failure message

Output

Nothing is outputted by this action.

Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
actions:
  - ppa.ui.input_choice:
      text: Select a Number
      options:
        - 1
        - 2
        - 3
    save: number

  - eval:
      expression: "number % 2 == 0"
    save: number_is_even

  - fail:
      reason: Number is not even
    when: "not number_is_even"

format_template

Format a string template using a dictionary of placeholder names & values.

Wrap a word in curly braces like {this} to make a placeholder.

Input
  • template: a string containing one or more placeholders

  • key_values: a dictionary containing placeholder names & values to format into the template

Output

The formatted template as a string.

Example
  • Setting a multi-line email template with placeholders at the top of a Playbook
1
2
3
4
5
6
7
8
9
set:
  email_template: >
    User {user_name} was successfully added to group {group_name}

    ServiceNow Incident number: {incident_number}

    Task ran at: {time}

    The operation was performed by PPA
  • Creating an email body from the template using variables created at run time
1
2
3
4
5
6
7
8
9
- format_template:
  load:
    template: email_template
    key_values:
      user_name: user.sAMAccountName
      group_name: group.sAMAccountName
      incident_number: incident.number
      time: time
  save: email_body

Remember

Formatting will fail if any placeholder is missing from key_values.