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'.
- 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