ft3 Extension Functions

Updated pdexter 2026-06-26

ft3 Extension Functions is a Ruleset-Include which is designed to add "helper" functions which can simplify coding with some of the complex objects we come across in rulesets.

The following details pertain to the "ft3 Extension Functions" version 202606A. Some functionality may be missing in earlier versions.

Usage

Include the rulesetInclude "ft3 Extension Functions"

#include "ft3 Extension Functions",

Objects/Functions Available

createCustomSystemAction

Creates a system action, allowing for a particular template of systemAction. Can also be run from client-side, if needed.

Syntax

var systemActionDoc = await ft3.createCustomSystemAction(ntf, documentData, dueDate, rulesetIdentifier, userId, templateId );

Example

const SYSTEM_ACTION_TID = '0dc38480-7d90-11e8-85a6-a31cfaaba53d';

var docData = {
    documentId : ntf.document.documentId,
    systemHeader : {
        summaryName : 'System Action Process for Test 2026-06-25'
    }
};

// Launch System Action
var saDoc = await ft3.createCustomSystemAction(ntf, docData, new Date('2066-09-23'), 
    'Dexwise Spider - OnSystemAction Zero', ntf.userId, SYSTEM_ACTION_TID);

ntf.logger.info('SA created: ' + saDoc?.documentId);

getCountByEqry

Returns a count of documents in the database which match a specified query.

This is intended to be used in place of the full ft3.findDocumentsByElastic call with handling function when all that is required is the count of resulting documents.

This is an awaitable function, hence knowledge of async/await is required. The containing ruleAction block is required to be declared "async".

If an error occurs, then the variable ntf.errorOnEqry is set (error object).

Caveat: This value may be inexact for queries which cover very large numbers of documents, under ElasticSearch 7; the upper limit here is 10000. Note: As of "ft3 Extension Functions" version 202212A, this upper limit is not a problem.

Internally, this only queries for a maximum of 1 result, thus reducing network traffic, but the full potential count is returned for use.

Example

    ruleAction : async function(ntf, callback) {
        var ft3 = ntf.scope;

        // -----------------------------------------------------------------
        // Query for open Costs on this Action
        // -----------------------------------------------------------------
        var eqry = {'query':{'bool':{
            'filter':[
                {'term':{'appTags':'cww'}},
                {'term':{'appTags':'cost'}},
                {'term':{'parentsRel.documentId':ntf.document.documentId}}
            ],
            must_not : [
                {term : {'status' : 'Cancelled'}}
            ]
        }}};

        var recCount = await ft3.getCountByEqry(ntf, eqry);

        if (ntf.errorOnEqry) {
            ntf.errorMessage = 'Error in query for Costs: ' + ntf.errorOnEqry.message;
            callback(); return;
        }

        ntf.logger.info('Found ' + recCount + ' Cost items.');

        callback();
    }

getDialogConfirm

THIS CAN BE REPLACED WITH FORMBIRD DIALOG'S FUNCTION fbDialog.confirm(..)

Returns true or false on a confirmation dialog, structured with SweetAlert.

Requires the #include "SweetAlert Dialog" or "Formbird Dialog"

This is an awaitable function, hence knowledge of async/await is required. The containing ruleAction block is required to be declared "async".

Syntax

var confirmFlag = await ft3.getDialogConfirm(ntf, dialogOptions);

var confirmFlag = await ft3.getDialogConfirm(ntf, dialogText);

Example 1

ruleAction : async function(ntf, callback) {
    var ft3 = ntf.scope;

    var confirm = await ft3.getDialogConfirm(ntf, {
        title : 'Waiting',
        text : 'Click ok when ready'
    });

    if (confirm) {
        ft3.showNotification('Ok clicked');
    }
    else {
        ft3.showNotification('Cancel clicked')
    }
    callback();
}

Example 2

ruleAction : async function(ntf, callback) {
    var ft3 = ntf.scope;

    var confirm = await ft3.getDialogConfirm(ntf, 'Click ok when ready');

    if (confirm) {
        ft3.showNotification('Ok clicked');
    }
    else {
        ft3.showNotification('Cancel clicked')
    }
    callback();
}

getDocsByEqry

Returns an array of documents for a specified query.

This is intended to be used in place of the full ft3.findDocumentsByElastic call with handling function when all that is required is the resulting documents (arguably 99% of all usages).

This is an awaitable function, hence knowledge of async/await is required. The containing ruleAction block is required to be declared "async".

Syntax

var documents = await ft3.getDocsByEqry(ntf, eqry [, options]);

Example

ruleQuerySpiderNames : {
    ruleCondition : function(ntf) { 
        return (
            ntf.context.fieldChanged === 'commonName'
            && ntf.context.newValue === 'test000'
        );
    },

    ruleAction : function(ntf, callback) { 
        var ft3 = ntf.scope;
        var eqry = {"query": {"bool": {"filter": [
            {'term' : {'appTags' : 'spider'}},
            {'term' : {'systemHeader.systemType' : 'document'}}
        ]}}}; 
        eqry.size = 5;

        var options = {
            includeDeleted : true
        };

        var docs = await ft3.getDocsByEqry(ntf, eqry, options);

        if (ntf.errorOnEqry) {
            ntf.errorMessage = `Error in query for Spiders: ${ntf.errorOnEqry.message}`;
            callback(); return;
        }

        var spiderNames = (docs || []).map(doc => doc.commonName);
        ntf.document.description = 'All Spiders: \n' + spiderNames.join(', ');
        callback();
    }
},

getFieldNamesOfPanel

Returns all the fields within a named panel defined by a sc-static-html component pair.

Syntax

var fieldNames = ft3.getFieldNames(ntf, ** panel-name )**;

This may be of use when one wants to hide a panel and clear all of its fields.

refreshSCDataTable

Reloads a sc-data-tables field on the document.

Syntax

ft3.refreshSCDataTable( field-name )