math function

Performs mathematical operations and functions on numeric data. Arguments can be retrieved from multiple sources (constants, message data, message metadata, attributes, or time series data) and results can be saved to the message or directly to database as attributes or time series.

Configuration

Supported functions

Using CUSTOM function

When you select the CUSTOM operation, you can write your own mathematical expression instead of using predefined operations. This allows you to perform complex calculations that combine multiple operations in a single node.

Key points:

• You can use up to 16 arguments with predefined names (displayed on the configuration form)
• Use these predefined argument names directly in your expression
• The expression is evaluated using the exp4j library - refer to its documentation for detailed syntax rules
• Supports standard mathematical operators: +, -, *, /, ^ (power), and parentheses
• Supports standard functions (sin(), cos(), sqrt(), abs(), etc.) plus custom functions: ln(x) (natural logarithm), lg(x) (base 10 logarithm), logab(a, b) (logarithm of b with base a)
• Available built-in constants: π or pi (3.14159265358979323846), e (2.7182818284590452354), φ (1.61803398874)

Expression examples:

Arguments

Arguments for mathematical operations can be retrieved from the following sources:

• Constant - A fixed numerical value specified directly in the configuration
• Message - Reads a value from a field in the JSON message payload
• Metadata - Reads a value from the message metadata
• Attribute - Fetch the attribute value from the database for the message originator
• Time series - Retrieve the latest time series value from the database for the message originator

Each argument can have a default value that will be used if the source value is missing.

Note: When specifying keys to fetch or extract values, you can use templatization (e.g., ${metadataKey} or $[dataKey]) to dynamically construct key names based on message content.

Note: All argument values must be numeric or strings that can be parsed as numbers. The node will fail if a value is an array, object, or non-numeric string, unless a default value is specified.

Result

The calculation result can be saved to one or more destinations:

• Message - Save the result to a specified key in the message data
• Metadata - Save the result to a specified key in the metadata
• Attribute - Save as an originator attribute (with configurable scope: Server or Shared)
• Time series - Save as a time series data point with the current timestamp

When saving to attributes or time series, you can optionally also add the result to the message data and/or metadata for use in subsequent rule nodes.

You can specify the number of digits after the decimal point for the result. The value will be rounded to the specified precision using half-up rounding mode (rounds towards the nearest neighbor, and if both neighbors are equidistant, rounds up).

Note: Processing for a given originator is performed sequentially within the scope of a server node, preventing race conditions when reading from and writing to the database.

Performance tip: This node is optimized for mathematical calculations and provides better performance than script nodes, as it eliminates the overhead of script compilation and execution. Use this node whenever possible for numeric operations.

JSON Schema

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "TbMathNodeConfiguration",
  "type": "object",
  "properties": {
    "operation": {
      "type": "string",
      "enum": [
        "ADD",
        "SUB",
        "MULT",
        "DIV",
        "SIN",
        "SINH",
        "COS",
        "COSH",
        "TAN",
        "TANH",
        "ACOS",
        "ASIN",
        "ATAN",
        "ATAN2",
        "EXP",
        "EXPM1",
        "SQRT",
        "CBRT",
        "GET_EXP",
        "HYPOT",
        "LOG",
        "LOG10",
        "LOG1P",
        "CEIL",
        "FLOOR",
        "FLOOR_DIV",
        "FLOOR_MOD",
        "ABS",
        "MIN",
        "MAX",
        "POW",
        "SIGNUM",
        "RAD",
        "DEG",
        "CUSTOM"
      ],
      "description": "The mathematical operation to perform."
    },
    "customFunction": {
      "type": "string",
      "description": "Custom mathematical expression (required when operation is CUSTOM)."
    },
    "arguments": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Predefined variable name for the argument (displayed in configuration form)."
          },
          "type": {
            "type": "string",
            "enum": [
              "CONSTANT",
              "MESSAGE_BODY",
              "MESSAGE_METADATA",
              "ATTRIBUTE",
              "TIME_SERIES"
            ],
            "description": "Source type for the argument value."
          },
          "key": {
            "type": "string",
            "description": "Key name to retrieve the value from (supports template patterns)."
          },
          "attributeScope": {
            "type": "string",
            "description": "Attribute scope (required only for ATTRIBUTE type)."
          },
          "defaultValue": {
            "type": "number",
            "description": "Default value if the source is missing or invalid."
          }
        },
        "required": [
          "name",
          "type",
          "key"
        ]
      },
      "description": "List of input arguments for the mathematical operation."
    },
    "result": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "MESSAGE_BODY",
            "MESSAGE_METADATA",
            "ATTRIBUTE",
            "TIME_SERIES"
          ],
          "description": "Destination type for the calculation result."
        },
        "key": {
          "type": "string",
          "description": "Key name for storing the result (supports template patterns)."
        },
        "attributeScope": {
          "type": "string",
          "description": "Attribute scope (required only for ATTRIBUTE type)."
        },
        "resultValuePrecision": {
          "type": "integer",
          "description": "Number of decimal places for rounding (0 for integer)."
        },
        "addToBody": {
          "type": "boolean",
          "description": "Also add the result to message data (for ATTRIBUTE/TIME_SERIES types)."
        },
        "addToMetadata": {
          "type": "boolean",
          "description": "Also add the result to message metadata (for ATTRIBUTE/TIME_SERIES types)."
        }
      },
      "required": [
        "type",
        "key"
      ]
    }
  },
  "required": [
    "operation",
    "arguments",
    "result"
  ],
  "additionalProperties": false
}

