Skip to content

Lesson 8. Writing a PreSaveServer ruleset

Updated pdexter 2022-12-20

This lesson covers the creation of our first server-side ruleset.

Our previous PreSave ruleset was a client-side ruleset, that is, it runs in the context of the user's browser session. Server-side rulesets run on the Formbird server, away from the user browser context.

PreSaveServer rulesets run after the browser successfully submits a document for saving. It also runs if the creation or update of the document occurs from any other context, such as an interface from a third party service or process.

As such, it does not allow client operations that work on the browser UI such as mandateField or showNotification. In this context, we have no knowledge of the user interface at all, only of the data itself (ie the document).

Step 1. Create the PreSaveServer Ruleset

  • Open the Ruleset Editor for a new Ruleset

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

  • Set the name of the RuleSet : Acme Rental Car Booking - PreSaveServer

  • 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 Booking - PreSaveServer',

        ruleInitialise : {
            ruleCondition : true,

            ruleAction : function(ntf) {
            }
        }
    }
}
  • Link this ruleset to the "Rental Car Booking" template, event "PreSaveServer", using the techniques described in Lesson 1.

Step 2. Create the Rental ID

Our aim here is to generate a value for RentalID on the Rental Car Booking document, on its first save, using the following elements concatenated:

  • The first three letters of the Customer surname.
  • The first letter of the Customer first name.
  • A hyphen.
  • The current date in the format YYMMDD.

Eg for customer Albus Dumbledore on 23 July 2019, we would create the RentalID "DUMA-190723"

  • Create a new rule called "ruleGenerateRentalId".
  • For the ruleCondition function, set so it only occurs if the RentalID field is not set:
ruleCondition : function(ntf) { 
    return (!ntf.document.rentalID);
}
  • For the ruleAction function, code as below:
ruleAction : function(ntf) { 
    var customer = ntf.document.customer;
    var newRentalId = customer.surname.slice(0,3).toUpperCase(); 
    if (customer.firstName) {
        newRentalId += customer.firstName.slice(0,1).toUpperCase();
    }
    newRentalId += '-' + ft3.moment().format('YYMMDD');

    ntf.document.rentalID = newRentalId;
}
  • Save your ruleset.

Step 3. Testing

  • Open an existing Rental Car document.

  • Scroll to the bottom, click on the dropdown "Add a new child document"

  • Click on Car Rental Booking

  • A new Car Rental Booking should display below this.

  • Enter the customer name : "Mrs", "Regina", "Turnbull"

  • Enter a pickup date.

  • Save

  • Reselect the just saved Booking from the grid, if necessary.

  • The Booking should have a Rental ID of "TURR-190513" (numeric value will differ according to the current date).

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

Debugging Server-side Rulesets

Because we are now working in server-side context, the previous means to debug rulesets do not apply. The rulesets will not write lines to the browser debugger console, instead they are written to a server log file, which can be difficult to get to.

Method 1. Terminal

The terminal method for debugging has been omitted here, due to changing processes, and is quite complicated. Discuss with Formbird administrators if this level of debugging is required.

Method 2. Email

The email method is probably the quickest way to get a first level debug of your ruleset, without having to log into servers and run linux commands. It delivers the ruleset only logging in an email to a designated email address. Further, it is limited only to a single run of the ruleset rather than from multiple runs and multiple users.

This relies on your Formbird server having been configured correctly with a working email service.

  • Add a new property to your ruleset, called "logging", which contains "debugEmail", eg
ruleset : {
    name : "Acme Car Rental Booking - PreSaveServer",

    logging : {
        debugEmail : "albus.dumbledore@hogwarts.edu.uk",
    }
    ...

Providing that the server is configured to send email, the designated email address will receive an email on each run of the ruleset, with all the logging that has come from that one run of the ruleset. As for the second method above, this is only the logging from the ruleset itself, not all the other loggings.

Once you have satisfactorily debugged your ruleset, you may want to remove the "debugEmail" setting, so you are not flooded with emails when the usage is in full production.

Example Email:

Ruleset Debug Output

The indicative error may not be displayed in the emailed output and it may still be necessary to use Method 1 to debug. But the email method is a handy first approach.

The email option may also not run, if the ruleset has significant syntax errors.

Lesson Items covered

  • Creating a PreSaveServer ruleset.
  • Debugging server-side rulesets.
  • Using email to debug server side rulesets.