Ruleset Functions

Formbird Application Functions are those functions made available to rulesets from the Formbird application, and are used to interact with the Formbird document and data.

These functions are provided through the object ntf which is passed to all rulesets. They are provided in its property object scope. By convention, we assign ft3 to this object, so as to make later coding briefer.

By convention, we assign ft3 to ntf.scope early in a block of script,

var ft3 = ntf.scope;

ft3.enableField('customerName', false);

so we might use its member functions with the shorthand "ft3.function-name", rather than typing "ntf.scope.function-name". It would be quite valid to do away with ft3 and just use ntf.scope everywhere in your script; in this documentation though, we will be using ft3 by convention, so at least be aware of where it comes from.

ft3 can be considered the general portable toolbox that contains these functions (and others) we use in rules.

The following chapters describe each of those functions in full.

• checkChecklistItem
• createDocumentFromTemplate
• enableField
• findDocumentsByElastic
• getConfiguration
• getFilter
• mandateField
• markDocumentChanged
• openNewDocument
• scheduleNewSystemAction
• sendSMS
• setFilter
• showField
• showNotification
• updateDocument

There are also "library" or third party objects available from ft3:

• ModalService -- a modal dialog library
• moment -- a date-time handling library

checkChecklistItem

Sets a checklist field item to checked or unchecked on the document.

(client-side function)

Syntax

ft3.checkChecklistItem('field-name', 'option-name', 'state');

Example

    ft3.checkChecklistItem('wingColours', 'blue', true);
    ft3.checkChecklistItem('wingColours', 'red', false);

createDocumentFromTemplate

(Applies to both client-side + server-side function)

Creates a new document according to a given template.

Syntax

ft3.createDocumentFromTemplate(doc-info, templateID, userID, function(err,doc) {

​ ...

});

Example

    var newDocInfo = {
            "name": "Jennifer",
            "age" : 23,
            "description" : "Here lies the messenger." 
            };
    var templateID = '5511e701d1e0d8d0a7cc5414';

    var ft3 = ntf.scope;

    ft3.createDocumentFromTemplate(newDocInfo, templateID, ntf.user.documentId,
    function(err, doc) {
        if (err) {
            ntf.logger.error('Error creating document: ' + err);
        }
        else {
            ntf.logger.info('Document created: ' + doc.documentId);
        }
    });

See also

openNewDocument

deleteDocument

Deletes a document.

Applies to client-side and server-side rulesets.

Syntax:

ft3.deleteDocument(document-id, function(err) {

  ...

});

Example

not yet available

enableField

(Applies to client-side rulesets)

Sets the enablement of a field on the document.

Syntax:

ft3.enableField(field-name, state)

Example

var ft3 = ntf.scope;

ft3.enableField('establishmentDate', false);

// Disable field if document is closed
var flag = !(ntf.document.status === 'Closed');
ft3.enableField('status', flag);

Note

To enable fields on a parent document in the case that a child document is open, precede the field-name with "parentDoc", eg "parentDoc.lastName".

To enable fields on a child document in the case that a child document is open, precede the field-name with "childDoc", eg "childDoc.lastName".

findDocumentsByElastic

(Applies to server-side and client-side rulesets)

Function to make a query (ElasticSearch) and retrieve a "resultset" of documents.

Syntax

ft3.findDocumentsByElastic(query, user-id, [options,] function(err, result) {

        ...

})

options

The optional argument options can contain alternative options/switches to change the mode of the query.

ElasticSearch result size

This method has a default results limit of 50 documents.

The result returned will contain the full number of matching documents, (result.data.hits.total), but the actual returned documents will only number 50.

To change this, add a "size": n element to the ElasticSearch query. This will override the default size added by the appserver (see example).

Example

    ft3 = ntf.scope;
    ...

    var eqry = {
        'size' : 1000,
        'query': {'bool': {'filter' : [
            {'term': {'type' : 'insect'}},
            {'term': {'color' : 'blue'}}
        ]}}
    };

    // Modify from, size dynamically after the eqry statement
    eqry.from = 100;
    eqry.size = 500;
    eqry.sort = [{'commonName':'asc'}];

    ft3.findDocumentsByElastic(eqry, ntf.user.documentId, function(err, result) {
        if (err) {
            ntf.logger.info('Error: ' + err.message);
        } 
        else {
            var i;
            ntf.logger.info('# Total Matches in DB: ' + result.data.hits.total);
            ntf.logger.info('# Returned Results: ' + result.data.hits.hits.length);
            for (i=0;i < result.data.hits.hits.length;i++) {
                var doc = result.data.hits.hits[i]._source;
                ntf.logger.info('Blue Insect [' + i + ']: ' + doc.name);
            }
        }
    });
    return;

