Lesson 9. Writing a PostSave ruleset

Updated pdexter 2022-12-20

A PostSave ruleset is called after a document is saved.

It can be considered to be outside of the document lifecycle, the document having already been saved.

In this lesson, we script a PostSave ruleset to send an email after a document is saved.

Caveat

Ensure that your Formbird server is configured for sending of emails.

Step 1. Prepare an Email Template

An Email Template is a document that contains settings and a layout for an email to be sent from a ruleset.

We will provide a simple Email Template for you to insert into your system via the Template Editor, without going into detail on Email Templates themselves.

For more details on Email Templates and their usage, see Creating Emails in Rulesets.

Copy the following and paste into a new document under Template Editor. Please note, the systemHeader elements should be merged to what appears in the systemHeader on the form.

{
    "systemHeader": {
        "templateId": "24d7eda0-ce29-11e5-bce0-c145a769f5e9",
        "summaryName": "Acme Rental Car Change Notification",
        "systemType" : "document"
    },
    "vtn": "system.email_template",
    "appTags": [
        "system",
        "email_template"
    ],
    "etName": "Acme Rental Car Change Notification",
    "subject": "Acme Rental Car Change Notification - {{doc.registration}}",
    "emailTemplateContent": "<h3>Acme Rental Car Change</h3>\n\n<p>The following profile has been updated on {{updatedDate}}: <a href=\"{{urlRoot}}/form/{{doc.documentId}}\">Car Registration: {{doc.registration}}</a></p>"
}

Save
Your new EmailTemplate should be now loaded in the browser.
Edit the new Email Template by putting your own email address in the "To" field, and saving.

Step 2. Create the PostSave ruleset

Open the Ruleset Editor for a new Ruleset

https://your-formbird/form/224bc62858d73ce57a9cb85e

Set the name of the RuleSet : Acme Rental Car - PostSave
Group can be set to acme, or your organisation name
Save your new ruleset.

The script pane will show the following:

{
#include "JayRule Ruleset Overlay JS",

    ruleset : {
        name : 'Acme Rental Car - PostSave',

        ruleInitialise : {
            ruleCondition : true,

            ruleAction : function(ntf) {
            }
        }
    }
}

Link this ruleset to the "Rental Car" template, event "PostSave", using the techniques described in Lesson 1.

Step 3. Scripting to email notification

Below the beginning of the script, under the first #include line, include the Email Functions ruleset include.

#include "Email Functions JS",

Add a debug email address, to receive any debugging.

    logging : {
        debugEmail : 'harry.potter@hogwarts.edu.uk',  // example only!!
    }

Create a rule to send the email, named "ruleSendChangeNotification"
For the ruleCondition, script as follows

ruleCondition : true,

This will run the rule for every saving of the document; later on you might want to change the condition to only be if a particular attribute of the Rental Car document is set, eg if a prestige car.

For ruleAction, script as follows

ruleAction : function(ntf, callback) { 
    var emailTemplateName = 'Acme Rental Car Change Notification';

    // Here we nominate the replacements to the handlebarred tokens 
    // in the Email Template document
    var replacements = {
        'urlRoot' : ft3.getConfiguration('urlRoot'),
        'updatedDate' : ft3.moment().format('ddd DD MMM YYYY h:mm a')
    };

    ft3.emailFunctions.launchEmail(ntf, emailTemplateName, replacements, 
    function(errMsg) {
        if (errMsg) {
            ntf.logger.error('Error on emailing: ' + errMsg);
        }
        else {
            ntf.logger.info('Email notification sent ok.');
        }
        callback();
    });
}

You might notice above, the ruleAction function has an extra argument, called "callback".

This argument is used when we are performing an asynchronous operation in the action, in this case it's the launchEmail function from emailFunctions (sourced from the ruleset include "Email Functions JS"). Because we need to wait for asynchronous functions to complete, we need to delay proceeding to the next rule of the ruleset by including a callback argument to the ruleAction, and calling callback(); when our process is complete, ie within the asynchronous function's own callback function.

More detail on asynchronous rules is provided in the next lesson (Lesson 10).

Save your ruleset.

The full ruleset should look like

{
#include "JayRule Ruleset Overlay JS",
#include "Email Functions JS",

    ruleset : {
        name : 'Acme Rental Car - PostSave',
        debugEmail : 'harry.potter@hogwarts.edu.uk',

        ruleInitialise : {
            ruleCondition : true,

            ruleAction : function(ntf) {
            }
        },

        ruleSendChangeNotification : {
            ruleCondition : true,

            ruleAction : function(ntf, callback) { 
                var ft3 = ntf.scope;
                var emailTemplateName = 'Acme Rental Car Change Notification';

                var replacements = {
                    'urlRoot' : ft3.getConfiguration('urlRoot'),
                    'updatedDate' : ft3.moment().format('ddd DD MMM YYYY h:mm a')
                };

                ft3.emailFunctions.launchEmail(ntf, emailTemplateName, replacements, function(errMsg) {
                    if (errMsg) {
                        ntf.logger.error('Error on emailing: ' + errMsg);
                    }
                    else {
                        ntf.logger.info('Email notification sent ok.');
                    }
                    callback();
                });
            }
        }
    }
}

Step 4. Testing

Open an existing Rental Car document.
Make any change.
Save
Wait a minute or so.
Check your email.
You should receive a formatted email indicating the change made.

If the above is true, you have successfully created a PostSave ruleset!

Lesson Items covered

Creating a PostSave ruleset.
Use of callback in asynchronous processes.
Sending a simple Email Notification.