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 (see here for more)

Output

Nothing is returned from this action.

Example

- ppa.ui.input_accept:
    text: Start

ppa.ui.

input_choice

Present a dropdown & wait for a choice.

Minimum Plugin Version: 1.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)

• element_id: an optional ID for the interface element (see here for more)

Output

The string 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

Prompting for a quantity & saving the choice as a new variable called quantity

• 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_choice:
      text: Select a Quantity
      options:
        One: 1
        Two: 2
        Three: 3
        Four: 4
        Five: 5
    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 (see here for more)

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_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 (see here for more)

Output

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

Example

- 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 (see here for more)

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_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 (see here for more)

Output

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

Example

- 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 (see here for more)

Output

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

Example

- 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 (see here for more)

Output

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

Example

- 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

• required: set to true to require a value before submission (defaults to false)

• element_id: an optional ID for the interface element (see here for more)

• lines: Denotes how many lines the input element should have (defaults to 15)

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 (see here for more)

Output

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

Example

- 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 (see here for more)

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

- 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 (see here for more)

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 (see here for more)

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:

  - 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: a default value for the input field (defaults to empty)

• pattern: a regular expression to validate the supplied value

• required: set to true to require a value before submission (defaults to false)

• element_id: an optional ID for the interface element (see here for more)

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 date 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 date picker

Output

A TimeStamp.

Example

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

ppa.ui.

output_error

Present some error text in red.

Minimum Plugin Version: 1.0.0

Input

• text: the text to display

• element_id: an optional ID for the interface element (see here for more)

Output

Nothing is outputted by this action.

Example

- 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 (see here for more)

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 basic text.

Minimum Plugin Version: 1.0.0

Input

• text: the text to display

• element_id: an optional ID for the interface element (see here for more)

Output

Nothing is outputted by this action.

Example

- 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 (see here for more)

Output

Nothing is outputted by this action.

Example

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

      Document text

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 (see here for more)

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 (see here for more)

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 (see here for more)

Output

Nothing is outputted by this action.

Example

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