Lesson 7. Writing a PreSave ruleset
Updated pdexter 2022-12-20
The PreSave ruleset is run in response to the user clicking the Save button in Formbird, and runs after the document's mandatory fields are verified, and before the document is actually saved.
There is an opportunity here to stop the Save, should the state of the document justify it, so it is an ideal place to script presave validation.
Step 1. Create the PreSave Ruleset
- Open the Ruleset Editor for a new Ruleset
https://your-formbird/form/224bc62858d73ce57a9cb85e
-
Set the name of the RuleSet : Acme Rental Car - PreSave
-
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 - PreSave',
ruleInitialise : {
ruleCondition : true,
ruleAction : function(ntf) {
}
}
}
}
- Link this ruleset to the "Acme Rental Car" template, event "PreSave", using the techniques described in Lesson 1.
Step 2. Add a validation rule for no future dates
Here we are going to validate that the Decommissioned date is not in the future. Only current or previous date-times are to be allowed. If the value violates this, then stop the Save.
- Open the new ruleset Acme Rental Car - PreSave
- Add a new rule called "ruleValidateDecommissionedDate"
- Code the following for the ruleCondition function
ruleCondition : function(ntf) {
var decomDate = ntf.document.decommissionedDate;
var decomDateM = ft3.moment(decomDate);
return (decomDate?.isAfter());
},
- Because we are using the library "moment", we need to include the rulesetInclude that incorporates this into our script. Add the following line near the top of the ruleset, beneath the include line for JayRule Ruleset Overlay
#include "Moment.js",
We make use here of the 3rd party date-time library "moment", which we call through ft3.
See Rulesets\moment (object) for more details.
Briefly, the function .isAfter() with no arguments returns true if the date is later than the current date-time.
- Code the following for the ruleAction
ruleAction : function(ntf) {
ntf.errorMessage = 'The Decommissioned date must not be a future date.';
}
By setting ntf.errorMessage, we are telling the system that we have found a problem, and the save should not go ahead. Normally, ntf.errorMessage is null or undefined.
- Save your ruleset.
Step 3. Add a validation rule for not earlier than the Opened Date
Here we validate that the Decommissioned date is not earlier than the Opened date.
- Add a new rule called "ruleValidateDecommissionedDate2"
- Code the following for the ruleCondition function
ruleCondition : function(ntf) {
var decomDateM = ft3.moment(ntf.document.decommissionedDate);
var openedDateM = ft3.moment(ntf.document.openedDate);
return (decomDate?.isBefore(openedDateM));
},
- Code the following for the ruleAction
ruleAction : function(ntf) {
ntf.errorMessage = 'The Decommissioned date must not be before the Opened date.';
}
- Save your ruleset.
The full ruleset should look like
{
#include "JayRule Ruleset Overlay JS",
#include "Moment.js",
ruleset : {
name : 'Acme Rental Car - PreSave',
ruleInitialise : {
ruleCondition : true,
ruleAction : function(ntf) {
}
},
ruleValidateDecommissionedDate : {
ruleCondition : function(ntf) {
var decomDate = ntf.document.decommissionedDate;
var decomDateM = ft3.moment(decomDate);
return (decomDate?.isAfter());
},
ruleAction : function(ntf) {
ntf.errorMessage = 'The Decommissioned date must not be a future date.';
}
},
ruleValidateDecommissionedDate2 : {
ruleCondition : function(ntf) {
var decomDateM = ft3.moment(ntf.document.decommissionedDate);
var openedDateM = ft3.moment(ntf.document.openedDate);
return (decomDate?.isBefore(openedDateM));
},
ruleAction : function(ntf) {
ntf.errorMessage = 'The Decommissioned date must not be before the Opened date.';
}
}
}
}
Step 4. Testing
-
Open an existing Rental Car document.
-
Set the Decommissioned Date to three months in the future.
-
Save
-
The saving will be stopped, with an error message that you coded.
-
Set the Decommissioned Date to three months earlier than the Opened Date.
-
Save.
-
The saving will be stopped, with an error message that you coded.
-
Set the Decommissioned Date to a valid date, later than the Opened Date, and earlier or on the current date time.
-
Save.
-
The saving will proceed okay.
If the above are true, you have successfully implemented a PreSave ruleset!
Lesson Items covered
- Creating and linking a PreSave ruleset
- Use of the moment library object (introductory)
- Setting of an error state in PreSave, to abort a document saving.