Skip to main content

Meta Data Source

The Meta Data Source enables data analysis to behave like another sensor in Mango. It creates virtual data points that derive their values from existing data points using JavaScript scripts. This allows you to perform calculations, transformations, aggregations, and complex logic across multiple data sources without additional hardware.

To use this data source, some knowledge of JavaScript is required. While there are differences from browser-based JavaScript (the document and window objects are not available), a full implementation of ECMAScript is available within the scripting environment.

Creating a Meta Data Source​

Navigate to the Data Sources page and create a new data source of type Meta. The Meta Data Source itself has minimal configuration -- the primary configuration happens at the data point level. Save the data source and enable it to begin adding meta data points.

Meta Data Points​

Meta points are configured by creating a "context" of existing data points, which become available for access within the script when it executes. These context points can be any point saved in Mango, including the current meta point being edited (for recursive calculations). Note that the current point must be saved before it appears in the context point list.

Point Configuration​

Data type determines the type of value expected to be returned from the script. The point attempts to convert the returned value to this type. Available data types include:

Data TypeDescriptionScript Return
BinaryTrue/false valuesBoolean (true/false)
MultistateInteger state valuesInteger
NumericFloating-point numbersNumber
AlphanumericText stringsString

Settable determines whether the point can be manually set by users. When a meta point is settable, users can write values to it through the UI or REST API.

Script Context​

The script context defines the data points available to the script when it executes. Each context point must be assigned a Var (variable name) that the script uses to reference the point data. These variable names must be valid ECMAScript identifiers:

  • Must start with a letter or underscore
  • May not contain spaces
  • Must be unique within the context

To add a point to the context, select it from the list and click the add icon. To remove a point, click the delete icon next to it.

Performance note: Only add points that the script actually needs. Each context point incurs overhead for data preparation. However, including extra context points can be useful to trigger script execution (see Script Execution below).

Script Execution Triggers​

Meta data point scripts can be triggered to execute in several ways:

  • Context update: The script runs whenever any context point receives a new value. This is the most common mode for real-time calculations.
  • Context change: The script runs only when a context point's value changes (not just when it is updated with the same value).
  • Cron pattern: The script runs on a cron schedule, independent of context point updates.

The choice of trigger affects how responsive the meta point is to changes in its source data and how much processing overhead it creates.

Writing Scripts​

Scripts execute in a JavaScript environment with access to all context points. Each context variable provides methods for accessing the current value and historical data.

Accessing Current Values​

// 'temp' is a context variable name
var currentTemp = temp.value;       // The current value
var timestamp = temp.time;          // The timestamp of the current value

Accessing Historical Values​

// Get the last N values
var lastTen = temp.last(10);

// Iterate over historical values
for (var i = 0; i < lastTen.length; i++) {
    var pv = lastTen[i];
    // pv.value - the value
    // pv.time  - the timestamp
}

Setting a Custom Timestamp​

Meta data points allow you to set a custom timestamp for the calculated value by setting a variable named TIMESTAMP. The timestamp value is in milliseconds since the Java epoch (January 1, 1970 UTC):

// Use the timestamp of the source point instead of the current time
TIMESTAMP = temp.time;
return temp.value * 1.8 + 32;  // Convert Celsius to Fahrenheit

Example Scripts​

Average of multiple points:

var avg = (sensor1.value + sensor2.value + sensor3.value) / 3;
return avg;

Running total with conditional logic:

if (flowMeter.value > 0 && valveStatus.value) {
    return flowMeter.value * 60;  // Convert L/min to L/hour
}
return 0;

Rate of change calculation:

var values = temp.last(2);
if (values.length >= 2) {
    var valueDiff = values[0].value - values[1].value;
    var timeDiff = (values[0].time - values[1].time) / 1000; // seconds
    if (timeDiff > 0) {
        return valueDiff / timeDiff; // degrees per second
    }
}
return 0;

String concatenation for alphanumeric points:

return device.value + " - Status: " + (status.value ? "Online" : "Offline");

Generate History​

When creating a new Meta Point, it is often useful to backfill historical values. The Generate History feature does this automatically:

  1. The system finds the most recent saved value across all context points and uses that date as the starting date for the simulation. If any context point has no saved values, the generation fails.
  2. The system finds the oldest saved value for the meta point and uses that as the ending date. If no values exist for the meta point, the current time is used.
  3. The simulation runs from the starting date to the ending date, creating and saving values according to the meta point's script and settings.

This means history can only be generated for time periods before the earliest existing meta point value.

To generate history, click the Generate History link in the Data Points table for the meta point.

About Mango JavaScript​

The Mango scripting environment extends standard ECMAScript with additional utilities for interacting with data points, the runtime manager, and other Mango services. For detailed information on the scripting API, including available utility objects and functions, see the Mango JavaScript documentation.

Key differences from browser JavaScript:

  • No document, window, or DOM objects
  • No browser-specific APIs (fetch, XMLHttpRequest, etc.)
  • Additional Mango-specific objects for data point access and system interaction
  • Script execution is sandboxed with configurable permissions

Best Practices​

  • Minimize context points: Only include points the script actually references to reduce overhead.
  • Handle missing data: Use null checks before accessing point values. A context point might not have a current value if the data source is offline.
  • Use descriptive variable names: Choose context Var names that clearly indicate the source point (e.g., tankLevel rather than p1).
  • Test with Generate History: Verify your script logic by generating historical values and reviewing the results.
  • Monitor execution time: Complex scripts that run on every context update can consume significant CPU. Consider using a cron-based trigger for expensive calculations.
  • Document your scripts: Use JavaScript comments to explain the business logic, units of measurement, and any assumptions.