Skip to main content

Thing Definition Automations

Support
  • Updated

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:

  1. Enter the Automations page.
  2. Select the Thing Definitions tab.
  3. Select the Thing Definition to edit.
  4. Press the Add Automation button.
  5. Provide the required information.
  6. 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.

Related articles

Comments

0 comments

Please sign in to leave a comment.