Functionality - Actions

Built-In Actions

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

count

Get the number of items in a list, dictionary, or string.

This action will output the following for each sequence type:

String: the number of characters in the string.

List: the number of items in the list.

Dictionary: the number of key-value pairs in the dictionary.

Minimum PPA Version: 2.5.1

Input
  • item: a list, dictionary, or string to count the contents of
Output

An integer.

Example
- count:
    item:
      - Welcome
      - to
      - PPA
  save: count

The value of the new variable count will be:

3

debug

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

Minimum PPA Version: 2.5.0

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.

Minimum PPA Version: 2.5.0

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.

Minimum PPA Version: 2.5.0

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

You can define playbook exit codes to give each exit code a business description in the activity page.

This is done through the Edit Metadata form in the PPA interface.

fail

Fail a task with a reason.

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

Minimum PPA Version: 2.5.0

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"

filter_list

Remove items from a list that match the supplied filters.

Minimum PPA Version: 2.5.1

Input

  • items: a list of items to filter

  • filters: either a single value or a list of values to filter from the items list

Output

A filtered list.

Filtering Single Values
- filter_list:
    items:
      - null
      - 1
      - 2
    filters: null
  save: filtered_list

The value of the new variable filtered_list will be:

- 1
- 2
Filtering Multiple Values
- filter_list:
    items:
      - 1
      - 2
      - 3
      - 4
      - 5
    filters:
      - 2
      - 4
  save: filtered_list

The value of the new variable filtered_list will be:

- 1
- 3
- 5

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.

Minimum PPA Version: 2.5.1

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.

join_list

Join a list of strings together using the specified delimiter.

Minimum PPA Version: 2.5.1

Input

  • items: the list of strings to join

  • delimiter: the delimiter to use when joining items (defaults to no delimiter)

Output

A string of all the list items joined together.

Example

Joining a list using a space as the delimiter:

- join_list:
    items:
      - Welcome
      - to
      - PPA
    delimiter: " "
  save: split_output

The value of the new variable joined_output will be:

Welcome to PPA

log

Add a new message to the task log.

Minimum PPA Version: 2.5.0

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 }}

set

Create a new named variable & assign it a value.

The variable will be available for use in all subsequent actions.

Minimum PPA Version: 2.5.1

Input

  • name: the variable name

  • value: the value to assign

Output

Nothing is outputted by this action.

Example

Creating a dictionary & storing it in the variable named 'configuration'

- set:
    name: configuration
    value:
      bind_address: 0.0.0.0:443
      ssl_cert: /etc/ssl/mycert.pem

sleep

Sleep a number of seconds before continuing to the next action.

Minimum PPA Version: 2.5.1

Input
  • seconds: the number of seconds to sleep
Output

Nothing is outputted by this action.

Example
- sleep:
    seconds: 10

split_text

Split a string into a list of strings using the specified delimiter.

Minimum PPA Version: 2.5.1

Input

  • text: the string to split

  • delimiter: optional delimiter to use when splitting text (defaults to one or more spaces)

Output

A list of strings (example below).

Example

Splitting on one or more whitespace characters using the default delimiter value:

- split_text:
    text: Welcome to PPA
  save: split_output

The value of the new variable split_output will be:

- Welcome
- to
- PPA

user_info

Get the username & logon domain name for the user who started the task.

Minimum PPA Version: 2.5.1

Input

This action takes no inputs.

Output

A dictionary containing the keys username & domain:

{
  "domain": "example-domain",
  "username": "example.user"
}
Example
- user_info:
  save: ppa_user