Skip to content

Creating Emails in Rulesets

Emails can be triggered from server side rulesets, and can merge data from a document into the target email.

Email Template documents are used to format an email, using document field values and other dynamic values to change the content. Generally, email templates are written as a template for an email about a particular Formbird document template. An email template is invoked from a server side ruleset (PreSaveServer, PostSave, or via a scheduled action) to create emails to send.

Note
The term Email Template should not be confused with the general Formbird document template. Email Templates are documents used to format emails.

Email Template editing

Email Templates can be formulated using the screens below:

Current Listing URL

support.formbird.com/#/form/5657a6985bec6a9d0a93be96

Current Email Template URL

support.formbird.com/#/form/24d7eda0-ce29-11e5-bce0-c145a769f5e9

Email Template screen

Email Template fields

Name/Key

Email Templates are referenced by Name/Key. It is important that once an email template is in use, changes to the Name field might break processes that call that email template, unless those processes (eg rulesets) are recoded to call the new name.

To Recipients / CC Recipients

Optional. If the email is to go to fixed recipients, you can add any document here from the system that contains an email field.

It is possible to override these values later in ruleset script with different recipients, using the replacement tokens @to and @cc .

Subject

The subject line to go on the email. This can contain tokens from the corresponding document or to be replaced by script at runtime.

Email Template (field)

The "Email Template" field contains html markup code used to construct the eventual email.

Test Tokens

Test tokens are used to define test values for the document field tokens and other tokens, for display of the preview. They are NOT sent in the final email to any recipient. It is a JSON structure, following this syntax:

{
    "doc.fieldA"        : "valueA",
    "doc.fieldB"        : "valueB",
    ...,
    "tokenX"        : "value-token-X",
    …
}

Send Test Email on Save

(checkbox)

When checked, a test email, using the test tokens, will be sent to the current user.


Using Email Templates in Rulesets

Once an email template is formulated, it can be used from a server-side RuleSet to "draw" an email and send it.

Step 1

In your ruleset script, include the Email Functions includable:

#include "Email Functions JS";

(Requires the "Email Functions JS" RulesetInclude)

Step 2

Call the function launchEmail.

Syntax

object.launchEmail( ntf , emailTemplateName , replacements , function( errMsg ) {
     ...
});

Part Description
object Instance of the shared emailFunctions object from the #include.
Generally this would be
ft3.emailFunctions
ntf Instance of ntf from ruleset.
emailTemplateName Name of the Email Template to invoke.
replacements A javascript object containing key-value pairs to set how tokens are replaced in the email template.
See section below, Replacements
errMsg An error string resulting from the call. Null if successful.

Example

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

    ruleset : {
        ...

        // -------------------------------------------------------------------
        // Rule "Water On Alerting"
        // -------------------------------------------------------------------
        ruleWaterOnAlert : {
            ruleCondition : function(ntf) {
                ...
            },

            ruleAction : function(ntf, callback) {
                var ft3 = ntf.scope; 
                ntf.logger.info('Minimum expected water off reached.');

                var emailTemplate = 'Barwon Water On Alert';
                var calcDateM = ft3.moment(ntf.document.completed);
                var calcDateStr = calcDateM.format('DD MMM YYYY, h:mm a');

                var replacements = {
                    'urlRoot'           : ntf.urlRoot,
                    'completedDate'     : calcDateStr
                };

                ft3.emailFunctions.launchEmail(ntf, emailTemplate, replacements, function(errMsg) {
                    if (errMsg) {
                        ntf.logger.info(errMsg);
                    }
                    else {
                        ntf.logger.info('Email sent ok.');

                        ntf.document.waterOnNotificationSentTS = ft3.moment().toISOString();
                    }
                    callback();
                });
            }
        },

        ...
    }
}

Example (old style JS)

{
#include "Email Functions JS",

...
    mainRule : function(ntf, callbackContinue, callbackSuccess, callbackError) {
        var main = this;
        ...

        // -------------------------------------------------------------------
        // Rule "Water On Alerting"
        // -------------------------------------------------------------------
        if (
            ...
        ) {
            ntf.logger.info('In rule "Water On Alerting"');

            ntf.logger.info('Minimum expected water off reached.');

            var emailTemplate = 'Barwon Water On Alert';
            var calcDateM = ft3.moment(ntf.document.completed);
            var calcDateStr = calcDateM.format('DD MMM YYYY, h:mm a');

            var replacements = {
                'urlRoot'           : ntf.urlRoot,
                'completedDate'     : calcDateStr
            };

            main.emailFunctions.launchEmail(ntf, emailTemplate, replacements, 
            function(errMsg) {
                if (errMsg) {
                    ntf.logger.info(errMsg);
                }
                else {
                    ntf.logger.info('Email sent ok.');

                    ntf.document.waterOnNotificationSentTS = ft3.moment().toISOString();
                }

                ntf.hasRun.waterOnAlerting = true;
                callbackContinue(ntf);
            });

            return;                                            
        }

        ...
    }
}

Replacements

The replacements argument takes the form of a javascript object that contains key-value pairs which indicate tokens to be replaced in the email template. This is in addition to the {{doc.field}} and {{user.field}} tokens that should automatically be replaced.

var replacements = {
    token-name          : value,
    token-name      : value,
    etc
}

eg

    var replacements = {
        'urlRoot'           : 'https://comp-dev.formbird.com',
        'completedDate'     : '23 Mar 1989'
    };

will replace the following tokens:

{{urlRoot}}
{{completedDate}}

A note on Dates

Currently, using automatic tokens for date fields, eg {{doc.inceptDate}} will render an unpalatable representation of the date value, eg '2017-09-13T09:51:33Z'.

For this reason, the replacement structure can be used to set a manually configured token, eg {{inceptDate}}, to a nicely formatted date and/or time string, as in the example

    var inceptDateStr = ft3.moment(ntf.document.inceptDate).format('D MMMM YYYY');

    var replacements = {
        ...,
        'inceptDate'     : inceptDateStr    // '8 January 2016'
    };

Setting Recipients

If it is required to dynamically modify the recipients for the To, CC and BCC of an email template, this can be done through the replacements argument.

Token Description
@to Will replace the To recipient field.
A simple string value of email addresses, separated by comma, is required.
@cc CC recipients
@bcc BCC recipients

Note - this will fully replace any configured recipients from the email template, if used.

Example

    var replacements = {
        'urlRoot'           : 'https://comp-dev.formbird.com',
        'completedDate'     : '23 Mar 1989',
        '@to'               : 'algernon.blackwood@miskatonic.edu',
        '@cc'               : 'tobylong@parel.com.au,mickshort@parel.com.au',
        '@bcc'            : 'scully@xfiles.com'
    };