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