Approval workflows JSON form schema

Introduction

Approval forms fields are defined using a JSON form schema created by Totara for this purpose. A form can be organised by section, or it can simply be a collection of fields.

Each field has a field_key, unique to the form, which is used to identify it in code.

A form can also include a PrintLayout definition, which is used to generate a printable form layout that looks similar to a traditional business form.

Example

{
  "title": "Simple Request Form",
  "shortname": "simple",
  "revision": "Revised December 2022",
  "version": "2022120801",
  "language": "en-US",
  "sections": [
    {
      "key": "A",
      "line": "Section A",
      "label": "Request",
      "fields": [
        {
          "key": "request",
          "line": "1",
          "label": "What are you requesting approval for?",
          "type": "text",
          "required": false
        },
        {
          "key": "notes",
          "line": "2",
          "label": "Further details",
          "type": "editor",
          "char_length": "50",
          "required": false
        }
      ]
    },
    {
      "key": "B",
      "line": "Section B",
      "label": "Followup",
      "fields": [
        {
          "key": "complete",
          "line": "1",
          "label": "Discussed with manager?",
          "required": false,
          "type": "select_one",
          "default": null,
          "attrs": {
            "choices": [
              {
                "key": null,
                "label": "Select one"
              },
              {
                "key": "Complete",
                "label": "Yes"
              },
              {
                "key": "Incomplete",
                "label": "No"
              }
            ]
          }
        }
      ]
    }
  ]
}

Schema definition

Optional properties are marked by suffixing them with a question mark. The part in square brackets is the type of the property.

Form (root)

Properties:

title? [string] - Title of the form for display.
shortname? [string] - Title of the form for reference.
revision? [string] - External reference version of the form (human readable).
version? [version string] - Machine-readable schema version.
language? [string] - Default language code for choices and labels.
fields? [Array<Field>]
sections [Array<Section>]
print_layout [PrintLayout]

Section

Properties:

key [string] - Unique key for the section.
label [string] - Label for the section.
line? [string] - Line number of the section. Used when line numbers are enabled in print view.
fields? [Array<Field>]

Field

Properties:

key [string] - Unique key for the field. This is used to store the data for the field, and in field references elsewhere in the schema and plugin code.
type [string] - Type of field (see list of field types below).
label [string] - Label for the field.
line? [string] - Line number of the field. Used when line numbers are enabled in print view.
instruction? [string] - Text to show below the field.
help? [string] - Help text to show in popover next to the label.
help_html? [string] - Reference to HTML to display in help popover. Takes precedence over help.
default? [*] - Default value of the field.
disabled? [boolean] - Whether the field should show as read-only on the form by default.
hidden? [boolean] - Whether the field should not be shown at all on the form by default.
conditional? [Test] - Hide this field if the condition is not met.
rules? [Array<Rule>] - Array of rules to check the condition and apply properties for each. All matching rules are applied.
char_length? [number] - Length of input, valid values are 2, 3, 4, 5, 10, 15, 20, 25, 30, 50, 75, and 100.
validations? [Array<Validation>]
attrs [object] - Properties specific to the field type.

The possible field types and the attrs for each are:

text
label
select_one
- choices [Array<SelectChoice>]
date
- format? [string] - String containing the tokens Y, m, and d - e.g. 'Y-m-d'.
email
number
phone
- format? [string] - E.g. 'us-ext'. Currently ignored.
textarea
url
editor
signature
address
- rows? [number]
fullname
currency
- currency [string] - Currency code, e.g. USD.
- min? [number]
currency_total
- currency [string] - Currency code, e.g. USD.
- sources [Array<string>] - List of keys of fields to total up.

Extra types can be added in plugins and specified as approvalform_pluginname/fieldtype.

Test

Properties:

key [string] - Field to check.
condition ["="|"<"|"<="|">"|">="] - Check to perform.
value: [*] Value to check against.

Rule

Properties

test [Test] - Condition to test. If it passes, this rule will be applied.
set [object] - Anything valid on Field, except key, type, conditional, and rules. These will be set if the condition passes. The attrs object will be merged.

Validation

Properties:

name [string] - Name of validation.

Possible validation types and their extra properties:

date_compare - compare two ISO date values (not datetime – if time is provided, it will be ignored):
- operation ["="|"<"|"<="|">"|">="] - Comparison.
- value [string] - Value to compare against.
min
- value [number] - Value to compare against.
max
- value [number] - Value to compare against.

PrintLayout

Properties:

options [PrintLayoutOptions]
sections [Array<PrintLayoutSection>]

PrintLayoutOptions

Properties:

paper_size? [object]
paper_size.width [number] - Width in mm.
paper_size.height [number] - Width in mm.
scale? [number] - Scale of layout as a whole. Defaults to 1.
section? [object] - Section options.
section.no_break? [boolean] - Avoid page breaks inside sections?
section.line_number? [boolean] - Include line numbers inside section headings?
field? [object] - Field options.
field.label_height? [number] - Maximum field label height in mm.
field.content_height? [number] - Maximum field content height in mm.
field.line_number? [boolean] - Include line numbers inside field labels?

PrintLayoutSection

Properties:

section? [string] - If specified, this section will only be shown if the section with the specified key exists in the schema.
rows [Array<Array<PrintLayoutField>>] - Array of rows, each row is an array of fields.

PrintLayoutField

Properties:

type [string]
units [number]

Types and their extra properties:

field
- field [string] - Name of the field. This should match up with 'key' in the form. This is used to retrieve the value and label.
- show_key? [boolean] - Show key in rendered value (mostly relevant for select_one fields).
- label? [boolean] - Show label? (true by default).
title - large text
- text [string]
section_label
- section [string] - Key of section to get the label from.
label
- text [string]
column
- rows [Array<Array<PrintLayoutField>>] - Array of rows, each row is an array of fields.
approvals