ntf Object

Updated pdexter 2022-10-22

The ntf object passed into rulesets has a number of built in sub-objects and properties useful to the ruleset writer.

ntf.document

This object represents the document in memory, as presented on the current browser page, or that is being operated on. As such, it has no specific utility properties common to all usages.

Eg, ntf.document.documentId is the documentId of the document.

Eg, ntf.document.coverColour is the value of the field "coverColour" on the document.

It has the further advantage that any attributes attached to it will persist through the document browser session that the document is opened in. An attribute attached in its OnLoad ruleset will still be present in later calls to OnFieldChange, PreSave and PreSaveServer rulesets.

This can be handy for setting flags if a particular field is set, eg

/// OnFieldChange
ntf.document.flagAssigneeChanged = true

...
/// PreSave
if (ntf.document.flagAssigneeChanged) {
    // do verification
    ...
    delete ntf.document.flagAssigneeChanged;
}

Caution - changes made to ntf.document during client side rulesets will persist right through to saving, if not removed, and you may end up with extraneous data saved with the document. For this reason, you should delete any such flag properties in PreSave or PreSaveServer.

Note - from Formbird v3.3.1-next.63, ntf.documentSession should be used for storing temporary value. See section below.

ntf.context

ntf.context is an object containing context information for use by a ruleset.

This information varies between different ruleset events. Generally there is a wide difference between server side rulesets (PreSaveServer, PostSave) and client-side (PreRender, OnLoad, OnFieldChange, PreSave, PostSaveClient)

Property	Description	Available In
appVersion	String; version of the Formbird application	all
eventName	String; descriptor of the Event under which this ruleset is occurring Values: PreRender OnLoad OnFieldChange PreSave PostSaveClient PreSaveServer * PostSave	all

fieldChanged	String; The name of the field that triggered OnFieldChange event. This is set only in OnFieldChange.	OnFieldChange
hostUrlRoot	String; the URL Root of the server.	Server-side
newValue	(any); The new value of the field that triggered an OnFieldChange event.	OnFieldChange
oldValue	(any); The previous value of the field that triggered an OnFieldChange event.	OnFieldChange
template	Object; the full template document of the current document.	Client-side
templateId	String; The templateId of the current document. Also generally available through ntf.document.systemHeader.templateId	Client-side
user	Object; The user account document of the current user. This is the same object as ntf.user. nb: this is readonly	all

The following are redundant properties and should be ignored.

Property	Description	Available In
formParameters	Object; not used	Client-side
logger	Object; not used	all
rsLogger	Object; not used	Server-side
ruleSetDoc	Object; not used	Server-side
ruleSetId	String; not used	Server-side
ruleSetLogTemplateId	String; not used	Server-side

ntf.user

ntf.user is basically a copy of the current user's account document.

The most useful properties here for use in rulesets are:

Property	Description
documentId	String; The current user's account documentId (In JayRule rulesets, ntf.userId is set to this value anyway)
email	String; The current user's email address.

ntf.scope

ntf.scope can be considered the toolbag of rulesets.

In general, we assign the object variable ft3 to this object. So for the most part, we can ignore ntf.scope.

It carries all the ruleset functions we use within rulesets. See Ruleset Functions.

ntf.documentSession

Available with Formbird v3.3.1-next.63

ntf.documentSession is a persistent object "bag" which persists for the entire lifecycle of the document, from OnLoad >> OnFieldChange >> PreSave >> PreSaveServer >> PostSave, and across client/server side ruleset events.

Example

--- ONLOAD ---
ruleSetSessionObjects : {
    ruleCondition : true,

    ruleAction : function(ntf) {
        ntf.logger.info('dsTimeStamp - ' + ntf.documentSession.dsTimeStamp);
        ntf.documentSession.dsTimeStamp = ft3.moment().format();
        ntf.documentSession.timeStampOB = ft3.moment().toDate();
        ntf.logger.info('dsTimeStamp` - ' + ntf.documentSession.dsTimeStamp);
    }
}

...

--- ONFIELDCHANGE ---
ruleTestSessionObjects : {
    fieldChanged : 'cmdTestDocumentSession',

    ruleAction : function(ntf) {
        var storedString = ntf.documentSession.dsTimeStamp, 
        storedDateOB = ntf.documentSession.timeStampOB;
        ntf.logger.info(`dsTimeStamp (fieldChanged) - ${storedString}`);
        ntf.logger.info(`timeStampOB (date) - ${storedDateOB}`);
    }
}

As demonstrated above, one can set objects within documentSession, however the objects are stringified to JSON in the background, therefore one needs to not set "active" objects, eg with function properties, which would get stripped out.

This should be used to replace previous practice of setting a temporary flag or value on the ntf.document (which was the only persistent object available), reacting to it in later rulesets, then remembering to delete the flag/value before or on saving the document.