Skip to main content

About Mango JavaScript

Mango uses ECMAScript (JavaScript) as its scripting language for meta data points, scripting data sources, event handlers, and other automation features. While this is the same language used in web browsers, the execution context within Mango is different -- there are no window, document, or DOM objects. Instead, the context provides access to data point values, system utilities, and Mango-specific APIs.

Most script editors in the Mango UI have an adjacent blue question mark icon that opens contextual help. The "About Mango JavaScript" section within that help contains version-specific information about available features.

Script Basics​

The Script area is where you enter the code to execute. Scripts can be any valid ECMAScript that would be written within a function body. The script should use return to produce a result value (for meta data points) or call point.set() to set values (for scripting data sources).

In addition to the standard ECMAScript built-ins, globally accessible functions can be defined through modules such as SST Global Scripts. These include convenience functions like max(), min(), avg(), and sum(). To use them, call them directly:

return max(x.value, y.value, z.value);

This returns the maximum of the present values of x, y, and z. Any number of parameters can be provided to these global functions.

After entering a script, click the check mark (validate) icon to execute it in test mode and view the calculated result without saving any values.

Point Value Time Objects​

Mango stores data as Point Value Time (PVT) objects. Each PVT contains a value and a timestamp. When accessing data point values from within a script, it is important to know whether you are working with a raw value or a full PVT object.

A Point Value Time object has the following structure:

{
    value: /* the point's value (number, boolean, string, etc.) */,
    time: /* timestamp in milliseconds since the Unix epoch */
}

Accessing the Current Value​

Each context variable provides direct access to its current value and timestamp:

  • p.value -- The current value of the point.
  • p.time -- The timestamp of the current value in milliseconds since epoch.

Timestamp Components​

The timestamp of a value is also available broken down into individual components. These are useful for time-based calculations, scheduling logic, or conditional behavior based on time of day:

FieldRangeDescription
p.millis0-999Millisecond portion of the timestamp
p.second0-60Second of the minute
p.minute0-60Minute of the hour
p.hour0-23Hour of the day (24-hour format)
p.day1-28/31Day of the month
p.dayOfWeek1-7Day of the week (1 = Sunday)
p.dayOfYear1-365/366Day of the year
p.month1-12Month of the year
p.yearfour digitsFull year

Example: Time-Based Logic​

// Only return a value during business hours (8 AM to 5 PM on weekdays)
if (p.hour >= 8 && p.hour < 17 && p.dayOfWeek >= 2 && p.dayOfWeek <= 6) {
    return sensor.value * calibrationFactor.value;
}
return UNCHANGED;

Historical Data Access​

Context point variables provide methods for accessing historical values:

p.last(count)​

Returns a list of the most recent count values for the point. The list contains Point Value Time objects ordered from most recent to oldest. This is commonly used for moving average calculations, trend detection, and smoothing algorithms.

var values = sensor.last(10);
var sum = 0;
for (var i = 0; i < values.size(); i++) {
    sum += values.get(i).value;
}
return sum / values.size();

p.lastValue(index)​

Returns a specific historical value by index. Index 0 is the most recent value, index 1 is the second most recent, and so on. Returns null if the requested index does not exist.

var current = sensor.value;
var previous = sensor.lastValue(1);
if (previous != null) {
    return current - previous.value;
}
return 0;

p.ago(periodType, count)​

Returns the value of the point from a specified time period ago. The periodType is a string such as MINUTES, HOURS, DAYS, WEEKS, or MONTHS, and count is the number of those periods.

// Get the value from 1 hour ago
var oneHourAgo = sensor.ago(HOURS, 1);
return sensor.value - oneHourAgo.value;

Special Variables and Objects​

TIMESTAMP​

Set this variable to a millisecond epoch value to override the timestamp of the meta data point's value. By default, the meta point uses the timestamp of the triggering context update.

// Use the timestamp from the source sensor, not the current time
TIMESTAMP = sensor.time;
return sensor.value * 1.8 + 32;

UNCHANGED​

Return this object to prevent the meta data point from updating its value. The point retains its previous value and no new entry is logged.

if (sensor.value < 0) {
    return UNCHANGED;  // Ignore negative readings
}
return sensor.value;

RuntimeManager​

Provides access to the Mango runtime for advanced operations such as enabling/disabling data sources and sending commands. Use with caution as improper use can affect system stability.

DataPointQuery​

Allows querying data points from within a script using RQL. Returns a list of data point objects that match the query.

var points = DataPointQuery.query("deviceName=Boiler1");
for (var i = 0; i < points.size(); i++) {
    LOG.info("Found point: " + points.get(i).getName());
}

JsonEmport​

Provides access to Mango's JSON import/export functionality from within scripts. This allows scripts to read and modify system configuration programmatically.

var config = JSON.parse(JsonEmport.getConfiguration("dataPoints"));
// Modify configuration...
JsonEmport.doImport(JSON.stringify(config));

Data Type Coercion​

The value returned by a meta data point script is coerced to the configured data type of the point:

Target TypeAccepted Script Return Values
NumericNumbers, numeric strings
BinaryBooleans, 0/1, "true"/"false"
MultistateIntegers corresponding to configured states
AlphanumericAny value (converted via toString())

If coercion fails, a script error event is raised on the data point.