Skip to content

Lesson 5. Using Ruleset Includes

Updated pdexter 2022-12-19

Ruleset Includes are scripts containing re-usable functions and script that might be used by multiple rulesets.

Often we may make common scripting in several rulesets, which requires duplicate maintenance if the logic changes, or a fix is needed. By putting that logic within a Ruleset Include, we cut the required maintenance down to one location.

There may already be a few pre-existing ruleset includes in your system -- eg, "JayRule Ruleset Overlay JS" is one!

Step 1. Create a Ruleset Include

  • Open a new Ruleset Include

http://your-formbird/form/94869c359bf4131553761097

  • Set the name to "Acme Rental Car Functions" (or with your chosen organisation name)

  • Set the Group to "acme" (or your chosen organisation name)

  • In the script pane, enter the following script:

acmeRentalCarFunctions : {

    convertKmToMi : function(kmNum) {
        return (kmNum / 1.6);
    }

}
  • Save your Ruleset Include.

Step 2. Modify the Rental Car Template

  • Open your "Rental Car" template in the template editor
  • Add a button after the odometer field
{
    "componentName": "sc-button",
    "name": "buttonShowMiles",
    "caption": "Show as Miles"
},
  • Save the template.

Step 3. Script for the button click

  • Open your ruleset Acme Rental Car - OnFieldChange.
  • Include your new Ruleset Include into the ruleset. Place the #include statement after the first one for JayRule.
#include "Acme Rental Car Functions",
  • Add a new rule called "ruleShowOdometerInMiles".
  • Script its ruleCondition function to respond to the new button click
ruleCondition : { 
    fieldChanged : 'buttonShowMiles'
}
  • Script its ruleAction function as follows
ruleAction : function(ntf) { 
    var ft3 = ntf.scope;
    var odometerNum = ntf.document.odometer || 0;
    var milesNum = ft3.acmeRentalCarFunctions.convertKmToMi(odometerNum);
    var milesString = milesNum.toFixed(1);  // Limit to one decimal place

    ft3.ModalService.openModal('Odometer in Miles', milesString, 'info');
}    

When a Ruleset Include is #included, its objects and functions are stored under the global object ft3.

The full ruleset should look like:

{
#include "JayRule Ruleset Overlay JS",
#include "Acme Rental Car Functions",

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

        ruleInitialise : {
            ruleCondition : true,

            ruleAction : function(ntf) {
            }
        },

        ruleSetLRDNow : {
            ruleCondition : { 
                fieldChanged : 'buttonSetLRDNow'
            },

            ruleAction : function(ntf) { 
                ntf.document.lastRentedDate = new Date();

                ntf.logger.info('This is an information log line.');
                ntf.logger.debug('This is a debug log line.');
                ntf.logger.error('This is an error log line.');

            }
        },

        ruleShowReasonDecommissioned : {
            ruleCondition : {
                fieldChanged : 'decommissionedDate'
            },

            ruleAction : function(ntf) { 
                var ft3 = ntf.scope;
                // if decommissioned date is set, set flag true, else false
                var flag = !!ntf.document.decommissionedDate;

                ft3.showField('reasonDecommissioned', flag);
            }
        },

        ruleShowOdometerInMiles : {
            ruleCondition : { 
                fieldChanged : 'buttonShowMiles'
            },

            ruleAction : function(ntf) { 
                var ft3 = ntf.scope;
                var odometerNum = ntf.document.odometer || 0;
                var milesNum = ft3.acmeRentalCarFunctions.convertKmToMi(odometerNum);
                var milesString = milesNum.toFixed(1);  // Limit to one decimal place

                ft3.ModalService.openModal('Odometer in Miles', milesString, 'info');
            }
        }
    }
}

Step 4. Testing

  • Open a new or existing Rental Car document.
  • Make sure there is a value in the odometer field.
  • Click the button "Show as Miles".
  • A dialog should show, showing the Odometer reading in miles.

If the above is true, you have successfully created and used a Ruleset Include!

Caution

While it's possible to create whole rules in a Ruleset Include, and insert them into a host Ruleset at specific points, this is not advised or supported.

The accepted approach with Ruleset Includes is that they contain objects and functions that may be utilised from rules within your ruleset. This keeps the ruleset "topology" within your ruleset, and more succinctly modularises the functionality that is to be shared.

Lesson Items covered

  • Creating a Ruleset Include
  • Using a Ruleset Include within a Ruleset