Tip

Use the javascript map function for arrays to convert an ElasticSearch result to an array of documents:

var docs = result.data.hits.hits.map(function(hit) { return hit._source });
// OR
var docs = result.data.hits.hits.map(hit => hit._source);

Suggested Enhancement

Handling of ElasticSearch results can be simplified by use of the ft3 Extension Functions esResult object.

See ft3 Extension Functions#esResult

Limiting the fields returned

In order to reduce the number of fields of documents returned, use a sourceFilter option.

// Enter code here
var eqry = {"query": {"bool": {"filter": [
    {"term" : {"appTags" : "spider"}},
    {"term" : {"systemHeader.systemType" : "document"}}
]}}};

var options = {
    sourceFilter : {
        include : ['commonName','genus','species']
    }
};

ft3.findDocumentsByElastic(eqry, ntf.userId, options, function(err, result) {
    if (err) {
        ntf.logger.error('Error on query: ' + err.message);
    }
    else {
        var firstDoc = result.data.hits.hits[0]._source;
        ntf.logger.info('first document: ' + JSON.stringify(firstDoc));
        // shows {"commonName": "Huntsman", "genus": "Beregama", "species": "Aurea"}
    }
});

Result topology

The result object returned by this function is a full ElasticSearch result structure, so may be quite arcane to dissect. The following properties are the most useful ones for our purposes.

Sample ElasticSearch result

{
  "statusCode": 200,
  "data": {
    "took": 2,
    "timed_out": false,
    "_shards": {
      "total": 5,
      "successful": 5,
      "failed": 0
    },
    "hits": {
      "total": 1,
      "max_score": 0,
      "hits": [
        {
          "_index": "gobble",
          "_type": "documents",
          "_id": "584f25cf22478a32c64c440e",
          "_score": 0,
          "_source": {
            "event": "OnLoad",
            "systemHeader": {
              "summaryName": "Dexwise Spider - OnLoad",
              "serverUpdatedDate": "2017-12-19T04:14:14.207000+00:00",
              "systemType": "document",
              "excludeGeneralSearch": false,
              "templateId": "224bc62858d73ce57a9cb85e",
              "serverDate": "2017-03-07T05:28:24.514Z",
              "currentVersion": true,
              "versionId": "12e837f0-e473-11e7-a189-39e2cecb7850",
              "createdWith": "224bc62858d73ce57a9cb85e",
              "summaryDescription": "RuleSet for processing of template Spider (et al), OnLoad event.",
              "createdBy": "5476946bb671fc07650beed1",
              "createdDate": "2017-12-19T04:14:14.767000+00:00",
              "serverCreatedDate": "2017-12-19T04:14:14.207000+00:00",
              "previousVersionId": "91c0bd80-e46f-11e7-a189-39e2cecb7850"
            },
            "businessType": "RuleSet",
            "flagInPreSave": true,
            "syncTemplateRule": true,
            "versionTag": "20171018A",
            "ruleSetGroup": "dexwise",
            "addSecurityKeys": [
              {
                "name": "DA-Dexwise-Rulesets",
                "documentId": "b8d9eeb0-02f6-11e7-965b-4799f2a39188"
              }
            ],
            "objectEventDescriptor": "Dexwise Spider - OnLoad",
            "template": [
              {
                "name": "Spider",
                "documentId": "c6a8eb50-c029-11e6-9eea-13b66331d97f"
              }
            ],
            "vtn": "system.ruleset",
            "appTags": [
              "system",
              "ruleset"
            ],
            "documentId": "abbff110-c0b7-11e6-9eea-13b66331d97f"
          }
        }
      ]
    }
  },
  "filter": false
}

findVersionDocument

(server-side)

Retrieves a version of a document by its versionId.

Syntax

ft3.findVersionDocument(versionId, userId, function(err, document) {

    ...

})

Example

    ntf.logger.info('Running findVersionDocument');
    ft3.findVersionDocument('3624da40-fd08-11e7-b927-e74a925fc9ea', ntf.user.documentId, function(err, document) {
        if (err) {
            ntf.logger.error(err);
        }
        else {
            ntf.logger.info('Retrieved document version: ' + document.systemHeader.versionId); 
            ntf.logger.info('_id: ' + document._id);
        }
        callback();
    });

