The Source Model (displayed as the name of the model) lists the existing datapoints configured within that model.
Understanding Expression Builder for Datapoints
Expression builders are used to create expression for computing values based on a set of available datapoints, fields, or constants and storing them as realtime or scheduled KPI datapoints.
Note: Expression builder is made available for Realtime datapoints by enabling the computation option.The three components of an expression builder are
- Expressions
- Variables
- Operators
Expression: An expression can contain up to two variables linked by a single mathematical operator and a total of five expressions, sequentially labelled from A to E, can be added. The final expression is constructed using the labels of these expressions.
Mathematical Operator: Plus, Minus, Multiply, and Divide are the supported mathematical operators.
Variables: Variables represent the values used within an expression.
Realtime Datapoint Variables
Realtime datapoint variables can be of the following types:
Parsing Key
Represents the value fetched from the incoming telemetry JSON using the specified parsing key. The value fetched from the JSON will be used in the computation.
Example: If the telemetry JSON includes a key named temp_k containing the temperature in Kelvin, you can reference temp_k directly in an expression as a parsing key variable and apply the appropriate conversion to derive the temperature in Celsius. The expression always uses the current value received in the JSON, so whenever a new telemetry message arrives, the updated Kelvin value is automatically used in the calculation.
Learn more in detail about Direct Parsing, {Edge Key}, findVal()
Constant
A user defined numeric value that remains the same for all computations.
Example: To convert temperature from Celsius to Kelvin, a constant value of 273.15 is added to the Celsius value in the expression. This value remains unchanged regardless of the incoming Celsius value.
Datapoint
References value stored in another available datapoint of the same source. Only datapoints/datapoint templates belonging to the same device, asset, or location instance/model are available for selection and use in the expression.
When using a datapoint in a realtime expression, you are given the following options: Actual Value and Math Function.
Actual Value: Uses the referenced datapoint value as is, without any modification.
Math Function: Applies the selected mathematical function to the datapoint value, and the resulting value is used in the computation. For example, If a datapoint has a value of
-3.6, applying the ABS math function converts it to 3.6. This converted value is then used in the expression for further calculation.Available Math Functions:
| SIN | Returns the sine of the datapoint value. |
COS | Returns the cosine of the datapoint value. |
TAN | Returns the tangent of the datapoint value. |
SQRT | Returns the square root of the datapoint value. |
ABS | Returns the absolute value of the datapoint. It removes the sign of the number, converting negative values to positive while leaving positive values unchanged. |
CEIL | Rounds the datapoint value up to the nearest integer. Example: If the datapoint value is 2.4, CEIL returns 3.If the value is -2.4, CEIL returns -2. |
FLOOR | Rounds the datapoint value down to the nearest integer. Example: If the datapoint value is 2.4, FLOOR returns 2.If the value is -2.4, FLOOR returns -3. |
ROUND | Rounds the datapoint value to the nearest integer, following standard rounding rules. Example: If the datapoint value is 2.3, ROUND returns 2.If the value is 2.6, ROUND returns 3.If the value is -2.5, ROUND returns -3 (rounded to the nearest integer). |
PREVIOUS_VALUE | Uses the previously stored value of the datapoint instead of the current incoming value. This is useful for comparisons, rate calculations, or detecting changes over time. Learn more. |
Example: Consider a scenario where you need a datapoint for power and already have datapoints for current and voltage. You can create the power datapoint by multiplying the current and voltage datapoints in an expression. As new current and voltage data are received, those values are automatically used to calculate and store the updated power value in the power datapoint.
Field
References the value from a numerical field configured in the model that accepts user input.
Example: Assume you have a Building model with a numerical field called Price Per Unit (kW). This field accepts user input and is manually entered on the Building instance's details page. You also have a realtime datapoint called Current Power (kW) that captures live power consumption from an energy meter. In the expression builder, the calculation can reference both values to determine and store the value in a new datapoint called Energy Cost.
Scheduled KPI Datapoint Variable
Scheduled KPI datapoint variables can be of the following types:
Datapoint
The datapoint variable references a value stored in another available datapoint. Unlike the datapoint variable of the realtime datapoint expression builder, in Scheduled KPI datapoints you can reference the datapoints from the current model, and also datapoints from other related models. When using a datapoint variable while creating a scheduled KPI datapoint, you are given the following options: Source Model and Related Model.
Source Model
Example: To store the hourly average temperature for a diesel generator, create a Scheduled KPI datapoint. Since the Diesel Generator model already has a Temperature datapoint, select it as the source and set the aggregation to hourly average to compute and store the required value as a new datapoint.
Related Model
Lists datapoints from models that are related to the current model.
When selecting a related model, ensure that its instances are linked to the current model through a Lookup field. Only values from instances that are associated via this Lookup relationship will be considered. If no such relationship exists, datapoint values from the related model cannot be used in the expression.
Example: Consider a scenario where you want to calculate a metric such as Hourly Fuel Efficiency. In this, the Energy Consumed datapoint is available in the Building model, while the Fuel Consumed datapoint is in the Diesel Generator model. To configure this, create the Hourly Fuel Efficiency datapoint in the Building model, select Energy Consumed as the current model datapoint, and choose the Diesel Generator model as the related model. Then reference its Fuel Consumed datapoint in the expression and apply hourly average aggregation to both values before calculating the ratio.
To establish a relationship, the instances must be linked through a Lookup field. For example, the Building 01 instance can be associated with the DG001 instance using a custom Lookup field named Connected Generator. This Lookup linkage allows the expression engine to correctly fetch the Fuel Consumed value from the associated Diesel Generator instance during calculation.
This ensures that, when calculating the Hourly Fuel Efficiency datapoint for Building 01, the Energy Consumed datapoint value from the Building 01 instance and the Fuel Consumed datapoint value from the associated DG001 instance are used together in the expression.
Aggregation function
KPI datapoints are executed at specific points in time. For a KPI datapoint to be computed, the value of the datapoint selected must be derived using an aggregation function that calculates values over a defined time period.
The following aggregation functions and time periods are available for configuration.
Aggregate Function | Output Value |
MAX | Maximum value of the datapoint value aggregated over the specified period. |
MIN | Minimum value within the datapoint value aggregated over the set period. |
SUM | Summation of all the datapoint values aggregated over the set period. |
AVG | Average of all the datapoint values aggregated over the set period. |
FIRST_VALUE | First datapoint value received within the set period. |
LAST_VALUE | Last datapoint value received within the set period. |
STDDEV_POP | Population Standard Deviation of datapoint values aggregated within the specified period. |
STDDEV_SAMP | Sample Standard Deviation of datapoint values aggregated within the specified period. |
VAR_POP | Population Variance of datapoint values aggregated within the specified period. |
VAR_SAMP | Sample Variance of datapoint values aggregated within the specified period. |
PERCENT_IN_CONTROL | Percentage of the aggregated datapoint values that fall within the defined control limits during the specified period. |
Time Period
Last 1 Hour | Last 6 Hours |
Last 12 hours | Today |
Yesterday | Last 7 Days |
Last 30 Days | Last Week |
Last Month | Last 24 Hours |
This Week | This Month |
Example: To calculate the average temperature for the last 1 hour, configure the KPI datapoint with the AVG aggregation function and select Last 1 Hour as the aggregation timeline. The system aggregates all temperature values received during the last hour and stores the computed average when the KPI is executed.
Field
References the value from a numerical field configured in the model that accepts user input. When using a field while creating a scheduled KPI datapoint, you are given two options: Current Model and Related Model.
Current Model
Lists fields configured in the same model to which the datapoint is being added. The value entered for the field in the device, asset, or location instance based on the current model is used in the computation.
Example: To calculate the average daily energy consumption per person, you can add a custom field to the Building model called “Today’s Head Count.” This field will be available under the current model datapoints. You can then use it along with the yesterday aggregated Energy Consumed datapoint to compute the per-person daily consumption while configuring the expression.
Related Model
Lists fields from models that are related to the current model.
When selecting a related model, ensure that its instances are linked to the current model through a Lookup field. Only values from instances that are associated via this Lookup relationship will be considered. If no such relationship exists, field values from the related model cannot be used in the expression.
Example: If you want to store the per-person fuel consumption, the Fuel Consumed datapoint will be in the Diesel Generator model, while the Today’s Head Count field will be in the Building model. In this case, you can create a scheduled KPI datapoint and configure it to aggregate the day’s total Fuel Consumed value from the Diesel Generator model, then divide it by the Today’s Head Count field from the related Building model.
To enable this calculation, the Diesel Generator instance must be linked to the corresponding Building instance through a Lookup field and the datapoint must be configured in the Diesel Generator model. This ensures that, the KPI execution uses the Today Head Count field value from the related Building instance to compute the per-person fuel consumption accurately. For example, the Building 01 instance can be associated with the DG001 instance using a custom Lookup field named Connected Generator. This Lookup linkage allows the expression engine to correctly fetch the Fuel Consumed value from the associated Diesel Generator instance during calculation.
This ensures that, when calculating the Hourly Fuel Efficiency datapoint for Building 01, the Energy Consumed datapoint value from the Building 01 instance and the Fuel Consumed datapoint value from the associated DG001 instance are used together in the expression.
Constant
A user-defined numeric value that remains the same for all computations.
Example: To convert temperature from Kelvin to Celsius, a constant value of 273.15 is used in the expression. This value remains unchanged regardless of the incoming Celsius temperature.
How to Build an Expression
Expression are created while creating or configuring a new datapoint.
Simple Expression
For a basic expression, fill two variable fields in a row with an operator to compute a value.
Consider a JSON payload where the distance value is measured and sent in centimetres but needs to be converted to millimetres.
{distance : 10}
You can use the expression builder for a straightforward unit conversion. Since 1 cm equals 10 mm, multiplying the incoming value by 10 converts it to millimetres accurately. Set up the expression to multiply the distance datapoint (in cm) by the constant value 10 to store the result in millimetres.
- Add a parsing key variable (direct parsing string), and input the parsing key, distance.
- Choose the multiplication operator.
- Add a constant variable of value of 10 as the second variable.
The expression will now store a computed value of 100 in the datapoint.
Complex Expression
For complex calculations where you need to perform multiple calculations on a value to be stored, you can use multiple rows and edit the expression of the row labels.
For example, consider a JSON message where the temperature value is sent in Fahrenheit, but you want to store data in Celsius.
{temp_f : 86}
Now, the formula for converting Fahrenheit to Celsius: (F - 32) * 0.55.
To achieve this computation:
In the first row:
- Add the parsing key variable with value temp_f
- Choose the Subtraction operator.
- Add a constant variable of 32.
- Click the + sign to add a second row.
In the second row:
- Add a constant variable of 0.55.
In the expression editor:
- Create the formula A*B.
Based on the expression, the resulting value stored in the datapoint will be 30.
Another example is calculating water usage in an agricultural setup. Here, the water consumed is stored in a datapoint, and the number of plants watered can change and is manually entered in a field called "Plants Watered." An expression can be created to calculate the water usage per plant as follows: