Allows you to alert involving parties when device or app level anomalies arise such as device went offline, temperature is above 35°C. Like similar mechanisms, Alert consists of events, checks/conditions and actions.
Alerts can be created at device, app, app profile or device profile level. When created at profile level, all devices and apps generated from this profile automatically gets a copy of the alert definition.
Unlike property and method, alert is not considered a pure element of the object model, therefore it cannot be inherited by child profiles.
See Alert Entity for details.
Resource Attributes
| Attribute | Description |
|---|---|
| id | A 23 to 26 characters long string that uniquely identifies this alert. |
| name | A name that uniquely identifies the alert among its siblings. Unlike other resources, alert name cannot be used as slug since the name is only context sensitive. |
| friendlyName | Human friendly name of the alert. |
| ownerId | The entity owning the method. Owner entity can be device profile or device. |
| description | Description of this alert. Optional. |
| tags | Tags attached to this alert. |
| triggerId | Id of the property that this alert is bound to. |
| ttl | Time-to-live period for the data point that will trigger the alert. For example if TTL is 30s then the system raise the alert if and only if the incoming data point's source time (or capture time) is within 30 seconds time window. Possible units are d for day, h for hour, min for minute, s for second, and ms for millisecond. |
| status | Can be enabled and disabled. Default enabled. |
| metric | Metric calculation formula. Simple property value (i.e "value"), or aggregators such as avg(), count(), min(), max(), and sum() over a period can be used to calculate its value. If the property type is waypoint, it is possible to use geoFence() function to create, well, a geo-fence. Metric is used in combination with condition object expression to trigger the alert. You can find usage samples below. |
| conditions | List of conditions that will trigger the alert. see Conditon object below. |
| recover | Single alert handler that will be executed after alert is recovered. |
| notifications | List of notifications that will notify the related parties. see Notification object below |
| locked | if locked, entity cannot be modified, deleted. |
| dateCreated | The date that this alert was created in ISO 8601 format. |
| dateModified | The date that this alert was modified in ISO 8601 format. |
Aggregate Functions
Aggregators can be used if and only if the given property's retention policy is
historical.
{
"id": "_ale_392736003857137341",
"accountId": "_acc_392726790711190051",
"ownerId": "_dpf_392727069718560420",
"name": "machine.temperature.alert",
"friendlyName": "Machine temperature alert",
"description": "Raised when the machine temperature average reaches to certain threshold over 16 minute period",
"tags": [
"temperature"
],
"triggerId": "_prp_392727127019887390",
"status": "enabled",
"metric": "avg(16min)",
"recover": {
"key": "H0",
"notification": "back_to_normal"
},
"conditions": [
{
"severity": "warning",
"expression": {
"operation": "gt",
"value": 45.2
},
"handlers": [
{
"key": "H1",
"notification": "logme",
"next": "H2",
"timeout": "1 minute"
},
{
"key": "H2",
"notification": "emailme",
"next": "H1",
"timeout": "1 minute"
}
]
},
{
"severity": "critical",
"expression": {
"operation": "gt",
"value": 65.1
},
"handlers": [
{
"key": "H1",
"notification": "logme",
"next": "H2",
"timeout": "1 minute"
},
{
"key": "H2",
"notification": "turnoff",
"next": "H1",
"timeout": "1 minute"
}
]
}
],
"notifications": [
{
"action": "log",
"name": "logme",
"level": "info",
"message": "${device.name}'s temperature exceeded its limit"
},
{
"action": "email",
"name": "emailme",
"to": "[email protected]",
"subject": "${property.name} property on device ${device.name} is above 45°C",
"message": "Current ${property.name} value is ${value}°C; it was ${last_value}°C before. Shutdown the engine if goes above 65°C."
},
{
"action": "method",
"name": "turnoff",
"method": "_mtd_392727204042600572",
"parameter": "stop"
},
{
"action": "email",
"name": "back_to_normal",
"to": "[email protected]",
"subject": "${alert.name} incident is recovered",
"message": "Everything back to normal for ${device.name}"
}
],
"locked": false,
"dateCreated": "2018-06-26T20:56:20Z",
"dateModified": "2018-06-26T20:56:20Z"
}
Condition Object
A condition is a value object and consists of the following attributes:
| Attribute | Description |
|---|---|
| severity | Can be critical, warning, and notification. |
| expression | Contains an expression that yields a scalar or boolean value. Non zero scalar values and true executes the given notifications. Consists of operation and value fields. operation fields can be eq, lt, lte, gte, gt, and match (for case insensitive text comparison). value holds the threshold value that will be compared to the metric value using the comparison operator specified in operation field. For example, if metric is avg(15min) for a temperature property, and expression is gt with value 50.0, then the full expression should be evaluated by the system as average(temperature, 15min) > 50.0. |
| handlers | Sequence of notifications will be used by this condition to alert. The given notifications should exist in the alert notification list. |
See Alert Entity for alert mechanism internals.
Notification Object
A notification is a value object and consists of the following attributes:
| Attribute | Description |
|---|---|
| name | Alert wide unique name of the notification. |
| action | Can be email, sms, method, webhook, or log. |
| message | Message of the notification. Can contain variables. |
| .... | Notification type specific attributes will follow. See below. |
Possible notification types are:
...
"notifications": [
{
"name": "Email-Notif-Sample",
"action": "email",
"to": "[email protected]",
"subject": "${alert.name} is triggered",
"message": "Hello world!"
}
]
...
...
"notifications": [
{
"name": "SMS-Notif-Sample",
"action": "sms",
"to": "+1 604 2592423, +17789974545",
"message": "${alert.name} is raised for ${device.name}"
}
]
...
Telephone numbers must contain a country and area code.
...
"notifications": [
{
"name": "Method-Notif-Sample",
"action": "method",
"method": "_mtd_392727204042600572",
"parameter": "off"
}
]
...
Can be any type of public method belongs to the alert's object.
...
"notifications": [
{
"name": "Logging-Notif-Sample",
"logLevel": "info",
"action": "log",
"message": "${device.name}'s 5 minutes temperature average is ${value}°C."
}
]
...
...
"notifications": [
{
"name": "slack",
"action": "webhook",
"message": "{ \"text\": \"${device.name} used ${value} KiB of data\" }",
"method": "post", "url": "https://hooks.slack.com/services/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"
}
]
...
Method can be either post, put and get. Message attribute holds the payload. If your payload is in JSON, all " characters should be escaped.
SECURITY
Alternatively you can include an attribute to your webhook notification called
signatureKey. if this attribute is specified, then the headerx-connio-signaturewill be included to the call (both get, post and put). As we're always sending text of json payloads (not post forms) we're concatenating the url with the payload and computing HMAC-SHA1 with the givensignatureKeyattribute as the key. Finally we encode the result in Base64 and this becomes the value of this header.
Aggregator Metric Usage
(
available aggregator functions are:
geoFence: Geo-fence e.g. geoFence(49.3427886,-123.0959533,5.0)
avg: Average e.g. avg(5min)
max: Maximum
min: Minimum
sum: Sum
count: Count
Available time unit follow the same convention that alert handlers timeout although its maximum accuracy are milliseconds. Possible units are d for day, h for hour, min for minute, s for second, and ms for millisecond.
Examples:
avg(15min)
sum(1h)
max(2d)
Alert Acknowledgement
Unless the condition that triggered the alert is recovered or acknowledged explicitly by the user, it continues to be in active state. You can acknowledge an alert by making a request to the following URL:
DELETE .../devices/{ref}/alerts/{ref}/incident or .
DELETE .../apps/{ref}/alerts/{ref}/incident
Alert Incident Monitoring
You can monitor device and app alert incident by requesting device and app state.
Variables
You can use variables in the message that will be replaced with the actual values before the alert notification is executed. The format is:
${<variable>}
e.g.
"${device.name}'s 5 minutes temperature average is ${value}°C."
| Placeholder | Description |
|---|---|
| account.id | Account id |
| alert.id | Alert id |
| alert.name | Alert name |
| property.id | Trigger property id |
| property.name | Trigger property name |
| device.id | Device id if device alert |
| device.name | Device name if device alert |
| app.id | App id if app alert |
| app.name | App name if app alert |
| value | Current value of the trigger that initiated the alert incident |
| last_value | Previous value of the trigger property |
| timestamp | Timestamp of the value |