Skip to main content

Conditions

A condition defines the event upon which an action is triggered. Conditions are expressed through simple triggers. Data Orchestrator monitors incoming events and triggers a corresponding action whenever there is a match.

Simple triggers are divided into two types: Device Triggers and Data Triggers.

Device Triggers​

Device triggers express conditions matching the state of a device.

This is the generic representation of a Device Trigger:

{
"type": "device_trigger",
"on": "<device_trigger_type>",
"device_id": "<device_id>",
"group_name": "<group_name>"
}

Parameters​

device_trigger_type can be one of the following:

  • device_connected: triggered when a device connects to its transport.
  • device_disconnected: triggered when a device disconnects from its transport.
  • device_error: triggered when data from a device causes an error.
  • device_registered: triggered when a device is registered to Data Orchestrator.
  • device_deletion_started: triggered when the deletion of a device is started.
  • device_deletion_finished: triggered when the deletion of a device is finished.
  • incoming_introspection: triggered when Data Orchestrator receives an introspection message from the device.
  • interface_added: triggered when an interface is added to the device introspection.
  • interface_removed: triggered when an interface is removed from the device introspection.
  • interface_minor_updated: triggered when the device introspection contains a new minor version of an interface.

device_id can be used to pass a specific Device ID to restrict the trigger to a single device. * is also accepted as device_id to maintain backwards compatibility and it is considered equivalent to no device_id specified.

group_name can be used to restrict the trigger to all devices that are member of the group.

device_id and group_name are mutually exclusive and if neither of them is specified in the simple trigger, the simple trigger will be installed for all devices in a realm.

Data Triggers​

Data triggers express conditions matching data coming from a device.

This is the generic representation of a Data Trigger:

{
"type": "data_trigger",
"device_id": "<device_id>",
"group_name": "<group_name>",
"on": "<data_trigger_type>",
"interface_name": "<interface_name>",
"interface_major": "<interface_major>",
"match_path": "<match_path>",
"value_match_operator": "<value_match_operator>",
"known_value": <known_value>
}

Data triggers are installed for all devices in a Realm.

Data Triggers Parameters​

device_id can be used to pass a specific Device ID to restrict the trigger to a single device. * is also accepted as device_id to maintain backwards compatibility and it is considered equivalent to no device_id specified.

group_name can be used to restrict the trigger to all devices that are member of the group.

device_id and group_name are mutually exclusive and if neither of them is specified in the simple trigger, the simple trigger will be installed for all devices in a realm.

data_trigger_type can be one of the following:

  • incoming_data: verifies the condition whenever new data arrives.
  • value_stored: verifies the condition whenever new data arrives, after it is saved to the database.
  • value_change: works only with properties interface; verifies the condition whenever the received value is different from the previous one.
  • value_change_applied: works only with properties interface; verifies the condition whenever the last value received is different from the last one previously received, after it is saved to the database.
  • path_created: verifies the condition whenever a new path in a property interface is set or the first value is streamed on a datastream interface.
  • path_removed: works only with properties interface; verifies the condition whenever a property path is unset.

interface_name and interface_major represent, respectively, the Interface name and major version that uniquely identify an Data Orchestrator Interface. interface_name can be * to match all interfaces; in that case interface_major is ignored and all major numbers are matched.

match_path is the path that will be used to match the condition. It can be /* to match all the paths of an interface.

value_match_operator is the operator used to match the incoming data against a known value. It can be * to indicate that all values should be matched (known_value is ignored in that case), otherwise it can be one of these operators: ==, !=, >, >=, <, <=, contains, not_contains. The match is always performed with <incoming_value> <operator> <known_value>. contains and not_contains can be used only with type string, binaryblob and with array types.

known_value is the value used with value_match_operator to perform the comparison on the incoming value. It must have the same type as the incoming value, except in the contains and not_contains case.