Skip to main content

Meta Data Source

The Meta data source creates derived data points by combining and transforming the values of existing points in Mango using JavaScript (ECMAScript) scripts. Rather than collecting data from an external system, each Meta data point defines a script context containing references to other points, and a script that computes a new value whenever its context changes or on a scheduled basis. This makes the Meta data source the primary tool for calculated fields, unit conversions, aggregations, and cross-point logic.

The scripting engine uses the Rhino JavaScript implementation, providing a full ECMAScript environment. While there is no browser DOM (no window or document objects), all standard JavaScript language features -- variables, functions, loops, conditionals, math operations -- are available.

Overview​

PropertyValue
ModuleCore (built-in)
ProtocolN/A (scripted)
DirectionDerived
Typical UseCalculating derived values from other data points using JavaScript

Prerequisites​

  • At least one existing data point in Mango to serve as input to the script. The context points can belong to any data source.
  • Basic knowledge of JavaScript for writing the transformation scripts. Complex transformations may require familiarity with Mango's scripting API (available in the Mango JavaScript help documentation).

Configuration​

Data Source Settings​

The Meta data source configuration is minimal at the data source level. The primary configuration is done on each individual data point.

SettingDescription
NameA descriptive name for the data source.
Update eventDetermines when meta points execute their scripts. Options typically include context update (when any context point changes), cron pattern (on a schedule), or context change (when context values actually differ from the previous poll).

Data Point Configuration​

Each Meta data point has its own script context and script.

SettingDescription
Data typeThe Mango data type expected as the script's return value (Binary, Multistate, Numeric, or Alphanumeric). The script output is coerced to this type.
SettableWhether the point can be manually set.
Variable nameThe name given to this point, which is always available in its own script context.

Script Context​

The script context defines which existing data points are available to the script at execution time. Each context point requires:

SettingDescription
PointThe source data point to include in the context.
VarThe variable name assigned to the point's data in the script. Must be a valid ECMAScript identifier (starts with a letter or underscore, no spaces).
Updates contextWhen checked, a value change on this point triggers the meta point to recalculate. Only used when the update event is "context update."
tip

Only add points to the context that the script actually uses. Each context point adds overhead for data preparation, and unnecessary context variables may trigger unintended script executions when using the context update event.

The current point being edited can also appear in its own context list (after it has been saved). This enables self-referencing calculations where the point's previous value influences its next value.

Scripts​

Scripts are written in JavaScript and have access to all context point variables. Each context variable provides properties such as .value (the current value) and .time (the timestamp of the current value).

Example -- Temperature conversion:

// Convert Fahrenheit to Celsius
// Context: tempF (a numeric point in Fahrenheit)
return (tempF.value - 32) * 5 / 9;

Example -- Average of multiple sensors:

// Context: sensor1, sensor2, sensor3 (numeric points)
return (sensor1.value + sensor2.value + sensor3.value) / 3;

Example -- Status logic:

// Context: temp (numeric), pressure (numeric)
// Returns a multistate value
if (temp.value > 100 || pressure.value > 50) {
    return 2; // Alarm
} else if (temp.value > 80 || pressure.value > 40) {
    return 1; // Warning
} else {
    return 0; // Normal
}

Custom Timestamps​

You can override the timestamp assigned to the meta point's value by setting a variable named TIMESTAMP in the script. The timestamp must be in milliseconds since the Java epoch (January 1, 1970 UTC).

// Use the timestamp from the source point instead of the execution time
TIMESTAMP = tempF.time;
return (tempF.value - 32) * 5 / 9;

Preventing Updates​

If the script returns the special object UNCHANGED, the meta point does not update its value for that execution cycle. This is useful for conditional calculations where you only want to record a new value when certain criteria are met.

// Only update if the value has changed significantly
var newValue = (sensor1.value + sensor2.value) / 2;
if (Math.abs(newValue - my.value) < 0.5) {
    return UNCHANGED;
}
return newValue;

Generate History​

When creating a new Meta point, you can backfill historical values using the Generate History feature available in the Data Points table. The process works as follows:

  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, generation fails.
  2. The system finds the oldest saved value for the Meta point and uses that as the ending date. If the Meta point has no existing values, the current time is used.
  3. The simulation runs from start to end, creating and saving values according to the Meta point's configuration.
important

History can only be generated for times before the earliest existing Meta point value. The set() function in the simulation context saves values regardless of logging type and does not send them through the data source output pipeline.

Common Patterns​

Unit Conversions​

Create Meta points to convert between measurement units (Fahrenheit to Celsius, PSI to bar, gallons per minute to liters per second). This keeps the raw data in its original units while providing converted values for display and reporting.

Rolling Averages and Aggregations​

Use Meta points with scheduled execution (cron-based update events) to compute rolling averages, minimums, maximums, or sums across multiple input points. This is useful for smoothing noisy sensor data or creating summary metrics.

Equipment Status Derivation​

Combine multiple binary and numeric inputs to derive a composite equipment status. For example, a pump might be considered "running normally" only when the motor is on, the flow rate is above a threshold, and no fault codes are active.

Calculated Energy Metrics​

Compute power factor, energy consumption rates, or efficiency ratios from raw electrical measurements. Meta points excel at this because they can reference points from different data sources and apply the calculation whenever any input changes.

Conditional Alarms​

Use Meta points to create conditions that are more complex than what a single event detector can express. For example, raise an alarm only when temperature exceeds a threshold AND the cooling system has been running for more than 10 minutes.

Troubleshooting​

Script Execution Errors​

  1. Variable not defined -- verify that all referenced variables match the Var names in the script context, including capitalization.
  2. Type conversion error -- the script return value must be compatible with the configured Data type. Returning a string when the point expects a number will cause an error.
  3. Context point not available -- if a context point is disabled or deleted, the script will fail with a missing variable error.

Unexpected Execution Timing​

  1. Too frequent -- if using context update, every change to any context point (with Updates context checked) triggers the script. Remove unnecessary context points or uncheck Updates context for points that should not trigger recalculation.
  2. Too infrequent -- verify that at least one context point has Updates context checked, or switch to a cron-based update event.

Missing or Wrong Values​

  1. UNCHANGED returned unintentionally -- check the script logic for paths that return UNCHANGED when a value should be produced.
  2. Stale context values -- context point values reflect the most recent value at the time of script execution. If context points update asynchronously, the script may see values from different moments in time.

History Generation Fails​

  1. Ensure all context points have at least one saved historical value. If any context point has no history, the generation start date cannot be determined.
  2. History generation only fills times before the Meta point's earliest existing value. If the point already has values spanning the desired range, no new history will be generated.