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 )