PPA: User Interface

Summary

This module contains actions for interacting with PPA Task Operators.

PPA Task Interface

See Task Interface for more information on inputs & outputs in PPA.

Actions

ppa.ui.

input_accept

Present a labelled button with text, & wait until it is clicked.

Minimum Plugin Version: 1.0.0

Input

text: the button label
element_id: the ID of the element in the task interface (more info)

Output

Nothing is returned from this action.

Example

1 2	`- ppa.ui.input_accept: text: Start`

ppa.ui.

input_checklist

Present a list of checkboxes & wait for a selection to be made.

Minimum Plugin Version: 6.0.0

Minimum PPA Version: 2.10.0

Input

text: the title of the checklist
options: one or more values to populate the dropdown list (see the examples for more information)
defaults: optional list of values from options that will be checked by default
element_id: an optional ID for the interface element (more info)
sensitive: set to true to protect sensitive data (requires PPA v3 & plugin version 8.0.0)

Output

A list of selected values (all will be strings).

Example 1: Simple

Prompting for a team & saving the selection as a new variable called team.

- ppa.ui.input_checklist:
    text: Select Groups
    options:
      - Domain Admin
      - PPA Admins
      - PAM Admins
      - PPA Access
      - Engineering
  save: team

Example 2: Custom Ordering

Prompting for groups to be selected & saving the selection as a new variable called groups

To avoid list values being automatically sorted, this example uses a dictionary as input
Each key is a dropdown item, & its value is its order in the list

  - ppa.ui.input_checklist:
      text: Select Groups
      options:
        Domain Admin: 1
        PPA Admins: 2
        PPA Access: 3
        PAM Admins: 4
        Engineering: 5
    save: groups

ppa.ui.

input_choice

Present a dropdown & wait for a choice.

Minimum Plugin Version: 6.0.0

Input

text: the title of the dropdown list
options: one or more values to populate the dropdown list (see the examples for more information)
default: optional value to use as a default in the dropdown list (defaults to first value in options)
element_id: an optional ID for the interface element (more info)
sensitive: set to true to protect sensitive data (requires PPA v3 & plugin version 8.0.0)

Output

The value chosen by the task operator.

Example 1: Simple

Prompting for a team & saving the choice as a new variable called team.

- ppa.ui.input_choice:
    text: Select a Team
    options:
      - Sales
      - Marketing
      - Engineering
  save: team

Example 2: Custom Ordering

Minimum Plugin Version: 7.0.0

  - ppa.ui.input_choice:
      text: Select a Quantity
      options:
        - value: Sales
          order: 1
        - value: Marketing
          order: 2
        - value: Engineering
          order: 3
    save: quantity

ppa.ui.

input_confirm

Present two labelled buttons to offer a choice, & wait until one is clicked.

Minimum Plugin Version: 1.0.0

Input

text: the text to display above the 2 buttons
confirm: the label of the button that returns true (defaults to Yes)
cancel: the label of the button that returns false (defaults to No)
element_id: an optional ID for the task interface element (more info)
sensitive: set to true to protect sensitive data (requires PPA v3 & plugin version 8.0.0)

Output

A boolean (true or false).

Example

- ppa.ui.input_confirm:
    text: Would you like to continue?
    confirm: Yes
    cancel: No
  save: confirm

ppa.ui.

input_date

Present a date picker & wait until it is submitted.

Minimum Plugin Version: 6.1.0

Minimum PPA Version: 2.11.0

Input

text: the text to display above the date picker

Output

A String.

Example

1
2
3

- ppa.ui.input_date:
    text: Select a Start Date
  save: date

ppa.ui.

input_email

Present a text input field used to supply an email address.

The input will be validated, & the task operator will be re-prompted if validation fails.

Minimum Plugin Version: 5.3.0

Input

text: the title of the input field
required: set to false to make the field optional (defaults to true)
element_id: an optional ID for the interface element (more info)
sensitive: set to true to protect sensitive data (requires PPA v3 & plugin version 8.0.0)

Output

The supplied email address, or null if required is false & no value was supplied.

Example

1
2
3

- ppa.ui.input_email:
    text: Please supply your email address
  save: email_address

ppa.ui.

input_file

Ask the Task Operator to upload a file to the PPA task container.

The file contents can be used & inspected by the task.

