Alerts

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

AttributeDescription
idA 23 to 26 characters long string that uniquely identifies this alert.
nameA 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.
friendlyNameHuman friendly name of the alert.
ownerIdThe entity owning the method. Owner entity can be device profile or device.
descriptionDescription of this alert. Optional.
tagsTags attached to this alert.
triggerIdId of the property that this alert is bound to.
ttlTime-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.
statusCan be enabled and disabled. Default enabled.
metricMetric 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.
conditionsList of conditions that will trigger the alert. see Conditon object below.
recoverSingle alert handler that will be executed after alert is recovered.
notificationsList of notifications that will notify the related parties. see Notification object below
lockedif locked, entity cannot be modified, deleted.
dateCreatedThe date that this alert was created in ISO 8601 format.
dateModifiedThe 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:

AttributeDescription
severityCan be critical, warning, and notification.
expressionContains 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.
handlersSequence 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:

AttributeDescription
nameAlert wide unique name of the notification.
actionCan be email, sms, method, webhook, or log.
messageMessage 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 header x-connio-signature will 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 given signatureKey attribute 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."

PlaceholderDescription
account.idAccount id
alert.idAlert id
alert.nameAlert name
property.idTrigger property id
property.nameTrigger property name
device.idDevice id if device alert
device.nameDevice name if device alert
app.idApp id if app alert
app.nameApp name if app alert
valueCurrent value of the trigger that initiated the alert incident
last_valuePrevious value of the trigger property
timestampTimestamp of the value