Alerts and Notifications

The Alerts and Notification microservice delivers information when something has been discovered on the node by other microservices, to subscribers. Subscribers can be a system or a person

The process is as follows:

  1. REST APIs, provided for the other microservices, on-box applications and off-box applications are passed to the Alerts and Notifications microservice

  2. The data Alerts and Notifications microservice passes the notifications to the Notifications Handler

  3. The Notifications Handler passes the notifications to the Distribution Co-ordinator based on the severity of the notification, as follows:

    • CRITICAL severity notifications are passed immediately
    • NORMAL severity notifications are passed when the Message Scheduler is set to send the next set of notifications

    Note

    The Message Scheduler functionality is not fully supported

  4. When the Distribution Co-ordinator receives the notifications, it queries the subscriptions to acquire the recipients and recipient channels (the subscribers)

  5. The Distribution Co-ordinator passes the notifications to the relevant channel senders to send the notification to the subscribers

  6. The subscriber receives the notification through their preferred channels, either REST callback or email, as defined in their subscription

This process is illustrated below:

Alerts and Notifications Process

For further sequence diagrams for Alerts and Notifications, refer to the EdgeX Foundry High Level Interaction Diagrams.

Alerts and Notifications Data Model

The following diagram shows the Alerts and Notifications data model:

Alerts and Notifications Data Model

The classes are described in the following table:

Class Description
Subscription Used to describe what to notify the subscriber about, and the channel to use to send the notification. The slug, receiver and channels parameters are mandatory; all other parameters are optional. The subscriptionCategories and subscribedLabels parameters specify which notifications the subscriber wants to receive
Channel Describes the Notification endpoint. This can be REST or EMAIL
Notification Describes the information that has been discovered on the node by other microservices. The slug, sender, category and content parameters are mandatory; all other parameters are optional. The notification initially has a status of NEW, and is persisted. When the sending process starts, the status changes to PROCESSED and the Distribution Co-ordinator queries the subscriptions with the same category and includes the labels to send the notification through the requested channels to the subscribers. If the sending of a notifications fails, it is re-sent until the configurable resend count is reached, at which point the status is changed to ESCALATED. If a notification is escalated, this triggers the escalation process where the notification is sent to the subscription with a slug of ESCALATION
Transmission Groups the records of the sent notifications by Channel. When the sending process is triggered, a corresponding transmission is generated. Each transmission contains the data from both Notification and Subscription

Note

To send a notification to a subscriber, the Subscription and the Notification must have the same category and at least one matching label.

Configuring the Mail Server

The mail server can send email notifications to Gmail or Yahoo mail accounts. The mail server must be configured as described below for each type of email account.

Gmail Accounts

To configure the sign-in security settings, you can use either of the following methods:

  • Enable 2-step verification and use an App Password. IOTech recommends the use of this method. For further information on enabling 2-step verification and App Passwords for a Gmail account, refer to Gmail Help
  • Turn on Less secure app access. IOTech does not recommend this method. For further information on turning less secure app access on, refer to the Google Account Help

The SMTP settings are shown below:

Smtp Host=smtp.gmail.com
Smtp Password=${gmail password or app password}
Smtp Port=587
Smtp Sender=${gmail account}
Smtp Username=${gmail account}

Yahoo Mail Accounts

IOTech recommends that Yahoo mail accounts are configured using an App Password, as described in the Generate third-party pap passwords section of the Help for Yahoo Account.

The SMTP settings are shown below:

Smtp Host=smtp.mail.yahoo.com
Smtp Password=${yahoo password or app password}
Smtp Port=587
Smtp Sender=${yahoo account}
Smtp Username=${yahoo account}

Example Use

Before starting the following examples, complete the following steps:

  1. In a terminal, enter edgexpert up --core-consul --support-notifications
  2. Open a browser
  3. Enter localhost:8500/ui in the Address Bar of the browser
  4. Navigate to the SMTP page for Alerts and Notifications. This can be found at localhost:8500/ui/dc1/kv/edgex/core/1.0/edgex-support-notifications/Smtp/
  5. Configure SMTP for your email, as described above
  6. Save your changes
  7. In a terminal, enter edgexpert restart support-notifications

For further information on the API URLs and schemas, refer to the EdgeX Foundry Alerts and Notifications API documentation.

Using Postman