The file will be made available to be downloaded by the task operator.

Minimum Plugin Version: 1.2.0

Input

text: text to display with the upload component
accept: optional file extension or MIME type to accept
element_id: the ID of the element in the task interface (more info)

Output

A single UploadedFile dictionary.

Example

- ppa.ui.input_file:
    text: Please upload a users CSV file
    accept: .csv
  save: users_csv

ppa.ui.

input_form

Present a form with one or more fields for the user to complete & submit.

Multiple fields types are supported, see here for more information.

Minimum Plugin Version: 7.0.0

Input

text: the title of the input form
fields: a list of form fields
sensitive: set to true to protect sensitive data (requires PPA v3 & plugin version 8.0.0)

Output

A dictionary containing the submitted form data.

See this example for more information on using form data.

Example

    - ppa.ui.input_form:
        text: New Joiner Form
        fields:

          - text:
              name: logon_name
              title: Logon Name
              pattern: >
                [A-Za-z]+\.[A-Za-z]+
              pattern_error: >
                Logon name must be in [first name].[last name] format.

          - email:
              name: email_address
              title: Email Address

          - choice:
              name: office
              title: Office
              options:
                - London
                - Paris
                - New York
              default: London

      save: joiner_data

ppa.ui.

input_hostname

Present a text input field used to supply a hostname.

The hostname format will be validated, & the task operator will be re-prompted if validation fails.

Minimum Plugin Version: 5.3.0

Input

text: the title of the input field
required: set to false to make the field optional (defaults to true)
element_id: an optional ID for the interface element (more info)

Output

The supplied hostname, or null if required is false & no value was supplied.

Example

1
2
3

- ppa.ui.input_hostname:
    text: Hostname
  save: hostname

ppa.ui.

input_ipv4

Present a text input field used to supply an IPv4 address.

The input will be validated, & the task operator will be re-prompted if validation fails.

Minimum Plugin Version: 5.3.0

Input

text: the title of the input field
required: set to false to make the field optional (defaults to true)
element_id: an optional ID for the interface element (more info)

Output

The supplied IPv4 address, or null if required is false & no value was supplied.

Example

1
2
3

- ppa.ui.input_ipv4:
    text: IP Address
  save: ip_address

ppa.ui.

input_ipv4_cidr

Present a text input field used to supply an IPv4 CIDR address.

The input will be validated, & the task operator will be re-prompted if validation fails.

Minimum Plugin Version: 5.3.0

Input

text: the title of the input field
required: set to false to make the field optional (defaults to true)
element_id: an optional ID for the interface element (more info)

Output

The supplied IPv4 CIDR address, or null if required is false & no value was supplied.

Example

1
2
3

- ppa.ui.input_ipv4_cidr:
    text: CIDR Address
  save: ip_address

ppa.ui.

input_multiline_text

Present a multiline text input field.

Minimum Plugin Version: 3.4.0

Input

text: the title of the input field
default: a default value for the input field (defaults to empty)
pattern: a regular expression to validate the supplied value
pattern_error: error to display if pattern validation fails
required: set to true to require a value before submission (defaults to false)
element_id: an optional ID for the interface element (more info)
lines: Denotes how many lines the input element should have (defaults to 15)
sensitive: set to true to protect sensitive data (requires PPA v3 & plugin version 8.0.0)

Output

The string submitted by the Task Operator. Any line breaks will be denoted by a \n.

Example

Prompting for a multiline comment & saving it as a new variable called comment.

- ppa.ui.input_multiline_text:
    text: Service Now Comment
    required: true
  save: comment

ppa.ui.

input_number

Present an input field used to supply a number.

The input will be validated, & the task operator will be re-prompted if validation fails.

Minimum Plugin Version: 5.8.0

Input

text: the title of the input field
minimum: optional lowest acceptable number
maximum: optional highest acceptable number
required: set to false to make the field optional (defaults to true)
element_id: an optional ID for the interface element (more info)
sensitive: set to true to protect sensitive data (requires PPA v3 & plugin version 8.0.0)

Output

The supplied number, or null if required is false & no value was supplied.

Example

1
2
3

- ppa.ui.input_number:
    text: Supply the number of days
  save: days

ppa.ui.

input_password

Present a password field.

