Notifications

Summary

Notifications are the main way for integrations and systems to send messages to users. It can be used to send alarm-messages, notify users of recent changes in values and other data. Notifications should bridge the automation part of systems with alerting users of potential problems.

To allow dynamic messages and deliver them to different systems Lynx supports templating the text and deliver it to 3:rd party integrations. IoT Open delivers some integrations as standard.

Architecture

The notifications consist of several parts that come together to form a chain of actions to deliver the message to the user. There are three main parts, message template, executor and output each described more in depth below.

This picture illustrates the connection between the different parts to form the message to the user.

This image is an example of expected flow for users or systems to create a new notification.

Executor

Executors are the integration point where Lynx have a standard way of delivering notifications to external partners. They are run as a separate programs that can be extended or updated at will. Each executor receives a POST request from Lynx with the formatted message and other parameters set by the user. Parameters usually include who the recipient is, who is sending the message, a header and other data.

IoT Open provides some executors described here.

Example POST request

This is the JSON data sent by the post request when an output send is used. Both message and all output_config values uses the template variable substitution before the data is sent to the executor.

The executor can optionally be configured to include the X-API-Key for authentication. It is up to the executor implementation to verify the header. The content type will also be set to application/json.

{
  "message": "The installation called 'My Home' is reporting an error.",
  "output_config": {
    "key-1": "value-1",
    "key-2": "value-2"
  },
  "executor_config": {
    "key-1": "value-1",
    "key-2": "value-2"
  },
  "organization": {
    "id": 0,
    "name": "string",
    "address": {
      "address": "string",
      "city": "string",
      "country": "string",
      "zip": "string"
    },
    "email": "string",
    "phone": "string",
    "force_sms_login": false,
    "parent": 0,
    "children": {
      "name": "string",
      "id": 0
    },
    "notes": "string"
  },
  "installation": {
    "id": 1,
    "name": "First installation",
    "client_id": 1,
    "organization_id": 1,
    "capabilities": [
      "string"
    ]
  },
  "payload": {
    "some_key": "some_value",
    "other_key": 5
  }
}

Message Template

To allow messages to be dynamically generated we support templating of the message. Each template can also be used in several outputs. This allows a single template to be used for multiple alarms to different people.

A more detailed description on how templates work can be found here.

Output

An output is the combining link between a message, an executor and some extra configuration options. The output configuration have config parameters, an example is SMS output uses receivers as a comma separated list of phone numbers to send the message to. Outputs for email uses subject and receivers fields. All config variables in the output can also use the templating language to create dynamic text values.