JavaScript API

Timeseries functions JS API guide

This guide describes how to write Custom Timeseries Functions and the contents of the JS API.

The API contains both the implementation of some predefined timeseries functions and some useful functions that can be used when writing Custom Aggregation Functions.

Writing Custom Aggregation Function

Input parameters

All functions will have three implicit input parameters that must be used for value calculation.

receivedValues: Array of Json of collected values. Each value will have two fields:
- value: collected value. value type depends on Column’s datastream type (please note that any datetime value will be formatted as an ISO string).
- at: datetime of collected value. This value will be defined in ISO string.
currentValue: Columns current aggregated value. The type depends on aggregation function behavior.
extra: Json with useful data for aggregated value updating. In some cases, when aggregated value must be updated, some previous auxiliary data must be used to calculate new values. The fields and their format will be defined taking into account the requirements of the function. For example, if an average data must be updated, previously received number of elements and their sum are necessary to calculate correctly new average value.

receivedValues example:

"receivedValues":[
    {
        "value": 3,
        "at": "2023-03-01T00:30:00.000Z"
    },{
        "value": 5,
        "at": "2023-03-01T01:30:00.000Z"
    },{
        "value": 6,
        "at": "2023-03-01T02:30:00.000Z"
    },{
        "value": 8,
        "at": "2023-03-01T02:30:00.000Z"
    }
];

currentValue example:

"currentValue": 4;

extra example:

"extra": {
  "sum": 8,
  "count": 2  
};

Timeserie function result

Defined function must return a result with specific format. It will be a json with two parameters:

value: New calculated value.
extra: A JSON with auxiliary data updated. The content of this JSON will be the same of the extra input parameter.

Result example:

return {
    "executionResult": "OK",
    "value": 5,
    "extra": {
      "sum": 30,
      "count": 5  
    }
};

There is an auxiliary function that takes value and extra fields as parameters and returns the json with correct format. For further description of this function check documentation.

Result example using auxiliary function:

return result.ok(5, {"sum":30}, {"count":6});

If some timeserie function execution throws an exception it will be internally caught. In this case result object will be like this:

return {
    "executionResult": "Some javascript execution error message"
}

This behavior can be forced using result.error function with an Error object or an string message. For example:

return result.error(new Error("Custom error message"));
// or
return result.error("Custom error message");

Function implementation example

Taking described Input parameters and the Result to be returned into account, AVG Aggregation Function implementation example is shown here:

var newCount = receivedValues.length;
var newSum = 0;
for(var recVal in receivedValues){
    newSum = newSum + receivedValues[recVal].value;
}
if (extra) {
    if(data.exists(extra.count)) newCount = newCount + extra.count;
    if(data.exists(extra.sum)) newSum = newSum + extra.sum;
}
var newValue = newSum / newCount;
return result.ok(newValue, {"sum":newSum}, {"count":newCount});

JS API

data.exists(value)

Aux method to check if some value has value. If value is undefined or null it will return false.

Kind: global function
Returns: Boolean - Json with result.

Param	Type	Description
value	any	value to be checked.

Example of use:

if(data.exists(receivedValues[recVal].value)){
    newSum = newSum + receivedValues[recVal].value;
}

data.undefined2null(value)

Aux method to replace all undefined fields with null values. Internally used to avoid issues when processing execution result.

Kind: global function
Returns: Any - Json with result.

Param	Type	Description
value	any	value to be checked and transformed.

Example of use:

var newValue = data.undefined2null(undefined);

console.log(newValue) // null