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_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.
1 2 3 4 5 6 7 8 9 |
|
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
1 2 3 4 5 6 7 8 9 |
|
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.
1 2 3 4 5 6 7 |
|
Example 2: Custom Ordering
Minimum Plugin Version: 7.0.0
1 2 3 4 5 6 7 8 9 10 |
|
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
1 2 3 4 5 |
|
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_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 totrue
) -
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_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
1 2 3 4 |
|
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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
|
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 totrue
) -
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_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 totrue
) -
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_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 totrue
) -
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_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 tofalse
) -
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.
1 2 3 4 |
|
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 totrue
) -
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_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 tofalse
) -
element_id: an optional ID for the interface element (more info)
Output
The password supplied by the task operator.
Example
1 2 3 4 |
|
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_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
1 2 3 4 |
|
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
.
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
If the first & second rows were chosen selected_rows
would be:
1 2 |
|
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 tofalse
) -
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
1 2 3 4 5 6 |
|
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.
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_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
1 2 3 4 5 |
|
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_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
1 2 3 4 5 |
|
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%
1 2 3 4 5 6 7 8 9 10 |
|
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.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
|
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
1 2 3 4 5 6 7 8 9 10 11 12 |
|