Using notification rules and actions

After you have modelled and activated your device twin or device twin and sent some data, you can use rules and actions to automatically respond to changes in the state of your devices in close to real time.

About rules and actions

In Platform Service, a rule can be used to detect situations where the state of a device or thing is outside of normal ranges and conditions and generate a notification in response. For example, you can define a rule to detect when the temperature of a device spikes for a specified amount of time.

In Platform Service, an action can be used to automatically perform tasks or operations in response to notifications generated by the Platform Service. For example, you can define an action that sends an alert to the dashboard on a user's device in response to a rule notification.

For more information on how to create rules, see the following topics:

Rules overview

A rule consists of a condition and a notification strategy.

Item Description Notes
Condition Conditions are JSONata expressions that must evaluate to true or false. They can reference properties on the state of the device or thing using the $state variable. They can also reference attributes or metadata on the device or thing instance using the $instance variable. This can be used to avoid hardcoding values in the condition. Example: $state.temperature > 100
In this example, the condition is checking whether value of the temperature property on the state is greater than 100.
Example: $state.temperature > $instance.metadata.tempThresholdMax
In this example, the condition is checking whether value of the temperature property on the state is greater than the value of the tempThresholdMax property defined on the metadata of the device or thing instance.
Notification strategy The Platform Service does not automatically publish a rule notification when the rule condition evaluates to true. The timing and frequency of rule notifications is controlled using the notification strategy defined on the rule. The notification strategy must be one of the following:
  • Every time
  • Frequency
  • Becomes true
  • Persists

Rules conditions are evaluated when an event that is received by Platform Service contributes to the state of a device or thing. The event does not need to result in a change of state in order for the rules to be evaluated. This is called "event-driven evaluation."

Rule notifications

A rule is triggered when the condition evaluates to true and the criteria specified by the notification strategy are met. When a rule is triggered, an MQTT message is published to the following topic:

iot-2/intf/<logicalInterfaceId>/rule/<ruleId>/evt/trigger

An example of the payload of the MQTT message is shown below:

{
  "type": "device",
  "typeId": "EcoBox_v2.0",
  "instanceId": "TestEcoplantGateway",
  "logicalInterfaceId": "5cffca3a81bf7c00228d1c9c",
  "ruleId": "5cffca3e81bf7c00228d1c9f",
  "ruleCondition": "$state.temperature > 100",
  "state" : {
    "temperature": 105
  },
  "timestamp": "2018-01-31T10:29:28Z",
  "updated": "2018-01-31T10:29:10Z"
}

If an error occurs during rule evaluation, an error message is published to the following MQTT topic:

iot-2/intf/<logicalInterfaceId>/rule/<ruleId>/err/data

The message body includes information that can be used to debug the error, including:

An example of the payload of the MQTT error message is shown below:

{
  "type": "device",
  "typeId": "TSensor",
  "instanceId": "tSensor",
  "logicalInterfaceId": "5846ed076522050001db0e12",
  "ruleId": "5i8t306d59087777329f1c56",
  "ruleCondition": "$state.temperature > 100",
  "message": "The result of expression evaluation is not of type boolean.",
  "state": {
    "temperature": 105
  }
}

Consuming rule notifications

You can now configure an action that is initiated when a rule is triggered.

Type of action Learn more...
Platform Service actions You can create built-in Platform Service actions, and associated triggers, that are executed when a rule is triggered. For more information, see Actions.
External applications You can implement an application that subscribes to the MQTT topic for rule notifications and performs custom logic when a message is received. For more information, see Application development.