Skip to content

ft3 Extension Functions

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.

For example, with our usual way of getting the array of documents from an ElasticSearch result:

if (result && result.data && result.data.hits .... ) {
    var docs = result.data.hits.hits.map(function(hit){ return hit._source; });
    ...
}

we can instead write:

var esResult = ft3.esResult(result);
if (esResult.isValid()) {
    var docs =  esResult.toDocArray();
}

Usage

Include the rulesetInclude "ft3 Extension Functions"

#include "ft3 Extension Functions",

Objects Available

Object/Function Description
esResult A handler for the ElasticSearch result object returned by ft3.findDocumentsByElastic.
selectedAssetHandler A handler for interrogating a sc-selected-asset field.
getApplicationConfiguration A function to retrieve a specific application configuration document and return its configuration as a JSON object.

esResult

esResult is designed to handle the result object returned by findDocumentsByElastic, and allow the developer to write more readable code.

Syntax

var esResultObject = ft3.esResult(elasticSearchResult);

Part Description
esResultObject handler object used to interrogate result
elasticSearchResult JSON object returned by findDocumentsByElastic

Once this object is created, it can be used to get information from the result using functions of the object:

Function Description Old Method
isValid Returns true if the result is a valid ElasticSearch result; false if not. if (result && result.data && result.data.hits && result.data.hits.hits) ...
toDocArray Returns a document array from the result result.data.hits.hits.map(function(hit){return hit._source});
isComplete Returns whether the result contains all matches to the query, or whether only a limited count of matches. if (result.data.hits.total > result.data.hits.hits.length) ...
fullCount Returns the total of matches from the query, which may be more than the result contains. result.data.hits.total
count Returns the number of matches to the query contained in the results, which may be less than the full potential count. result.data.hits.hits.length
firstDocument Returns the first document of the query results. result.data.hits.hits[0]._source

Example

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

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

        ft3.findDocumentsByElastic(eqry, ntf.userId, function(err, result) {
            var esResult = ft3.esResult(result);
            if (err) {
                ntf.errorMessage = 'Error on query: ' + err.message;
            }
            else if (esResult.isValid()) {
                var docs = esResult.toDocArray();

                var spiderNames = docs.map(function(doc){
                    return doc.commonName;
                });
                ntf.document.description = 'All Spiders: \n' + spiderNames.join(', ');

                if (!esResult.isComplete()) {
                    ntf.document.description += ', (incomplete list)';
                }

                ntf.document.description += '\n\n# Total Spiders: ' + esResult.fullCount();

                ntf.document.description += '\n# fetched by query: ' + esResult.count();

                ntf.document.description += '\n\n# First Spider found: ' + esResult.firstDocument().commonName;
            }
            else {
                alert('esResult not valid');
            }

            callback();
        });
    }
},

selectedAssetHandler

The selectedAssetHandler is designed to handle the sc-selected-asset component field.

Syntax

object = ft3.selectedAssetHandler(ntf, field);

Part Description
object Handler object used to interrogate the sc-selected-asset.
field The field or field name to interrogate.

Once this object is created, it can be used to get information from the field using functions of the object:

Function Description Old Method
isValid Returns true if the field is a valid sc-selected-asset object; false if not. var isValidField = (fieldOB && fieldOB.type === 'FeatureCollection' && fieldOb.features) ? true : false;
getMainFeature Returns the feature from the FeatureCollection whose .properties.type is "street", usually the first feature. var object1 = locationGeo.features[0]
(requiring prevalidating code)
getPrimaryAssetFeature Returns the primary asset feature object of the field. looping through each feature, checking its properties.type value
getSecondaryAssetFeature Returns the secondary asset feature object of the field. looping through each feature, checking its properties.type value

Example

// no example yet

getApplicationConfiguration

This is a single function used to fetch a JSON object representing a particular application configuration document.

Application Configuration documents are based on a particular template, with systemType "applicationConfiguration".

Please note, this is an asynchronous function, and requires callback handling.

Detail on the Application Configuration document is coming in another document.

Syntax

ft3.getApplicationConfiguration(ntf, nameKey, function(configurationObject) {     // process/store configuration object     ... });

Part Description
nameKey Name matching the "Name/Key" (.name) of the target application configuration document
configurationObject The returned configuration JSON object.

Example

Sample Application Configuration:

Name/Key : "dexwise.test"

Configuration:

{
    "spiderColorDefault" : "Indigo",
    "spiderWeightDefaultMG" : 11
}
Sample ruleset usage:
    var ft3 = ntf.scope; 

    ft3.getApplicationConfiguration(ntf, 'dexwise.test', function(configOB) {
        if (configOB) {
            ntf.appConfig = configOB;

            ntf.document.description =
                'Spider Colour Default: ' + ntf.appConfig.spiderColorDefault 
                + '\nSpider Weight Default (mg): ' 
                + ntf.appConfig.spiderWeightDefaultMG;
        }
    });