The password will be obfuscated in the interface & not stored in PPA.

Minimum Plugin Version: 1.0.0

Input

text: the title of the input field
meter: set to true to show a password strength meter (defaults to false)
element_id: an optional ID for the interface element (more info)

Output

The password supplied by the task operator.

Example

- ppa.ui.input_password:
    text: Enter a Password
    meter: true
  save: new_password

ppa.ui.

input_password_confirm

Present 'New Password' & 'Confirm Password' input fields.

This action will loop until both supplied passwords match.

The passwords are obfuscated in the interface & not stored in PPA.

Minimum Plugin Version: 1.0.0

Input

This action takes no inputs.

Output

The password supplied by the task operator.

Example

1 2	`- ppa.ui.input_password_confirm: save: new_password`

ppa.ui.

input_sensitive_file

Ask the Task Operator to upload a file to the PPA task container.

The file contents can be used & inspected by the task.

The file will not be made available to be downloaded by the task operator.

Minimum PPA Appliance Version: 2.6.3

Minimum Plugin Version: 3.4.0

Input

text: text to display with the upload component
accept: optional file extension or MIME type to accept
element_id: the ID of the element in the task interface (more info)

Output

A single UploadedFile dictionary.

Example

- ppa.ui.input_sensitive_file:
    text: Please upload a certificate private key
    accept: .pem
  save: private_key

ppa.ui.

input_table

Present a table & wait for a selection.

Minimum Plugin Version: 3.0.0

Input

text: the table title
header: a list of column names
rows: the table contents as a list of lists, where each inner list is a row of values
minimum: The minimum number of acceptable selections
maximum: The maximum number of acceptable selections
element_id: an optional ID for the interface element (more info)
sensitive: set to true to protect sensitive data (requires PPA v3 & plugin version 8.0.0)

Output

A list of the selected table row indices (zero-indexed).

Example

Presenting a table of cities & countries & saving the selection as selected_rows.

- ppa.ui.input_table:
    title: Select Cities
    header:
      - City
      - Country
    rows:
      - - Paris
        - France
      - - London
        - England
      - - Cardiff
        - Wales
  save: selected_rows

If the first & second rows were chosen selected_rows would be:

1
2

  - 0
  - 1

ppa.ui.

input_text

Present a text input field.

Minimum Plugin Version: 1.0.0

Input

text: the title of the input field
default: an optional default value for the input field (defaults to empty)
pattern: an optional regular expression to validate the supplied value (defaults )
pattern_error: error to display if pattern validation fails (supported in PPA version 2.11.x & newer)
required: set to true to require a value before submission (defaults to false)
element_id: an optional ID for the interface element (more info)
sensitive: set to true to protect sensitive data (requires PPA v3 & plugin version 8.0.0)

Output

The string submitted by the task operator.

Example

Prompting for a username & saving it as a new variable called username.

The value is required, & must match the format firstname.surname
A folded string (the > character) escapes any special pattern characters

- ppa.ui.input_text:
    text: Username
    required: true
    pattern: >
      [A-Za-z]+\.[A-Za-z]+
  save: username

ppa.ui.

input_timestamp

Present a datetime picker & wait until it is submitted.

Minimum Plugin Version: 5.2.0

Minimum PPA Version: 2.8.0

Input

text: the text to display above the datetime picker

Output

A TimeStamp.

Example

1
2
3

- ppa.ui.input_timestamp:
    text: Select a Start Time
  save: timestamp

ppa.ui.

output_error

Present an error message in the task interface.

Minimum Plugin Version: 1.0.0

Input

text: the text to display
element_id: an optional ID for the interface element (more info)
color*: optional color name or hex code to apply to the text (see below for more)
sensitive: set to true to protect sensitive data (requires PPA v3 & plugin version 8.0.0)

Colors

Minimum PPA Version: 3.0.0

Minimum Plugin Version: 8.0.0

Either a color name or a hex code can be supplied as the color input.

Valid color names:

- yellow
- orange
- blue
- light_blue
- dark_blue
- green
- light_green
- dark_green
- red
- grey
- purple
- black
- pink

Output

Nothing is outputted by this action.

Example

1 2	`- ppa.ui.output_error: text: Something went wrong`

ppa.ui.

output_file

Allow the Task Operator to download a file from the PPA task.

