View Source Triggers

Triggers in Astarte are the go-to mechanism for generating push events. In contrast with AppEngine's REST APIs, Triggers allow users to specify conditions upon which a custom payload is delivered to a recipient, using a specific action, which usually maps to a specific transport/protocol, such as HTTP.

Given this kind of flexibility, triggers are the most powerful way to push data to an external service, potentially without any additional customization.

Triggers can be managed from Realm Management API, astartectl with the astartectl realm-management triggers subcommand, or Astarte Dashboard in the Triggers page.

building-triggers
Building Triggers

Triggers can be either built manually or using Astarte Dashboard's Trigger Editor. Trigger Editor dynamically loads installed Interfaces in the Realm and eases trigger creation by providing not only linting and validation, but also dynamic resolution of Interface names.

Trigger Editor works in a very similar fashion to Interfaces Editor, and shares the same User Interface.

format
Format

A trigger is described using a JSON document. Each trigger is defined by two main parts: condition and action.

This is a JSON representation of an example trigger:

{
  "name": "example_trigger",
  "action": {
    "http_url": "https://example.com/my_hook",
    "http_method": "post"
  },
  "simple_triggers": [
    {
      "type": "data_trigger",
      "on": "incoming_data",
      "interface_name": "org.astarte-platform.genericsensors.Values",
      "interface_major": 0,
      "match_path": "/streamTest/value",
      "value_match_operator": ">",
      "known_value": 0.4
    }
  ]
}

The condition is represented by the simple_triggers array. In this release, Astarte supports only a single entry in the simple_triggers array, but support for multiple simple triggers (and different ways to combine them) is planned for future releases.

The condition in the example specifies that when data is received on the org.astarte-platform.genericsensors.Values interface on /streamTest/value path, if the value of said data is > 0.4, then the trigger is activated. For more information about all the possible conditions, check out the Conditions section

The action object describes what the result of the trigger will be. In this specific case, an HTTP POST request will be sent to https://example.com/my_hook, with the payload:

{
  "timestamp": "<event_timestamp>",
  "device_id": "<device_id>",
  "event": {
    "type": "incoming_data",
    "interface": "org.astarte-platform.genericsensors.Values",
    "path": "/streamTest/value",
    "value": <some_value>
  }
}

To know more about all possible actions, check the Actions section

conditions
Conditions

A condition defines the event upon which an action is triggered. Conditions are expressed through simple triggers. Astarte 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

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_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

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

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 Astarte 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.

actions
Actions

Actions are triggered by a matching condition. An Action defines how the event should be sent to the outer world (e.g. an http POST on a certain URL). In addition, most actions have a Payload, which carries the body of the event.

http-actions
HTTP Actions

Payloads are most of the time represented as text, and Astarte provides several ways to generate them. By default Astarte generates a JSON payload with all the relevant information of the event. This is also the format used when delivering payloads in Astarte Channels. The format of the payload can be found in the Default action section.

Astarte also provides a powerful templating mechanism for plain-text payloads based on top of Mustache. This is especially useful for integrating with third-party actors which require custom plain-text payloads. Keep in mind that Mustache templates are only able to produce text/plain payloads, not valid JSON.

Default action

This is the configuration object representing a minimal default action:

{
  "http_url": "<http_url>",
  "http_method": "<method>"
}

The default action sends an HTTP request to the specified http_url using http_method method (e.g. POST).

Further options might be used, such as "http_static_headers", enabling auth to remote services:

{
  "http_url": "<http_url>",
  "http_method": "<method>",
  "http_static_headers": {
    "Authorization": "Bearer <token>"
  },
  "ignore_ssl_errors": <true|false>
}

The ignore_ssl_errors key is optional and defaults to false. If set to true, any SSL error encountered while doing the HTTP request will be ignored. This can be useful if the trigger must ignore self-signed or expired certificates.

Please, beware that some http headers might be not allowed or reserved for http connection signaling.

simpleevent-payloads
SimpleEvent payloads

The payload delivered in a default HTTP action or in Astarte Channels is a JSON document with this format:

{
  "timestamp": "<timestamp>",
  "device_id": "<device_id>",
  "trigger_name": "<trigger_name>",
  "event": <event>
}

timestamp is an UTC ISO 8601 timestamp (e.g. "2019-10-16T08:56:08.534377Z") representing when the event happened.

device_id identifies the device that triggered the event.

trigger_name identifies the trigger that fired the event.

event is a JSON object that has a specific structure depending on the type of the simple_trigger that generated it. Event objects are detailed below.

Additionally, the realm that originated the trigger is available in the request in the Astarte-Realm header.

Event objects

DeviceConnectedEvent

{
  "type": "device_connected",
  "device_ip_address": "<device_ip_address>"
}

device_ip_address is the IP address of the device.

DeviceDisconnectedEvent

{
  "type": "device_disconnected"
}

DeviceErrorEvent

{
  "type": "device_error",
  "error_name": "<error_name>",
  "metadata": {
    "<key>": "<value>"
  }
}

error_name is a string identifying the error. More details can be found in the device errors documentation

metadata is a map with string key and string values that may contain additional information about the error. Some metadata (e.g. binary payloads) might be encoded in base64 if they cannot be represented as string. In that case, the key is prepended with the base64_ prefix.