To use Postman for alerts and notifications, complete the following steps:

  1. Send a POST request to create a subscription, as illustrated below:

    Sending a POST Request Using Postman

    Note

    The receiving REST API and/or EMAIL settings are defined by the user. To emulate a REST channel for testing, the RESTful API used in this example was built locally using Python Flask and the temporary public HTTP URL was created using ngrok. Flask is a lightweight Web Server Gateway Interface (WSGI) web application framework, which helps to create a RESTful web server. ngrok exposes local servers behind Network address translations (NATs) and firewalls to the public internet over secure tunnels to allow the Alerts and Notifications microservice to reach the Flash web server.

    The JSON used to create a new subscription is as follows:

    {
        "name": "create_subscription ",
        "event": [
                    {
                         "listen": "test",
                         "script": {
                                 "id": "2387f67c-0a89-4586-bcbf-230939f05425",
                                 "exec": [
                                        "pm.test(\"Status code is 201\", function () {",
                                        "    pm.response.to.have.status(201);",
                                        "});"
                                 ],
                                 "type": "text/javascript"
                         }
                    }
        ],
        "request": {
                "method": "POST",
                "header": [
                        {
                                "key": "Content-Type",
                                "value": "application/json",
                                "type": "text"
                        }
                ],
                "body": {
                        "mode": "raw",
                        "raw": "{\n    \"slug\": \"sys-admin\",\n    \"receiver\": \"System Administator\",\n    \"subscribedCategories\": [\n        \"HW_HEALTH\"\n    ],\n    \"subscribedLabels\": [\n    \t\"test\",\n    \t\"123\"\n    ],\n    \"channels\": [\n    \t{\n            \"type\": \"REST\",\n            \"url\": \"http://0fd7f734.ngrok.io\"\n        },\n        {\n            \"type\": \"EMAIL\",\n            \"mailAddresses\": [\n                \"my_test@gmail.com\",\n                \"user@example.com\"\n            ]\n        }\n    ]\n}"
                },
                "url": {
                        "raw": "http://{{localhost}}:48060/api/v1/subscription",
                        "protocol": "http",
                        "host": [
                                "{{localhost}}"
                        ],
                        "port": "48060",
                        "path": [
                                "api",
                                "v1",
                                "subscription"
                        ]
                }
        },
        "response": []
    }
    
  2. Create a CRITICAL notification, as illustrated below:

    CRITICAL notification in Postman

    The JSON used to create the CRITICAL notification is as follows:

    {
       "name": "create_notifications",
       "event": [
                {
                        "listen": "test",
                        "script": {
                                "id": "375c3910-bd80-40e4-a938-e07d877a81bc",
                                "exec": [
                                        "pm.test(\"Status code is 202\", function () {",
                                        "    pm.response.to.have.status(202);",
                                        "});"
                                ],
                                "type": "text/javascript"
                        }
                }
        ],
        "request": {
                "method": "POST",
                "header": [
                        {
                                "key": "Content-Type",
                                "value": "application/json",
                                "type": "text"
                        }
                ],
                "body": {
                        "mode": "raw",
                        "raw": "{\n    \"slug\": \"notice-001\",\n    \"sender\": \"System Management\",\n    \"category\": \"HW_HEALTH\",\n    \"severity\": \"CRITICAL\",\n    \"content\": \" This is a test\",\n    \"labels\": [\n    \t\"test\",\n    \t\"123\"\n    ]\n}"
                },
                "url": {
                        "raw": "http://{{localhost}}:48060/api/v1/notification",
                        "protocol": "http",
                        "host": [
                                "{{localhost}}"
                        ],
                        "port": "48060",
                        "path": [
                                "api",
                                "v1",
                                "notification"
                        ]
                }
        },
        "response": []
    }
    

  1. Send GET http://{{localhost}}:48060/api/v1/transmission/slug/{{slugName}}/{{limit}}. In this example, {{slugName}} is notic-001 and {{limit}} is 2

    If the notification is successfully sent, you can see the following:

    • The status in the transmission changes to SENT, as shown in the following illustration:
    SENT status
    • The notification is received in the channel. For example, in the illustration below, a gmail account received the notification:
    Gmail Channel
    • In our example, we used ngrok to verify that the Flash web server received the notification successfully, as illustrated below:
    ngroks verification
If the notification is not successfully sent, it is resent until the status changes to SENT, or until the resend count is reached. If all resend attempts fail, the status changes to TRXESCALATION.

Using Edge Xpert Manager

You can use the Edge Xpert Manager to set up Notifications and Subscriptions, as described in Managing Notifications, Subscriptions and Transmissions.

Several microservices automatically send a POST request to trigger the Alerts and Notifications microservice with a NORMAL notification when something changes.

For example, the following illustration shows that the Random-Float-Device in the Virtual Device Service has been locked; such a change immediately triggers a NORMAL notification:

Locked Random-Float-Device

You can see the notification in the Notifications pane of the Edge Xpert Manager, as illustrated below:

Edge Xpert Manager Notification

Note

The Notification Scheduler is not currently processing NORMAL notifications, so no notification will be sent to subscribers.