Skip to content

ft3 Extension Functions

Updated pdexter 2022-12-21

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 202212A. Some functionality may be missing in earlier versions.

Usage

Include the rulesetInclude "ft3 Extension Functions"

#include "ft3 Extension Functions",

Objects/Functions Available

Object/Function Description
getCountByEqry A function to return the count of documents matching a query.
getDialogConfirm A function to open a confirm/cancel dialog and return whether confirmed or cancelled.
getDocsByEqry A function to return an array of documents matching a query.
getFieldNamesOfPanel A function to fetch the field names within a panel definition of the template.
refreshSCDataTable A function to reload an sc-data-tables component.

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

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

Requires the #include "SweetAlert 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);

Part Description
confirmFlag Variable to receive the result (true/false)
ft3 Instance of ntf.scope
ntf The ntf object.
dialogOptions An object structure containing the parameters for the SweetAlert dialog.
The option "showCancelButton" defaults to true, unless explicitly set false
dialogText A string containing the text to display in the confirm dialog, if a full dialogOptions argument is not used.

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]);

Part Description
documents Return of an array of document objects from the query.
ft3 Instance of ntf.scope
ntf The ntf object
eqry An elasticsearch query to submit.
options Optional argument, usually omitted
Any options required for the query
See findDocumentsByElastic for full detail.

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 )