getConfiguration

(server-side function)

Function to get configuration entries, either from the configuration document in the database, or from Config.js in the file system for fieldtec-web.

(nb - scope of fetchable configuration may have changed since this document)

Syntax

value = ft3.getConfiguration(key);

Example

    var ft3 = ntf.scope;

    // Get configuration from main configuration document
    var templateId = ft3.getConfiguration("clientConfiguration.ruleSetIncludeTemplateId");

    ntf.logger.info('Env = ' + env1 );
    ntf.logger.info('RSInc TID = ' + templateId);

getDeep

Function to return the value of a property located deep within a chain of objects, without having to verify the existence of each object in the chain.

If any object along the chain is undefined or null, then returns null.

(client-side/server-side function)

Availability

This function is available from JayRule v20210718 (Kafkaesque Koala).

Syntax

value = ft3.getDeep(object, path);

Example

var streetName = ft3.getDeep(ntf.document.locationGeo, 'features.0.properties.street');

Javascript Optional Chaining

(In Javascript ...) The optional chaining operator (?.) enables you to read the value of a property located deep within a chain of connected objects without having to check that each reference in the chain is valid. [MDN Web Docs]

Optional chaining is available within client ruleset script, but currently (2021-08-13) not available in our server script (dependent on Node.JS version).

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining

If a future version of Formbird has a version of NodeJS which supports optional chaining, this would then be the preferred method.

getFilter

Function to return the ElasticSearch query filter used by an instance of a grid or related field component.

(client-side function)

Syntax

value = ft3.getFilter(field-name);

Example

    var oldFilter = ft3.getFilter('gridWidgets');

See Also

setFilter

htmlEncode

Function to encode variables of unknown value, to ensure that script injection does not occur.

This should be used for all cases where a value to be displayed in rendered html is not explicitly defined in the code. It may have been sourced from a data query result.

This function has been built into JayRule (Jealous Jerboa) and later; if not there, please advise JayRule author.

Syntax

value = ft3.htmlEncode(rawValue);

Example

var rawValue = `Jim Jones <script>alert("you shouldn't see this popup");</script>`;

var html = ft3.htmlEncode(rawValue);
// returns "Jim Jones &lt;script&gt;alert(&#34;you shouldn&#39;t see this popup&#34;);&lt;/script&gt;"

lazyLoader

Object; Loads a third party library in order to use it within a ruleset.

This has the advantage that loaded libraries are still available when the app is offline (to be confirmed).

(client-side object)

Syntax

ft3.lazyLoader.load({...

      name : name-of-library,

        files : [

                url1,

                url2, etc

        ]

})

.then(function() {

        // initialise library object

})

Example

ft3.lazyLoader.load({name: 'swal', files: [
    "https://cdnjs.cloudflare.com/ajax/libs/limonte-sweetalert2/6.6.2/sweetalert2.min.js",
    "https://cdnjs.cloudflare.com/ajax/libs/limonte-sweetalert2/6.6.2/sweetalert2.min.css"
]})
.then(function() {
    // Assign fetched object to our own ft3.
    ft3.swal = swal;
});

​

loadComponentLibrary

Loads a library object from a Formbird component, so as to be able to manipulate/query a field on screen.

This requires knowledge of the specific component, and what library service and function it offers.

(client-side function)

Syntax

ft3.loadComponentLibrary(service-name, function(error-message, library) {

  ...

})

Example

// ---------------------------------------------------------------------------------
// Wrapper function to update layers on the sc-address-map component.
// ---------------------------------------------------------------------------------
updateMapLayers : function (ntf, componentType, componentName, newLayers, callbackF) {
    var ft3 = ntf.scope;

    ft3.loadComponentLibrary('sclMapRulesInterface', function (errMsg, mapLibrary) {
        if (errMsg) {
            ntf.logger.error('Error in calling MapLibrary: ' + errMsg);
            callbackF(false);
        }
        else {
            ntf.logger.info('MapLibrary called.');

            mapLibrary.setMapLayers(componentType,componentName,newLayers);

            callbackF(true);
        }
    });
}

mandateField

Makes a field on the document mandatory or not mandatory. When mandatory, the field must have a non-blank value for the document to be saved.

(client-side function)

Syntax

