PPA: User Interface Forms

Minimum PPA Version: 2.11.0

Minimum Plugin Version: 7.0.0

Form Inputs

Version 6.1.0 of this plugin adds support for form inputs in PPA tasks.

Forms can contain as many fields as you need, & multiple field types are supported.

Example

New Joiner Form

The form below contains 3 fields & uses both automatic & custom input validation.

New Joiner Form - PPA Interface

New Joiner Form - Playbook Snippet

- 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

      - checklist:
          name: applications
          title: Required Applications
          options:
            - value: Outlook
              order: 1
            - value: Word
              order: 2
            - value: Excel
              order: 3
            - value: Visio
              order: 4
          defaults:
            - Outlook
            - Word

      - choice:
          name: department
          title: Department
          options:
            - Sales
            - Marketing
            - Engineering

      - timestamp:
          name: start_date
          title: Start Date

  save: joiner_data

Using Submitted Data

In this example the following data is submitted using the form.

New Joiner Form - PPA Interface

The joiner_data variable will contain data below:

New Joiner Form - Submitted Data

{
    "logon_name": "example.user",
    "email_address": "example.user@company.net",
    "applications": [
        "Outlook",
        "Word"
    ],
    "department": "Marketing",
    "start_date": {
        "timestamp": "2022-03-02T09:00:00+00:00",
        "timezone": "Europe/London"
    }
}

Its values can then be supplied to any subsequent actions like this:

New Joiner Form - Using Form values

- active_directory.users.create:
    distinguishedName: >
      "CN={{ joiner_data.logon_name }},OU={{ joiner_data.department }},DC=Company,DC=Net"
  load:
    sAMAccountName: joiner_data.logon_name
    mail: joiner_data.email_address
    domain_controller: domain_controller

Field Types

The table below shows all supported field types & the validation options for each.

Name	Validation Method	Default Validator	Default Validation Error
Text	Custom	Any non-blank value	Input must not be blank
Multi-Line Text	Custom	Any non-blank value	Input must not be blank
Email Address	Automatic with custom errors	Email address	Invalid email address
Dropdown	Fixed Format	-	-
Check List	Fixed Format	-	-
IPv4 Address	Automatic with custom errors	IPv4 (dot-decimal notation)	Invalid IPv4 address
Hostname	Automatic with custom errors	RFC-1123 Hostname	Invalid Hostname
Number	Automatic with custom errors	One or more 0-9 characters	Invalid Number
Floating Point	Automatic with custom errors	Number with a decimal place	Invalid floating point number
Date	Fixed Format	DD/MM/YYYY	-
Date & Time	Fixed Format	DD/MM/YYYY HH:MM:SS	-

More information on each field type can be found below.

text

Presents a single-line text field.

Supported configuration values:

• title

• name

• default (optional)

• pattern (optional)

• pattern_error (optional)

• required (optional defaulting to true)

Example

- 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

Presents an email address field with automatic validation.

Supported configuration values:

• title

• name

• default (optional)

• pattern_error (optional)

• required (optional defaulting to true)

Example

- email:
    name: email_address
    title: Email Address

choice

Presents a dropdown box with one or more options.

Supported configuration values:

• title

• name

• options

• default (optional)

• required (optional defaulting to true)

Simple List

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

Ordered List With Default

- choice:
    name: office
    title: Office
    options:
      - value: London
        order: 1
      - value: Paris
        order: 2
      - value: New York
        order: 3
    default: Paris

checklist

Presents a checklist with one or more options.

Supported configuration values:

• title

• name

• options

• defaults (optional)

• required (optional defaulting to true)

Simple List

- checklist:
    name: applications
    title: Required Applications
    options:
      - Outlook
      - Word
      - Excel
      - Visio
    defaults:
      - Outlook

Ordered List

- checklist:
    name: applications
    title: Required Applications
    options:
      - value: Outlook
        order: 1
      - value: Word
        order: 2
      - value: Excel
        order: 3
      - value: Visio
        order: 4
    defaults:
      - Outlook
      - Word

ipv4address

Presents an IPv4 address field with automatic validation.

Supported configuration values:

• title

• name

• default (optional)

• pattern_error (optional)

• required (optional defaulting to true)

Example

- ipv4address:
    name: ip_address
    title: IP Address

hostname

Presents a hostname field with automatic validation.

Supported configuration values:

• title

• name

• default (optional)

• pattern_error (optional)

• required (optional defaulting to true)

Example

- hostname:
    name: hostname
    title: Hostname

multiline

Presents a text field with multiple lines.

Supported configuration values:

• title

• name

• default (optional)

• pattern (optional)

• pattern_error (optional)

• required (optional defaulting to true)

• lines (optional)

Example

- multiline:
    name: comment
    title: Comment
    lines: 5

number

Presents a number field with automatic validation.

Supported configuration values:

• title

• name

• default (optional)

• pattern_error (optional)

• required (optional defaulting to true)

Example

- number:
    name: extension
    title: Phone Extension

float

Presents a floating point number field with automatic validation.

Supported configuration values:

• title

• name

• default (optional)

• pattern_error (optional)

• required (optional defaulting to true)

Example

- float:
    name: cost
    title: Cost

timestamp

Presents a date & time picker.

Supported configuration values:

• title

• name

Example

- timestamp:
    name: start_time
    title: Start Time

date

Presents a date picker.

Supported configuration values:

• title

• name

Example

- date:
    name: start_date
    title: Start Date

Input Validation

Depending on the field type, input validation can be automatic or custom.

You can find the validation method for each field here.

The pattern is used to validate the user input, & the pattern_error is displayed to the user if validation fails.

More information on the pattern & pattern_error of each field type can be found here.

Note: validation is not performed on empty fields that are optional.

Custom Validation

By default the text & multiline fields will only validate that the field is not-empty.

You can provide your own validation rules & error messages using pattern & pattern_error.

The following snippet uses both to validate input & present a meaningful error if validation fails:

  - 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

Validation Errors

The pattern used by a field with automatic validation cannot be overwritten.

You can still overwrite the pattern_error to control what's displayed if validation fails.

  - number:
      name: hours
      title: Number of hours
      pattern_error: The hours field must be a number

Configuration Glossary

Name	Description	Required	Field Types
name	The name of the field in the submitted form.	Yes	All
title	The title of the field in the interface.	Yes	All
required	Indicates whether the field is required or not (defaults to true). Set to false to make the field optional.	No	text, multiline, email, ipv4_address, hostname, number, float
pattern	Regular expression used to validate user input.	No	text, multiline
pattern_error	Error to display if input validation fails. The following field types already show useful errors, but they can be overwritten: email, ipv4_address, hostname, number, float.	No	text, multiline, email, ipv4_address, hostname, number, float
options	One or more options to select from.	No	choice, checklist
default	Default value for the field.	No	text, multiline, email, ipv4_address, hostname, number, float, choice
defaults	One or more default values for the field.	No	checklist
lines	The default number of lines in the field.	No	multiline