Event Notifications

Notifications are asynchronous messages sent by Cisco Business Dashboard to notify consumers of events as they occur. Events may relate to managed network devices, or the Cisco Business Dashboard application. Cisco Business Dashboard uses Server-Sent Events (SSEs) to send these notifications. The Server-Sent Events specification defines an EventSource API for opening an HTTP connection for receiving push notifications from a server in the form of DOM events.

Supported Events

Events are defined in a hierarchy. The event type is a string identifying the event by specifying each level of the hierarchy delimited by forward-slash characters (e.g. /state_change/reachability). The following tables list the available events along with the descriptive string contained within the event body.

Device Action

State Change of Devices

Dashboard-specific Events (Login/logout/session)

Device Config Change Events

Available subTypes are:

• system
• ntp
• clock
• dns
• authentication
• vlan
• wlan
• interface

Event Payload Format

The event payload in the SSE data field is of the form:

{
      "event-id": "fe1ba361-53e9-4306-83ff-177f5e75cef4",
      "timestamp": 1552287535000,
      "org-id": "5c4fbe2c2bedca0006523276",
      "network-id": "c931e485-6e04-4a67-9dbf-563414a342f1",
      "node-id": "6ecc88e0-958c-4314-8132-858eda8f9e2a",
      "node-type": "Host",
      "severity": 1, // Alert(0), Warning(1), Info(2), Normal(3)
      "type": "/state_change/credential/SNMP",
      "correlator": null,
      "english-string": "{nodeType} {hostname} SNMP credential changed from {from} to {to} at {time}",
      "parameters": {
        "hostname": "AC:F2:C5:21:BC:40",
        "from": "none",
        "to": "required",
        "time": "2019-02-28T01:47:14Z",
        "nodeType": "Host"
      }
    }

Replaying Events

The SSE specification defines a Last-Event-ID header that may be used to resend or replay past events. If a client loses connection to server, it can reconnect with the Last-Event-ID header set to the last event ID it has received. This will typically be handled by the SSE client library being used. When establishing a new session, a client may also set this header using a stored event ID to trigger an event replay.

Cisco Business Dashboard will only replay events from the last 60 minutes or at most 10,000 events.

Event Source

Client applications need to specify event types and networks of interest. Only events of the specified types and from monitored networks will be sent.

• Method: GET
• Uri: /api/v2/event-source?types=action,config_change,event,state_change&monitored-networks=all
• Parameters:
  • types: comma separated event types, combination of action, config_change, event and state_change, default is combination of all types action,config_change,event,state_change
  • monitored-networks: all or subscribed, default is all
    • all: all networks managed by the user who is the owner of the access key used to sign the JWT
    • subscribed: subscribed networks in another subscribe API call.

Authorization header Authorization: Bearer SIGNED_JWT is also required for this API.

If the SSE client library in use does not support modification of HTTP headers, the authorization information and event ID may be included as query parameters in the URL:

For example:

/api/v2/event-source?token=SIGNED_JWT&last-event-id=5f00a460-642a-4b7c-be14-5a9d92b2ca25

These parameters passed in HTTP headers will take precedence over parameters in URL.

Cisco Business Dashboard will close a client connection when the following cases are detected.

1. The current connection has lasted for more than 24 hours.
2. A heart beat event cannot be sent to client.
3. The JWT has expired.
4. The access key used to sign the JWT has expired or has been removed/disabled.
5. The role or associated organizations of the user who is the owner of the access key used to sign the JWT has been changed.
6. The subscription of monitored networks has been unsubscribed.

For cases #1 or #2, the SSE client will be able to reconnect automatically with Last-Event-ID header set for event replay. For the other cases, the application will need to take some action before reconnecting, such as renewing the JWT, changing the access key or re-subscribing to networks.

Subscribing to Networks

Client applications need to specify which networks should be monitored. Only events from monitored networks will be pushed to the client. There are two types of subscription:

• Implicit subscription: with monitored-networks=all parameter (or no parameter as all is the default when calling the event source API which implicitly subscribes all networks).
• Explicit subscription: call the subscribe API explicitly.

The last call from same client ID will override subscribed monitored networks from a previous call. Cisco Business Dashboard will expire the subscription after 2 hours from when there is no active client connection to the event source.

The recommended sequence of calls is as follows:

• Explicit Subscription:
  1. Generate JWT(exp=now+1hour).
  2. Subscribe to networks.
  3. Connect to event source.
  4. Reconnect each hour until the JWT expires, then return to step 1.
• Implicit Subscription:
  1. Generate JWT(exp=now+1hour).
  2. Connect to event source.
  3. Reconnect each hour until the JWT expires, then return to step 1.

Subscription API:

• Method: POST
• Uri: /api/v2/subscription
• Request Body:

{
    "network-ids": [
        "0b821a4a-5415-4beb-8bb1-7c3c885751f1",
        "9930d4b6-a780-4c50-af66-7a5794927165"
    ]
}

If a client application is no longer interested in the events, it can unsubscribe by calling:

• Method: DELETE
• Uri: /api/v2/subscription

Both implicit subscription and explicit subscription can be unsubscribed. But for implicit subscription, the client application needs to shutdown the connection to event source before unsubscribing, otherwise the SSE client may trigger a reconnect which does an implicit subscription again.

Heartbeat Event

Cisco Business Dashboard will send a heartbeat event to connected clients every 10 minutes to check if the client is alive. If the heartbeat event fails, the Manager will close the connection.

{
    "event-id": "fe1ba361-53e9-4306-83ff-177f5e75cef4",
    "timestamp": 1508810463000,
    "type": "/heart_beat"
}

Event Localization

This request returns a dictionary of localized strings used for event descriptions. The dictionary need only be requested once, but applications should refresh the dictionary if a change in the Dashboard version is detected by calling /api/api-info.

• Method: GET
• Uri: /api/v2/resources/event-strings
• Response Body:

[
    {
        "locale": "en_US",    // "en_US","de_DE","es_ES","fr_FR","ja_JP","zh_CN"
        "event-strings": {
            "action": {
                "backup": {
                    "accept": {
                        "message": "{nodeType} {hostname} backup successfully at {time}",
                        "type": "/action/backup/accept"
                    },
                }
            },
            "state_change": {
                "credential": {
                    "SNMP": {
                        "message": "{nodeType} {hostname} SNMP credential changed from {from} to {to} at {time}",
                        "type": "/Notifications/Credential/SNMP"
                    },
                    "UserID": {
                        "message": "{nodeType} {hostname} user credential changed from {from} to {to} at {time}",
                        "type": "/Notifications/Credential/UserID"
                    }
                },
                "eox": {
                    "message": "{nodeType} {hostname} eox status changed from {from} to {to} at {time}",
                    "type": "/Notifications/EOX"
                },
            }
        },
        "node-type-strings": {
            "IpCamera": "IP Camera",
        },
        "state-change-strings": {
            "active maintenance contract": "active maintenance contract",
        }
    }
]