ft3.mandateField( field-name, state)

Example

ft3.mandateField('status', true);
ft3.mandateField('widgetColor', false);

Note

To mandate fields on a parent document in the case that a child document is open, precede the field-name with "parentDoc", eg "parentDoc.lastName".

To mandate fields on a child document in the case that a child document is open, precede the field-name with "childDoc", eg "childDoc.lastName".

markDocumentChanged

Sets the document to a dirty state, thus showing the save tick icon at the top.

Syntax

ft3.markDocumentChanged()

Example

ft3.markDocumentChanged();

ModalService (object)

A function Object for presenting message dialogs to the user.

(client-side function)

As of Formbird v3.1.x, the ModalService object is no longer initialised with the SweetAlert library object.

See below Post Formbird 3.x.x Implementation for current practice.

Syntax

ft3.ModalService.openModal(args)

ft3.ModalService.openModal(options)

.then(

    function confirmFunction() { .... }

    function dismissFunction(dismissType) { ... } );

~~ft3.ModalService.swal(args)~~ !!! AVOID USING IN NEW RULESETS

Post Formbird 3.x.x Implementation

Due to conflicts within the Formbird application, the ModalService as provided no longer offers the SweetAlert library functionality, and now only offers a limited dialog service.

This service is basically limited to the following mode of coding:

    ft3.ModalService.openModal('Test Message Title', 'This is a test of the button functionality in ruleset script.', 'success');

Ie, a simple three argument function.

