Alarms Notifications

Notifications are optional properties of an alarm. They allow to send different types of messages when the state of the alarm changes.

Types of notifications

There are different types of notifications available :

Email : an email is send either to a user of the current account, based on the user Id and the email address registered in the user's profile, or directly to a given email address.
Sms : a SMS is send either to a user of the current account, based on the user Id and the phone number registered in the user's profile, or directly to a given phone number.
Webhook : a custom webhook is sent to a specific URL. To use this type of notification, it is necessary to firstly create an 'alarm type' webhook.
Event : an event is created on the site related to the alarm.
Variable : a variable is set to 0/1 according to the state of the alarm, respectively NotPresent/Present or is pulsed (1 sec width) if the alarm is acknowledged. This variable must exist, the Alarm engine will not create it.

Here is a sample of a variable notification definition:
```
"notifications": [

      {
          "type": "Variable",
          "value": "123",
          "notifyOnTriggers": [
              "Set",
              "Reset"
          ]
      }
  ]
```
123 is the id of the variable that will be set/reset following the alarm state.

Tip

Learn more about Webhook & Events.

Notifications triggers

A notification is triggered by an alarm's change of state. The different changes of state available are :

Set: the notification will be triggered each time the state of the alarm becomes "present".
Reset: the notification will be triggered each time the state of the alarm becomes "not present".
Ack: the notification will be triggered each time a user acknowledges the current state (present or not present) of the alarm.
Enable: the notification will be triggered each time a user enables the alarm.
Disable: the notification will be triggered each time a user disables the alarm.

Please, note that for variable notification, only the pair (Set and Reset) or Ack triggers are allowed.

Tip

Learn more about How to create notifications

Configure notifications for an alarm

Notifications have the following object model :

"notifications": [
    {
      "type": "Email",
      "target": "User",
      "value": "1234",
      "notifyOnTriggers": [
        "Set"
      ]
    }
    ]

Type

This property can have the following values :

Email
Sms
Webhook
Event
Variable

Target

'Target' will be defined only for Email, Sms notifications.

The value can be :

User: the notification will be sent to a user of the account via the email or phone number registered in his profile (Email and Sms notifications)
Custom: the notification will be sent to the email address or phone number given in the 'value' property (Email and Sms notifications).

Value

'Value' will be defined only for Email, Sms Webhook and Variable notifications.

For Email and Sms, it must be set to either to the User id (if 'User' has been selected as 'target') or to the email address/phone number given (if the 'target' is 'Custom')

For Webhook, it must contain the Webhook Id.

For Variable, it must contain the id of an existing variable that will follow the state of the alarm.

N.B.: To use 'webhook' notification, a webhook with the 'alarm' type has to exist on the current account.

Tip

Learn More about Webhook.

notifyOnTriggers

For each notification, the system needs to know in which cases the notification must be triggered.

That's the role of the property 'notifyOnTriggers'.

In this array, the user can define which changes of state trigger the notification:

Set: when the alarm becomes 'present'
Reset: when the alarm becomes 'not present'
ACK: when the alarm is acknowledged by a user
Enable: when the alarm is enabled by a user
Disable: when the alarm is disabled by a user

Examples of Notifications

"notifications": [
    {
      "type": "Email",
      "target": "User",
      "value": "12345678816",
      "notifyOnTriggers": [
        "Set"
      ]
    },
    {
      "type": "Sms",
      "target": "Custom",
      "value": "+32471111111",
      "notifyOnTriggers": [
        "Set"
      ]
    },
    
    {
      "type": "Webhook",
      "value": "567YTDFII8567",
      "notifyOnTriggers": [
        "Set",
        "ACK"
      ]
    },
    {
      "type": "Event",
      "notifyOnTriggers": [
        "Enable",
        "Disable"
      ]
    },
    {
        "type": "Variable",
         "value": "123",
         "notifyOnTriggers": [
             "Set",
             "Reset"
         ]
     },
     {
        "type": "Variable",
         "value": "456",
         "notifyOnTriggers": [
             "Ack",
         ]
     }

  ]

An alarm with the previous notifications will:

send an email to the user who has the ID '12345678816' each time the alarm becomes present.
send an SMS to the phone number '+32471111111' each time the alarm becomes present or not present.
trigger the webhook with the ID '567YTDFII8567' each time the alarm becomes present or is acknowledged by a user.
trigger the creation of an event (on the site linked to the alarm) each time the alarm is disabled or enabled by a user.
set variable 123 to 1 when the alarm is present and set it to 0 when the alarm is not present
set variable 456 to 1 when the alarm is acknowledged and automatically set it to 0 one second later (the timestamp of the rising edge corresponds to the time of the acknowledgement)

Documentation Center