Servitly allows defining automations, which are executed on products specific events, to trigger actions, like sending an email or calling a third-party system API.
An automation can listen to the following events:
-
Measure Update: a condition is verified each time a metric value is updated (e.g. temperature → 100).
-
Alert Activated: an alert has been deactivated.
-
Alert Cleared: an alert has been deactivated.
An automation can execute the following actions:
-
Notification: send a notification to an external address (at the moment only the email channel is supported).
-
Callback: perform a request on an external REST API.
- Execute Command: execute a command on the remote-connected product.
Creating an Automation
To add a new Automation to a Thing Definition, you should:
- Enter the Automations page.
- Select the Thing Definitions tab.
- Select the Thing Definition to edit.
- Press the Add Automation button.
- Provide the required information.
- Press the Save button and edit the additional information, if needed.
Editing an Automation
By selecting an Automation, you can edit its properties, including event and the related actions to be executed.
Events
According to the event type, different conditions can be then specified.
On Measure Update
This event is triggered every time the value of the selected metric changes.
The condition requires selecting a Metric of the thing definition, and specify a predicate and value.
On Event Activated / Cleared
This event is triggered every time a specific Event is activated or cleared.
The condition requires selecting an Event of the thing definition.
Actions
The automation allows configuring the actions to be triggered when the condition is verified.
You can define multiple actions of these following types.
Notification
This action allows sending a notification email.
Within the Title, Short Message, and Long Message it is possible to use some Placeholders to include information about the thing, the automation, and the measure.
Callback URL
This action allows performing a request (POST only) to an external API.
For secure requests (HTTPS), the certificate handshaking is automatically performed by Servitly, for this reason, a certificate based on a public CA must be used, so self-signed certificates are not supported.
The endpoint can contain query string parameters (e.g. apiKey), note that the URL is invoked from the Servitly backend, so it must be reachable from the cloud.
The POST body will include all the information about the thing, automation, and measure.
Optionally, the basic HTTP authentication can be used by specifying the username and password.
Here is a JSON payload sent to the callback URL when the automation is triggered.
{ "alert": { "severity": "FAILURE", "duration": "7845", "activatedTime": "1581517331499", "description": "The oven is offline", "activatedTimeFormattedTZ": "2020-02-12 14:22:11[UTC]", "title": "Oven offline", "activatedTimeFormatted": "2020-02-12 14:22:11[UTC]", "durationFormatted": "7s" }, "thing": { "serialNumber": "OVEN-002", "gpsPosition": "45.687400, 9.025605", "name": "OVEN-002", "id": "5d5ea24463342200076a3c53", "serviceLevel": "Pay-per-use", "properties": { "networkInterface": "WIFI", "serviceDueDate": "1590662457621" } }, "thingDefinition": { "name": "Oven-1200w", "id": "5c795c602074420008bcd6ef", "properties": { "model": "1200W" } }, "location": { "country": "Italy", "gpsPosition": "45.655769,8.4920926", "name": "Sweet Life", "id": "5aeae7f34e22a20006f6145c", "properties": { "phoneNumber": "+39 02 125458965", "address": "via Della Stazione, 10", "city": "Fontaneto D'agogna" } }, "customer": { "country": "Italy", "name": "Sweet Bakery", "id": "5aeae7ee2ce57500072b9e65", "properties": { "phoneNumber": "+39 02 125458965", "vatNumber": "5674568901" } }, "partner": { "country": "Italy", "code": "12484566", "timezone": "Europe/Rome", "name": "Oven Service", "id": "5cf5270f2d4d4a0008f5a27c", "properties": { "phoneNumber": "+39 02 23564158", "gpsPosition": "45.457787, 9.171554", "address": "via Ausonio, 21", "city": "Milano", "vatNumber": "12567842695429" } }, "metrics": {}, "timestamp": "1581517339344", "rule": { "name": "test", "id": "5e440967c5f85100010ceb5f", "event": "ON_ALERT_ACTIVATED" }, "action": { "name": "test" } }
The payload structure is fixed, but the attributes depend on the properties that have been configured on the various objects.
The alert node is present only in case the automation is based on alert event.
Execute Command
This action allows you to specify the command to be executed on the thing when the automation is triggered.
For instance, you can force the machine to reset when a certain condition occurs (e.g. temperature > 100 °C).
Placeholders
The following list reports the placeholders that can be used within message computation during automation processing.
Use the following syntax to include a placeholder within a text:
Rule triggered due to a power greater than ${metrics.Power.value} ${metrics.Power.unit}
PLACEHOLDER |
DESCRIPTION |
SAMPLE VALUE |
metrics.<METRIC_NAME>.value |
The value of the <METRIC_NAME> metric |
101, true, 12.77, LOW_WATER |
metrics.<METRIC_NAME>.unit |
The measuring unit of the <METRIC_NAME> metric |
Kg, m |
timestamp |
The timestamp the rule has been triggered |
1476271832909 |
rule.name |
The rule name |
High speed |
rule.event |
The event triggering the rule |
ON_MEASURE_UPDATE, ON_CONNECTION_STATE_CHANGED |
rule.predicate |
The rule predicate |
=, <, >, != |
rule.value |
The rule comparison value |
100, ABC, 12.77 |
action.name |
The action name, available only within an action |
User Notification |
thing.id |
The thing identifier |
asdg2354346tsdggd3456356 |
thing.name |
The thing name |
Printer-floor1 |
thing.serialNumber |
The thing serial number |
XY000001 |
thing.properties.<PROP_NAME> |
The value of the property named <PROP_NAME>. |
|
thing.serviceLevel |
The Service Level name associated with the Thing |
GOLD |
thingDefinition.id |
The thing definition identifier |
asdg2354346tsdggd3456356 |
thingDefinition.name |
The thing definition model name |
Mod123 |
thingDefinition.properties.<PROP_NAME> |
The value of the property named <PROP_NAME>. |
|
Execution policy
Suppose to have a condition that checks the temperature:
temperature > 50
Actions are triggered only when the value overtakes the threshold, for instance:
T1 |
40 °C |
DO NOTHING |
T2 |
50 °C |
DO NOTHING |
T3 |
55 °C |
DO ACTIONS |
T4 |
65 °C |
DO NOTHING |
T5 |
40 °C |
DO NOTHING |
T6 |
55 °C |
DO ACTIONS |
T7 |
57 °C |
DO NOTHING |
Options
This section allows defining options to be used within the event definition and whose value can be redefined by the end-user within the page by suing the thing-options widget.
For more details, see the Options article.
Thing Automations
Within the DPS editing page of a thing, you can select the Automations tab to configure automations that will be evaluated only for the selected thing. For instance, a customer can define a automation to invoke a legacy API under certain conditions and trigger some automations.
Comments
0 comments
Please sign in to leave a comment.