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