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
Payloads are most of the time represented as text, and Data Orchestrator provides several ways to generate them. By default Data Orchestrator generates a JSON payload with all the relevant information of the event. This is also the format used when delivering payloads in Data Orchestrator Channels. The format of the payload can be found in the Default action section.
Data Orchestrator 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
The payload delivered in a default HTTP action or in Data Orchestrator 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.
DeviceRegisteredEvent
{
"type": "device_registered"
}
DeviceDeletionStartedEvent
{
"type": "device_deletion_started"
}
DeviceDeletionFinishedEvent
{
"type": "device_deletion_finished"
}
IncomingIntrospectionEvent
{
"type": "incoming_introspection",
"introspection_map": {
"<interface_name>": {
"major": <major_value>,
"minor": <minor_value>
}
}
}
interface_name is the name of an interface. There is one map entry for each interface in the introspection.
<major_value> is the major version of the interface.
<minor_value> is the minor version of the interface.
InterfaceAddedEvent
{
"type": "interface_added",
"interface": "<interface_name>",
"major_version": <major_value>,
"minor_version": <minor_value>
}
interface_name is the name of the interface.
<major_value> is the major version of the interface.
<minor_value> is the minor version of the interface.
InterfaceRemovedEvent
{
"type": "interface_removed",
"interface": "<interface_name>",
"major_version": <major_value>
}
interface_name is the name of the interface.
<major_value> is the major version of the interface.
InterfaceMinorUpdatedEvent
{
"type": "interface_minor_updated",
"interface": "<interface_name>",
"major_version": <major_value>,
"old_minor_version": <old_minor_value>,
"new_minor_version": <new_minor_value>
}
interface_name is the name of the interface.
<major_value> is the major version of the interface.
<old_minor_value> is the old, outdated minor version of the interface declared by the device.
<new_minor_value> is the new minor version of the interface declared by the device.
IncomingDataEvent
{
"type": "incoming_data",
"interface": "<interface>",
"path": "<path>",
"value": <value>
}
interface is the interface on which data was received.
path is the path on which data was received.
value is the received value. Its type depends on the type of the mapping it's coming from.
binaryblob and binaryblobarray type values are encoded with Base64.
ValueStoredEvent
{
"type": "value_stored",
"interface": "<interface>",
"path": "<path>",
"value": <value>
}
interface is the interface on which data was received.
path is the path on which data was received.
value is the received value. Its type depends on the type of the mapping it's coming from.
binaryblob and binaryblobarray type values are encoded with Base64.
ValueChangeEvent
{
"type": "value_change",
"interface": "<interface>",
"path": "<path>",
"old_value": <old_value>,
"new_value": <new_value>
}
interface is the interface on which data was received.
path is the path on which data was received.
old_value is the previous value. Its type depends on the type of the mapping it's coming from.
binaryblob and binaryblobarray type values are encoded with Base64.
new_value is the received value. Its type depends on the type of the mapping it's coming from.
binaryblob and binaryblobarray type values are encoded with Base64.
ValueChangeAppliedEvent
{
"type": "value_change_applied",
"interface": "<interface>",
"path": "<path>",
"old_value": <old_value>,
"new_value": <new_value>
}
interface is the interface on which data was received.
path is the path on which data was received.
old_value is the previous value. Its type depends on the type of the mapping it's coming from.
binaryblob and binaryblobarray type values are encoded with Base64.
new_value is the received value. Its type depends on the type of the mapping it's coming from.
binaryblob and binaryblobarray type values are encoded with Base64.
PathCreatedEvent
{
"type": "path_created",
"interface": "<interface>",
"path": "<path>",
"value": <value>
}
interface is the interface on which data was received.
path is the path that has been created.
value is the received value. Its type depends on the type of the mapping it's coming from.
binaryblob and binaryblobarray type values are encoded with Base64.
PathRemovedEvent
{
"type": "path_removed",
"interface": "<interface>",
"path": "<path>"
}
interface is the interface on which data was received.
path is the path that has been removed.
Mustache action
This is the configuration object representing a Mustache action:
{
"http_url": "<http_url>",
"http_method": "<http_method>",
"template_type": "mustache",
"template": "<template>",
"ignore_ssl_errors": <true|false>
}
The Mustache action sends an HTTP request to the specified http_url, with the payload
built with the Mustache template specified in template. If the
template contains a key inside a double curly bracket (like so: {{ key }}), it will be substituted
with the actual value of that key in the event.
The basic keys that can be use to populate the template are:
{{ realm }}: the realm the trigger belongs to.{{ device_id }}: the device that originated the trigger.{{ trigger_name }}: the trigger name.{{ event_type }}: the type of the received event.
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.
Moreover, depending on the event type, all keys that are contained in the events described in the
previous section are available, always by wrapping them in {{ }}.
The realm is also sent in the Astarte-Realm header.
Example
This is an example of a trigger that uses Mustache action.
{
"name": "example_mustache_trigger",
"action": {
"template_type": "mustache",
"template": "Device {{ device_id }} just connected from IP {{ device_ip_address }}",
"http_url": "https://example.com/my_mustache_hook",
"http_method": "post"
},
"simple_triggers": [
{
"type": "device_trigger",
"on": "device_connected",
"device_id": "*"
}
]
}
When a device is connected, the following request will be received by
https://example.com/my_mustache_hook:
POST /my_mustache_hook HTTP/1.1
Data Orchestrator-Realm: test
Content-Length: 63
Content-Type: text/plain
Host: example.com
User-Agent: hackney/1.13.0
Device ydqBlFsGQ--xZ-_efQxuLw just connected from IP 172.18.0.1
Trigger Delivery Policies
When an HTTP action is triggered, an event is sent to a specific URL. However, it is possible that the request is not successfully completed, e.g. the required resource is momentarily not available. Trigger Delivery Policies specify what to do in case of delivery errors and how to handle events which have not been successfully delivered. A Trigger can be linked to one (at most) Trigger Delivery Policy by specifying the name of the policy in the "policy" field. If no Trigger Delivery Policies are specified, Data Orchestrator will resort to the default (pre v1.1) behaviour, i.e. ignoring delivery errors. Refer to the relevant documentation for more information on Trigger Delivery Policies.
AMQP 0-9-1 Actions
AMQP 0-9-1 actions might be configured as an alternative to HTTP actions for advanced use cases. AMQP 0-9-1 is the right choice for a number of scenarios, including Data Orchestrator Flow integration, high performance ingestion, integration with an existing AMQP infrastructure, etc...
Payloads are always encoded using protobuf, therefore if any other format is required Data Orchestrator Flow should be employed as a format converter.
This is a minimal configuration object representing an AMQP 0-9-1 action:
{
"amqp_exchange": "astarte_events_<realm-name>_<exchange-suffix>",
"amqp_routing_key": "my_routing_key",
"amqp_message_expiration_ms": <expiration in milliseconds>,
"amqp_message_persistent": <true when disk persistency is used>
}
It is possible to configure more advanced AMQP 0-9-1 actions:
{
"amqp_exchange": "astarte_events_myrealm_myexchange",
"amqp_routing_key": "my routing key",
"amqp_static_headers": {
"key": "value"
},
"amqp_message_expiration_ms": 10000,
"amqp_message_priority": 0,
"amqp_message_persistent": true
}
Some Data Orchestrator specific restrictions apply:
amqp_exchangemust haveastarte_events_<realm-name>_<any-allowed-string>format.amqp_routing_keymust not contain{and}, which are reserved for future uses.
For further details RabbitMQ documentation is suggested.
Starting from version v1.3.0, AMQP exchanges for AMQP actions are declared inside a dedicated RabbitMQ vhost associated with the target realm. The vhost naming convention is:
/[astarte_instance_id]_[realm_name]
but under normal circumstances, astarte_instance_id is not set, so it becomes:
/_[realm_name]
As a result, the action will now refer to the exchange within the realm-specific vhost, rather than under the default / vhost as in the previous logic.
For additional details regarding the Data Orchestrator Instance ID, you can refer to its documentation.