Message processing algorithm

1. For each argument, the node retrieves the value from the configured source (constant, message data, metadata, attribute, or time series). If a value cannot be retrieved and no default value is specified, processing fails.
2. All argument values are converted to numeric (double) format. If conversion fails, processing fails.
3. The node performs the mathematical calculation using the retrieved argument values according to the selected operation.
4. The result is formatted according to the configured precision (rounded to the specified number of decimal places).
5. The result is saved to the configured destination(s): message, metadata, attribute, and/or time series.
6. When processing completes successfully, the message is forwarded via the Success connection.

Output connections

• Success
  • The mathematical operation completed successfully and the result was saved.
• Failure
  • An error occurred during processing, such as:
    • Missing required argument without a default value
    • Failed to convert an argument value to a number
    • Division by zero
    • Invalid mathematical operation (e.g., square root of negative number for real numbers)
    • Other unexpected error

Examples

Example 1 — Accumulating water consumption

A water meter device reports incremental consumption. You need to update the total consumption stored as an attribute.

Incoming message

Data:

1
2
3
{
  "deltaConsumption": 15.7
}

State of the system

Originator has a server attribute: totalConsumption = 12543.8

Node configuration

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
  "operation": "ADD",
  "arguments": [
    {
      "name": "x",
      "type": "ATTRIBUTE",
      "key": "totalConsumption",
      "attributeScope": "SERVER_SCOPE",
      "defaultValue": 0
    },
    {
      "name": "y",
      "type": "MESSAGE_BODY",
      "key": "deltaConsumption"
    }
  ],
  "result": {
    "type": "ATTRIBUTE",
    "key": "totalConsumption",
    "attributeScope": "SERVER_SCOPE",
    "resultValuePrecision": 2,
    "addToBody": true,
    "addToMetadata": false
  }
}

Outgoing message

Data:

1
2
3
4
{
  "deltaConsumption": 15.7,
  "totalConsumption": 12559.5
}

Routed via the Success connection.

Result

The originator attribute totalConsumption is updated from 12543.8 to 12559.5 (12543.8 + 15.7). The new total is also added to the message data for use in subsequent rule nodes.

Example 2 — Complex signal processing calculation

Calculate a signal quality indicator using a custom formula that combines distance, signal strength, and environmental factors. The formula uses trigonometric functions, logarithms, and built-in constants.

Formula: quality = 100 * e^(-distance / 1000) * (1 + 0.5 * sin(2 * pi * frequency/1000)) * sqrt(abs(signalStrength))

Incoming message

Originator: DEVICE

Data:

1
2
3
4
5
{
  "distance": 250,
  "frequency": 2400,
  "signalStrength": -45
}

Node configuration

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
  "operation": "CUSTOM",
  "customFunction": "100 * e^(-x / 1000) * (1 + 0.5 * sin(2 * pi * y / 1000)) * sqrt(abs(z))",
  "arguments": [
    {
      "name": "x",
      "type": "MESSAGE_BODY",
      "key": "distance"
    },
    {
      "name": "y",
      "type": "MESSAGE_BODY",
      "key": "frequency"
    },
    {
      "name": "z",
      "type": "MESSAGE_BODY",
      "key": "signalStrength"
    }
  ],
  "result": {
    "type": "MESSAGE_BODY",
    "key": "signalQuality",
    "resultValuePrecision": 2,
    "addToBody": true,
    "addToMetadata": false
  }
}

Outgoing message

Data:

1
2
3
4
5
6
{
  "distance": 250,
  "frequency": 2400,
  "signalStrength": -45,
  "signalQuality": 675.98
}

Routed via the Success connection.

Result

The signal quality indicator is calculated using exponential decay for distance, sinusoidal modulation for frequency effects, and square root transformation of signal strength. The formula demonstrates the use of:

• The built-in constant e (Euler’s number) for exponential calculations
• The built-in constant pi for trigonometric calculations
• Functions: sin(), sqrt(), abs()
• Complex expression with multiple operations

The result (675.98) is saved to the message data for further processing.