Mapping expression language

Expression language and notification rules

The mapping expression language has been extended for use with the data management Using notification rules and actions through the introduction of $state and $instance variables which are defined for use in expressions.

• The $state variable is used to reference properties on the device state in an expression, for example, $state.temperature.
• The $instance variable is used to reference attributes and metadata on the device instance in an expression, for example, $instance.metadata.tempThresholdMax.

You might want to use these variables so that you do not need to hard-code values in your notification rule condition expressions, and can set a different threshold value for each device instance.

JSONata operators

All JSONata Operators are supported, except as listed:

• Path operators
  Not supported:
  • ^(…) (Order-by)
• Numeric operators
• Comparison operators
• Boolean operators
• Other operators
  Not supported:
  • ~> (Chain)
  • := (Variable binding)
  • ... ~> | ... | ... | (Transform)

• Use Parenthesis ( ) for expression grouping and to alter operator precedence.
• Use single or double quotes to surround strings and property names, for example $event.object.'ab'.
• Use back-ticks to surround property names that contain special characters, including spaces, for example:

  {"x y":22}.`x y`

• Use back-ticks to surround property names that begin with a number, for example `7emperature`

JSONata functions

• All String functions
• All Numeric functions
• All Numeric aggregation functions
• All Boolean functions
• The following Array functions:
  • $count
  • $append

Extending the mapping expression language

The mapping expression language has been extended for use with the data management feature through the introduction of $event, $state and $instance variables. JSON is bound to these variables before the expression is evaluated. The following table provides an overview of these variables, which are defined for use in expressions:

The following example uses the following object as the input to an event:

{
    "temperature": 35,
    "humidity": 72,
    "pressure": 1024
}

The object is converted to an array by using the following expression:

[$event.temperature, $event.humidity, $event.pressure]

The expression results in the generation of the following output:

 [
    35,
    72,
    1024
  ]

You can reverse this example, and convert an array from the input to an object. The following example uses the following array as the input to an event:

{
    "readings": [
      35,
      72,
      1024
    ]
  }

The array is converted to an object by using the following expression:

 {"temperature": $event.readings[0], "humidity": $event.readings[1], "pressure": $event.readings[2]}

The expression results in the generation of the following output:

{
  "temperature": 35,
  "humidity": 72,
  "pressure": 1024
}

You can also define an expression that combines the use of these variables. In the following example, a temp_adjustment property is defined in the device metadata and is used to calibrate the event reading. The property is defined in one mapping but can be applied to many devices.

"propertyMappings" : {
        "tevt" : {
           "temperature" : "$event.t + $instance.metadata.temp_adjustment"
        }
     },

The dot operator "." is used for object access with a literal key, for example $event.object.hh. The first expression, which in the example is $event.t, is constrained to a specific property, either in the event ($event) or the state ($state) or the metadata ($instance). The second expression, which in the example is $instance.metadata.temp_adjustment, contains the information that you might want to access.

Language guide

• All Simple queries are supported.
• Predicate queries are supported, except for wildcards.
• Parenthesized expressions are supported, except for code blocks.
• The following Conditional expressions are supported:
  • Conditional logic
  • Variables
    Variables are supported through the use of the $instance, $state, and $event variables as part of the extended mapping language which is specific this data management feature.
    Note: The $ and $$ variables that are used in JSONata are not currently supported.
  • Invocation of most predefined functions.
    
    Note: You cannot define your own functions.

Constructing output

You can specify how processed data is presented in the output by using array constructors or object constructors.

Supported array constructors

Arrays can be constructed by enclosing a comma-separated list of literals or expressions in a pair of brackets. Commas are used to separate multiple expressions within the array constructor inlcuding sequence generation, for example, [1, 3-1] = [1,2], [1..3] -> [1,2,3] and [1..3, 7..9] -> [1,2,3,7,8,9].

Supported object constructors

You can construct JSON objects in your output by using a pair of braces {} that contain key values or pairs separated by commas, with each key and value separated by a colon, for example, {key1 : value1, key2:value2} or {"hello" : "world"}. The object key must be a string.

Handling mismatches between mapping expression and input data

A state update might fail when one of the mapping expressions contains a reference to input data that is not specified in the published event.

For example, you might configure the following expressions:

temperature = $event.t
humidity = $event.hum

where t is an optional property for the event.

If an event that contains only humidity data is received, for example, {"humidity":22}, then the expression temperature = $event.t fails to evaluate, because the optional t property is not specified in the published device event.

The state update fails. The humidity state property is not updated, and an error message is published to the MQTT error topic for the device:

iot-2/type/${typeId}/id/${deviceId}/err/data

To prevent state update failures because of unspecified optional data, you can use the $exists function in combination with a ternary conditional to specify a default value for optional properties. The following example defines a default value of 0 for the t property:

"tempEvent:
    {
      "temperature": "$exists($event.t)?$event.t:0",
      "humidity": "$event.hum"
    }

By defining a default value for the optional property in this way, the expression evaluates successfully, even when the t property is not specified in the published device event.

Therefore, if the event {"humidity":22} is received, the state update completes successfully and the device state is set to {"humidity":22, "temperature":0}.