Minimum Plugin Version: 1.2.0

Input

text: text to display with the upload component
data: file contents
filename: name of the file
type: optional MIME type (defaults to application/octet-stream)
element_id: the ID of the element in the task interface (more info)

Output

Nothing is outputted by this action.

Example

- ppa.ui.output_file:
    text: Please download the CSV report
    filename: report.csv
  load:
    data: csv_report

ppa.ui.

output_info

Present some text in the task interface.

Minimum Plugin Version: 1.0.0

Input

text: the text to display
element_id: an optional ID for the interface element (more info)
color*: optional color name or hex code to apply to the text (see below for more)
sensitive: set to true to protect sensitive data (requires PPA v3 & plugin version 8.0.0)

Colors

Minimum PPA Version: 3.0.0

Minimum Plugin Version: 8.0.0

Either a color name or a hex code can be supplied as the color input.

Valid color names:

- yellow
- orange
- blue
- light_blue
- dark_blue
- green
- light_green
- dark_green
- red
- grey
- purple
- black
- pink

Output

Nothing is outputted by this action.

Example

1 2	`- ppa.ui.output_info: text: Welcome to PPA`

ppa.ui.

output_markdown

Present a markdown document to display.

Minimum Plugin Version: 1.0.0

Input

doc: the markdown document to display
element_id: an optional ID for the interface element (more info)
sensitive: set to true to protect sensitive data (requires PPA v3 & plugin version 8.0.0)

Output

Nothing is outputted by this action.

Example

- ppa.ui.output_markdown:
    doc: >
      # Markdown Header

      Document text

ppa.ui.

output_password

Present an obfuscated password with copy to clipboard & optional reveal buttons.

The task will wait until the 'Done' button is clicked.

The password is not stored & will not be retrievable once the task finishes.

Minimum Plugin Version: 10.1.0

Input

title: a title to display above the password or secret
password: the password
allow_reveal: set to false to hide the reveal button (defaults to true)

Output

Nothing is outputted by this action.

Example

- ppa_tools.password_generators.regex:
    length: 20
  save: password

- ppa.ui.output_password:
    title: Generated Password
  load:
    password: password

ppa.ui.

output_progress

Present a progress bar with an indeterminate or % value.

The value null is deemed indeterminate & will display an animation.

Minimum Plugin Version: 1.0.0

Input

text: the title of the progress bar
percent: an integer progress value or null
element_id: an optional ID for the interface element (more info)

Progress Bar Element IDs

It is essential to supply an element_id to any progress bar whose value will be set more than once.

Output

Nothing is outputted by this action.

Example

Showing an indeterminate progress bar
waiting for a button click
Updating the progress bar to 100%

- ppa.ui.output_progress:
    text: Waiting to continue...
    percent: null
    element_id: action_progress
- ppa.ui.input_accept:
    text: Continue
- ppa.ui.output_progress:
    text: Continuing
    percent: 100
    element_id: action_progress

ppa.ui.

output_tabbed_table

Display a table with multiple tabs.

Minimum Plugin Version: 3.5.0

Input

text: the table title
header: a list of column names
tabs: a dictionary containing tab names & their rows as a list of lists
element_id: an optional ID for the interface element (more info)
sensitive: set to true to protect sensitive data (requires PPA v3 & plugin version 8.0.0)

Output

Nothing is outputted by this action.

Example

Presenting a table with 2 tabs, where each tab contains a table with 3 columns & 1 row.

- ppa.ui.output_tabbed_table:
    text: Users
    header:
      - Team
      - Role
      - Location
    tabs:
      John Smith:
        - - Engineering
          - Developer
          - London
      David Bennett:
        - - Engineering
          - Software Tester
          - London

ppa.ui.

output_table

Display a table.

Minimum Plugin Version: 1.0.0

Input

text: the table title
header: a list of column names
rows: the table contents as a list of lists, where each inner list is a row of values
element_id: an optional ID for the interface element (more info)
sensitive: set to true to protect sensitive data (requires PPA v3 & plugin version 8.0.0)

Output

Nothing is outputted by this action.

Example

- ppa.ui.output_table:
    text: Cities
    header:
      - Name
      - Country
    rows:
      - - Paris
        - France
      - - London
        - England
      - - Brussels
        - Belgium