Admin formulas

For examples that show how formulas are used in application features, including the variables available in each context, see Formula use cases

Formula Operands

The Formula class evaluates a formula definition as a tree of operands. Every operand is an object with a type field. Operation and function operands also include an operator field and an operands array containing child operands.

Operand Shape

TS

type Operand =
  | Constant
  | Variable
  | ArithmeticOperation
  | ComparisonOperation
  | LogicalOperation
  | ConditionalFunction
  | StringFunction
  | AggregateFunction
  | ArrayFunction
  | StatisticalFunction
  | null;

null is part of the shared TypeScript type, but the Formula class throws Operand is null when it encounters one.

Constant

Constants return their configured value.

Type	Operator	Inputs	Result
`constant`	N/A	`value: number \| string \| boolean \| Operand[]`	Returns `value`. If `value` is an array, each item is evaluated as an operand and the result is an array of evaluated values.

JSON Example:

JSON

{ "type": "constant", "value": 42 }

Variable

Variables read values fetched during prepare() or passed to run({ variables }).

Type	Operator	Inputs	Result
`variable`	N/A	`path: string[]`, optional `params: Record<string, unknown>`, optional `customVariableId: string`	Reads the root variable named by `path[0]`. If `path` has more entries, each later entry is used as a property accessor on the fetched root value.

Input notes:

path[0] identifies the variable fetcher or runtime variable value.
params are passed to the variable fetcher and are part of the variable cache key.
Paths with more than one segment require the root variable value to be an object.
Array callback variables are injected internally with names beginning with $, such as $arrayItem and $accumulator.

JSON Example:

JSON

{ "type": "variable", "path": ["entity", "custom_data", "temperature"] }

Arithmetic

Arithmetic operations evaluate two numeric child operands.

Type	Operator	Inputs	Result
`arithmeticOperation`	`+`	`operands: [left, right]`; both values must be numbers	`left + right`
`arithmeticOperation`	`-`	`operands: [left, right]`; both values must be numbers	`left - right`
`arithmeticOperation`	`*`	`operands: [left, right]`; both values must be numbers	`left * right`
`arithmeticOperation`	`/`	`operands: [left, right]`; both values must be numbers	`left / right`
`arithmeticOperation`	`%`	`operands: [left, right]`; both values must be numbers	`left % right`

JSON Example:

JSON

{
  "type": "arithmeticOperation",
  "operator": "+",
  "operands": [
    { "type": "variable", "path": ["entity", "custom_data", "temperature"] },
    { "type": "constant", "value": 5 }
  ]
}

Comparison

Comparison operations evaluate two child operands and return a boolean.

Type	Operator	Inputs	Result
`comparisonOperation`	`==`	`operands: [left, right]`	`true` when `left === right`
`comparisonOperation`	`!=`	`operands: [left, right]`	`true` when `left !== right`
`comparisonOperation`	`>`	`operands: [left, right]`; both values must be numbers	`true` when `left > right`
`comparisonOperation`	`<`	`operands: [left, right]`; both values must be numbers	`true` when `left < right`
`comparisonOperation`	`>=`	`operands: [left, right]`; both values must be numbers	`true` when `left >= right`
`comparisonOperation`	`<=`	`operands: [left, right]`; both values must be numbers	`true` when `left <= right`

JSON Example:

JSON

{
  "type": "comparisonOperation",
  "operator": ">=",
  "operands": [
    { "type": "variable", "path": ["entity", "custom_data", "temperature"] },
    { "type": "constant", "value": 70 }
  ]
}

Logical

Logical operations evaluate child operands using JavaScript truthiness.

Type	Operator	Inputs	Result
`logicalOperation`	`AND`	`operands: [left, right]`	`left && right`
`logicalOperation`	`OR`	`operands: [left, right]`	`left \|\| right`
`logicalOperation`	`NOT`	`operands: [value]`	`!value`

Because the implementation uses JavaScript logical operators directly, AND and OR return the selected operand value, not necessarily a boolean.

JSON Example:

JSON

{
  "type": "logicalOperation",
  "operator": "AND",
  "operands": [
    { "type": "variable", "path": ["entity", "custom_data", "isOnline"] },
    {
      "type": "comparisonOperation",
      "operator": ">",
      "operands": [
        { "type": "variable", "path": ["entity", "custom_data", "batteryLevel"] },
        { "type": "constant", "value": 20 }
      ]
    }
  ]
}

Conditional

Conditional functions choose which child operand to evaluate based on earlier operands.

Type	Operator	Inputs	Result
`conditionalFunction`	`if`	`operands: [condition, thenValue, elseValue]`	Evaluates `condition` using JavaScript truthiness. Returns `thenValue` when truthy; otherwise returns `elseValue`.
`conditionalFunction`	`switch`	`operands: [expression, caseValue1, result1, ..., defaultValue]`	Evaluates `expression`, then compares it to each case value with strict equality. Returns the result paired with the first matching case, or `defaultValue` when no case matches.

JSON Example:

JSON

{
  "type": "conditionalFunction",
  "operator": "if",
  "operands": [
    { "type": "variable", "path": ["entity", "custom_data", "isOnline"] },
    { "type": "constant", "value": "online" },
    { "type": "constant", "value": "offline" }
  ]
}

String

String functions operate on text-like values.

