Relationship between Rulesets & Templates

Updated pdexter 2024-01-15

A template holds several event ruleset links, defined as the following root level properties:

Note that more than one ruleset can be linked to any event on a template.

Example Template

{
    "name": "Insect",
    "appTags": [
        "dexwise",
        "entomology",
        "insect"
    ],
    "summaryNameRule": "Insect - {{commonName}} ({{genus}} {{species}})",
    "summaryDescriptionRule": "{{description}}",
    "formColor": "#E3E3E3",
    "systemHeader": {...},
    "documentId": "07e7fbd0-cee3-11e5-aa08-fdabe14f1759",
    "components": [...],
    "onLoadClientRuleRel": [
        {
            "documentId": "23713325-3p67-66r1-3472-200r2r17qs3p,
            "name": "Insect - PreRender"
        }
    ],
    "onLoadClientRuleRel": [
        {
            "documentId": "78268870-8c12-11e6-8927-755e7e62df8c",
            "name": "Insect - OnLoad"
        },
        {
            "documentId": "007ba540-c833-11e7-af55-9b20b8681e48",
            "name": "Insect - OnFieldState"
        }
    ],
    "onFieldChangeClientRuleRel": [
        {
            "documentId": "569708a56f63cbc353af47fd",
            "name": "Insect - OnFieldChange"
        },
        {
            "documentId": "007ba540-c833-11e7-af55-9b20b8681e48",
            "name": "Insect - OnFieldState"
        }
    ],
    "preSaveClientRuleRel": [
        {
            "documentId": "6b139450-4952-11e6-ae2d-a99c41a4e267",
            "name": "Insect - PreSave"
        }
    ],
    "postSaveClientRuleRel": [
        {
            "documentId": "58919726-c833-11e7-af55-76777697",
            "name": "Insect - PostSaveClient"
        },
        {
            "documentId": "007ba540-c833-11e7-af55-9b20b8681e48",
            "name": "Insect - OnFieldState"
        }
    ],
    "preSaveServerRuleRel": [
        {
            "documentId": "563388f0-4953-11e6-ae2d-a99c41a4e267",
            "name": "Insect - PreSaveServer"
        }
    ],
    "postSaveServerRuleRel": [
        {
            "documentId": "56524b945bec6a9d0a93bcc3",
            "name": "Insect - PostSave"
        }
    ]
}

Applying Rulesets to Templates

While it is possible to apply a Ruleset to a Template by directly editing the Template, there is available a special overlay template called "Ruleset Linker" which can be used instead.

The overlay template's document ID is abb10be0-b9dc-11e7-8013-1f0b88022708, and placing this after a template's url with slash (/) will display the template's ruleset links as below.

Eg: https://whizzo-dev.formbird.com/#/form/07e7fbd0-cee3-11e5-aa08-fdabe14f1759/abb10be0-b9dc-11e7-8013-1f0b88022708

There is a link at the bottom of the overlay template which can be dragged to your bookmark bar for a quick way to view any template with this overlay.

Field-specific Ruleset linking

Available Formbird v4.x.x and later

OnFieldChange rulesets can be configured to execute only when specific fields are changed.

This is an optional feature only. If omitted, all fields trigger the ruleset.

To achieve this:

• Open your template where you linked a ruleset using document/template editor.
• Add a triggeredOn field to related document item and set the fields. Example:

 "onFieldChangeClientRuleRel": [
        {
            "documentId": "d8bc8340-c0b7-11e6-9eea-13b66331d97f",
            "name": "Acme Rental Car - OnFieldChange",
            "triggeredOn": ["buttonSetLRDNow", "decommissionedDate"]
        }
 ]

2024-01-15 - Currently not modifiable in the Ruleset Linker overlay.

Recommended Practice - OnFieldState Ruleset

You may notice in the above examples that OnLoad and OnFieldChange both call a common ruleset, called "XXXX - OnFieldState".

There is no actual event called "FieldState". It is what we might call a "pseudo event", which we can emulate by attaching an "OnFieldState" ruleset to events where it should occur.

An OnFieldState ruleset is a good place to script the setting of field states such as enablement and mandatoriness; this generally needs to be performed for all fields both on loading (OnLoad), plus for particular fields on a specific field changing (OnFieldChange). It should also be placed in PostSaveClient, in case any changes to document have occurred in saving.

For example, if a checkbox "Requires Verification" is checked, we want to enable and mandate the fields "Verification Detail" and "Verified By".

This needs to occur on the changing of the checkbox field, either to checked or unchecked. So, it needs to occur in response to the event "OnFieldChange".

It also needs to occur when we come back the next day and open this document again. Formbird documents do not remember their enabled/mandatory states from the previous browser session, so the states need to be applied again. So, it also needs to occur in response to the event "OnLoad".