If the more complex dialog features as described below are required, then we need to add the following to the top of our ruleset (below #include "JayRule Ruleset Overlay JS"):

#include "SweetAlert Dialog",

providing that your system has the Ruleset Include "SweetAlert Dialog", and that your JayRule is at least version "Haughty Hedgehog" which will run included rules.

For prior versions of JayRule, you can still use this #include, but you will have to manually call in your own initial rule:

ft3.initialiseSweetAlert(ntf, function() {
    // sweetalert is initialised
})

This loads the SweetAlert2 version 6.6.2, which was in place prior to Formbird 3.x.x. Ruleset code that formerly used this dialog functionality will work with this version of SweetAlert.

The SweetAlert library has undergone many changes to its functionality signature, such that changing from some versions to another involves a huge amount of code refactoring.

Should you wish to use another version of SweetAlert, using your own initialisation script, be advised that you will need to be very familiar with the new or different functionality and function arguments.

Options

(From SweetAlert documentation - some discrepancies may occur)

Options marked "Definite" are envisaged to be supported for the full term of the component development in future. Others may also be continued on, and this table is subject to change re those.

Example 1

    ft3.ModalService.openModal('Test Message Title', 'This is a test of the button functionality in ruleset script.', 'success');

Example2

    ft3.ModalService.openModal({
      title: 'Are you sure?',
      text: "You won't be able to revert this!",
      type: 'warning',
      showCancelButton: true,
      confirmButtonColor: '#3085d6',
      cancelButtonColor: '#d33',
      confirmButtonText: 'Yes, delete it!',
      cancelButtonText: 'No, cancel!'
    })
    .then(
        function confirmFunction () {
          ft3.ModalService.openModal(
            'Deleted!',
            'Your imaginary file has been deleted.',
            'success'
          );
        }, 
        function dismissFunction(dismiss) {
          // dismiss can be 'cancel', 'overlay',
          // 'close', and 'timer'
          if (dismiss === 'cancel') {
            ft3.ModalService.openModal(
              'Cancelled',
              'Your imaginary file is safe :)',
              'error'
            );
          }
        }
    );

Note

ModalService.openModal is based on the third party library SweetAlert.

openNewDocument

Opens a new document of a given template, in the current or a new window.

(client-side function)

Syntax

ft3.openNewDocument( template-id, initial-values, new-window, function(err) {

        ...

});

where

Example

       var ft3 = ntf.scope;
       var TPL_ID = 'b62410d1e601a95aacdb9c6f';
       var initialValues = {
            'genus'   : 'Cicadidae',
            'species' : 'Exuviae',
            'commonName' : 'Cicada'
       };

       ft3.openNewDocument(TPL_ID, initialValues, 'yes', function(err){
            if (err) {
                ntf.logger.info('Error opening new document: ' + err.message);
            }
            else {
                ntf.logger.info("New document opened.");            
            }
       });

Note

For a server side version, see createDocumentFromTemplate.

sanitizeHtml

Sanitises HTML strings to ensure there is no script injection.

The imprudent setting of html to elements of the page can under some circumstances result in breaking of the page, or worse. This function is designed to scan any html string and prevent any script injection from occurring.

(client-side function)

Availability

Available from JayRule v20210211 (Indolent Iguana ++)

Syntax

value = ft3.sanitizeHtml( html )

Example

var badHtml = '<div>aaa</div><IMG """><SCRIPT>alert("XSS")</SCRIPT>"\>';

$('div#divParentcmdRunMe12 button').html(ft3.sanitizeHtml(badHtml));

ft3.ModalService.openModal({
    title : 'san html test',
    html : ft3.sanitizeHtml(badHtml)
});

scheduleNewSystemAction

Schedules a System Action to occur in the future, which runs a RuleSet.

(server-side function)

Syntax

ft3.scheduleNewSystemAction( document, checkDate, objectEventDescriptor, user, function(err, systemActionDocument ) {

       ...

})

Example

        var ft3 = ntf.scope;
        var nbrMinutesToWait = 15;
        var checkDate = new Date();
        var templateId = '944e24fb8cf0a381942b3e77';

        checkDate = ft3.moment().add(nbrMinutesToWait, 'minute');

        // Create a stripped down version of the document to pass
        var docToPass = {
            documentId : ntf.document.documentId,
            note : 'document truncated - query for current'
        };

        ft3.scheduleNewSystemAction(docToPass, checkDate, 'Task-Direct-LoneOvertime',
                ntf.user, function(err, doc) {
            if (err) {
                ntf.logger.info(err.message);
            }
            else if (doc) {
                logger.info('New system action created: ' + doc.documentId);
            }
            ...
        });
        return;

Tip

When passing the document to this method, remove most of the document content and leave just the documentId. It is most probably important for the target ruleset to query for the current document from the database anyway, using documentId.

This will avoid any issues with using an out of date version of the document in the target ruleset, as ntf.document received by the ruleset will be as was passed when this function was called, not automatically what is current in the database.

var ft3 = ntf.scope;
var docToPass = {
  documentId : ntf.document.documentId,
  note : 'This document is truncated to just the documentId -- query for current.'
};

ft3.scheduleNewSystemAction(docToPass, checkDate, 'Task-Direct-LoneOvertime', ntf.user, function(err, doc) { ...

setFilter

Sets the ElasticSearch query filter on an instance of ft-grid, ft-related-document, and other field types.

(client-side function)

Syntax

ft3.setFilter( field-name , new-filter )

Applies to

The setFilter function applies to:

• ft-grid, or similar custom grid components
• ft-related-document
• ft-address-map

Example

    var oldFilter = ft3.getFilter('gridWidgets');

    var newFilter = {'query':{'bool':{'filter':[{'match':{'color':'turquoise'}}]}}}; 

    ft3.setFilter('gridWidgets', newFilter);

See Also

getFilter

showField

Shows or hides a field on the document.

(client-side function)

Syntax

ft3.showField( field-name , state );

Note

To show/hide fields on a parent document in the case that a child document is open, precede the field-name with "parentDoc", eg parentDoc.lastName.

To show/hide fields on a child document in the case that a child document is open, precede the field-name with "childDoc", eg childDoc.lastName.

showNotification

Shows a notification message that displays in the top right corner of the page.

(client-side function)

Syntax

ft3.showNotification( message , status );

updateDocument

Function to update a document.

(client & server-side function)

Syntax

ft3.updateDocument(doc-id, change, user-id, function(err, doc) {

  ...

});

WARNING

(Applies to Formbird prior to v3.1.x)

Using updateDocument within a PostSave ruleset on the same document can result in a runaway process where the document keeps saving over and over ad infinitum.

Preferably, move any such changes to PreSaveServer where the ntf.document object can still be modified normally, without needing to call updateDocument.

If it is necessary to still use it in PostSave, then use the PostSaveLoopPrevention method to update the document.

Formbird v3.1.x and later has built in protection from looping PostSave self updates.

-- pd 2020-06-03

Example

    var change = {
        'saDateMark' : new Date()
    };

    ft3.updateDocument(ntf.document.documentId, change, ntf.user.documentId, 
    function(err, doc) {
        if (err) {
            ntf.logger.error('Error in updateDocument: ' + err);
        }
        else {
            ntf.logger.info('Document updated successfully.');
        }
        callback();
    });