Type	Operator	Inputs	Result
`stringFunction`	`concat`	`operands: Operand[]`	Evaluates each operand and joins the values with no separator.
`stringFunction`	`split`	`operands: [stringValue, delimiterValue]`	Converts non-null inputs to strings and returns `String(stringValue).split(String(delimiterValue))`. If `stringValue` is `null` or `undefined`, returns `[]`. A `null` or `undefined` delimiter becomes `''`.

JSON Example:

JSON

{
  "type": "stringFunction",
  "operator": "concat",
  "operands": [
    { "type": "variable", "path": ["entity", "custom_data", "name"] },
    { "type": "constant", "value": " - " },
    { "type": "variable", "path": ["entity", "custom_data", "status"] }
  ]
}

Aggregate

Aggregate functions operate on one array operand. They only include entries that are numbers and not NaN in their calculations.

Type	Operator	Inputs	Result
`aggregateFunction`	`sum`	`operands: [array]`; `array` must evaluate to an array	Sum of numeric entries. Starts at `0`.
`aggregateFunction`	`average`	`operands: [array]`; `array` must evaluate to an array	Sum of numeric entries divided by the array length.
`aggregateFunction`	`max`	`operands: [array]`; `array` must evaluate to an array	Maximum numeric entry. Starts at `-Infinity`.
`aggregateFunction`	`min`	`operands: [array]`; `array` must evaluate to an array	Minimum numeric entry. Starts at `Infinity`.

JSON Example:

JSON

{
  "type": "aggregateFunction",
  "operator": "sum",
  "operands": [
    {
      "type": "constant",
      "value": [
        { "type": "variable", "path": ["entity", "custom_data", "mondayRunHours"] },
        { "type": "variable", "path": ["entity", "custom_data", "tuesdayRunHours"] },
        { "type": "variable", "path": ["entity", "custom_data", "wednesdayRunHours"] }
      ]
    }
  ]
}

Array

Array functions operate on array values and, for callbacks, create scoped variables for each iteration.

Type	Operator	Inputs	Result
`arrayFunction`	`map`	`operands: [array, mapper]`; `array` must evaluate to an array	Returns `array.map(...)`. For each item, `mapper` is evaluated with `$arrayItem` set to the current item.
`arrayFunction`	`filter`	`operands: [array, predicate]`; `array` must evaluate to an array	Returns `array.filter(...)`. For each item, `predicate` is evaluated with `$arrayItem` set to the current item and kept when the result is truthy.
`arrayFunction`	`reduce`	`operands: [array, reducer, initialValue]`; `array` must evaluate to an array	Returns `array.reduce(...)`. For each item, `reducer` is evaluated with `$accumulator` set to the current accumulator and `$arrayItem` set to the current item.
`arrayFunction`	`length`	`operands: [array]`; `array` must evaluate to an array	`array.length`
`arrayFunction`	`contains`	`operands: [array, value]`; `array` must evaluate to an array	`array.includes(value)`
`arrayFunction`	`indexOf`	`operands: [array, value]`; `array` must evaluate to an array	`array.indexOf(value)`
`arrayFunction`	`concat`	`operands: [array1, array2]`; both operands must evaluate to arrays	`array1.concat(array2)`

Callback variable examples:

JSON

{ "type": "variable", "path": ["$arrayItem"] }

JSON

{ "type": "variable", "path": ["$accumulator"] }

JSON Example:

JSON

{
  "type": "arrayFunction",
  "operator": "filter",
  "operands": [
    {
      "type": "constant",
      "value": [
        { "type": "variable", "path": ["entity", "custom_data", "morningTemperature"] },
        { "type": "variable", "path": ["entity", "custom_data", "afternoonTemperature"] },
        { "type": "variable", "path": ["entity", "custom_data", "eveningTemperature"] }
      ]
    },
    {
      "type": "comparisonOperation",
      "operator": ">",
      "operands": [
        { "type": "variable", "path": ["$arrayItem"] },
        { "type": "constant", "value": 80 }
      ]
    }
  ]
}

Statistical

Statistical functions operate on one array operand, except percentile, which also takes a comparison value. These functions expect array contents to be numeric because they perform numeric sorting and arithmetic directly.

Type	Operator	Inputs	Result
`statisticalFunction`	`mean`	`operands: [array]`; `array` must evaluate to an array	Arithmetic mean of the array.
`statisticalFunction`	`median`	`operands: [array]`; `array` must evaluate to an array	Median of the numerically sorted array.
`statisticalFunction`	`mode`	`operands: [array]`; `array` must evaluate to an array	Mode of the numerically sorted array.
`statisticalFunction`	`standardDeviation`	`operands: [array]`; `array` must evaluate to an array	Standard deviation of the array.
`statisticalFunction`	`variance`	`operands: [array]`; `array` must evaluate to an array	Variance of the array.
`statisticalFunction`	`percentile`	`operands: [array, value]`; `array` must evaluate to an array and `value` must be a number	Percentage of entries below `value`, counting entries equal to `value` as half.

JSON Example:

JSON

{
  "type": "statisticalFunction",
  "operator": "mean",
  "operands": [
    {
      "type": "constant",
      "value": [
        { "type": "variable", "path": ["entity", "custom_data", "morningTemperature"] },
        { "type": "variable", "path": ["entity", "custom_data", "afternoonTemperature"] },
        { "type": "variable", "path": ["entity", "custom_data", "eveningTemperature"] }
      ]
    }
  ]
}