Real-time notifications

Overview

This section describes the aspects common to all the real-time notifications services of Cumulocity.

Each service has his own subscription channel name format and URL which are described in section Notifications with REST interface documentation. The real-time notifications are available for:

• Real-time statements.
• Inventory.
• Events.
• Measurements.
• Device control.
• Alarms.

The real-time notifications API enables responsive communication from Cumulocity over restricted networks towards clients such as web browser and mobile devices. Clients subscribe to so-called channels to receive messages. These channels are filled by Cumulocity with the output of real-time statements or newly created operations. In addition, particular system channels are used for initial handshake with clients, subscription to channels, removal from channels and connection. As communication mechanism, the Bayeux protocol over HTTPS or WSS is used.

Note that when using long-polling, all PUT/POST requests Accept header should be provided, otherwise an empty response body will be returned.

Info: The long-polling interface is designed as a mechanism for custom applications to poll infrequent events from Cumulocity. The long-polling interface is not designed as a mechanism to stream large data volumes (>100kB/sec) or frequent data (>50 events/sec) out of Cumulocity. The usage of long polling is not supported for such use cases.

Handshake

A real-time notifications client initiates connection negotiation by sending a message to the “/meta/handshake” channel. In response, the client receives a clientId which identifies a conversation and must be passed in every non-handshake request.

When using websockets, a property ‘ext’ containing an authentication object must also be sent. In case of basic authentication the “token” is used with base64 encoded credentials. In case of OAuth authentication the request must have the cookie with the authorization name, holding the access token. Further more the XSRF token must be forwarded as part of the handshake message.

{
  "ext": {
    "com.cumulocity.authn": {
      "token": "<base64 encoded credentials>",
      "tfa": "<tfa token>",
      "xsrfToken": "<xsrf token>",
    },
    "systemOfUnits": "<system of units>"
  }
}

Request

Advice

Example request:

POST /cep/realtime
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: application/json
[
  {
    "channel": "/meta/handshake",
    "ext": {
      "com.cumulocity.authn": {
        "token": "<base64 encoded credentials>"
      }
    }
    "version": "1.0",
    "mininumVersion": "1.0beta",
    "supportedConnectionTypes": ["websocket","long-polling"],
    "advice":{"timeout":120000,"interval":30000}
  }
]

Response

Example of successful response:

HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "channel": "/meta/handshake",
    "version": "1.0",
    "minimumVersion": "1.0",
    "supportedConnectionTypes": ["websocket"],
    "clientId": "Un1q31d3nt1f13r",
    "successful": true
  }
]

Example of failed response:

HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "channel": "/meta/handshake",
    "successful": false,
    "error":"403::Handshake denied"
  }
]

Subscribe

A notification client can send subscribe messages where can specify desired channel to receive output messages from cumulocity server. The client will receive the messages in succeeding connect requests.

The format of channels names is different according to REST api in which the real-time notification service is used. For details go to :

• The Real-time statements
• The Device control

Request

Example Request:

    POST /cep/realtime
    Host: ...
    Authorization: Basic ...
    Content-Length: ...
    Content-Type: application/json
    [
      {
        "channel": "/meta/subscribe",
        "clientId": "Un1q31d3nt1f13r",
        "subscription": "/alarms/<Device ID>"
      }
    ]

Response

Example response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    [
      {
        "channel": "/meta/subscribe",
        "clientId": "Un1q31d3nt1f13r",
        "subscription": "/alarms/<Device ID>",
        "successful": true,
        "error": ""
      }
    ]

Unsubscribe

To stop receiving notifications from a channel, send a message to “/meta/unsubscribe” supplying the proper channel name in the same format as used during subscription.

Request

Example Request:

POST /cep/realtime
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: application/json
[
  {
    "channel": "/meta/unsubscribe",
    "clientId": "Un1q31d3nt1f13r",
    "subscription": "/CepModuleName/CepStatementName"
  }
]

Response

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "channel": "/meta/unsubscribe",
    "clientId": "Un1q31d3nt1f13r",
    "subscription": "/CepModuleName/CepStatementName",
    "successful": true,
    "error": ""
  }
]

Connect

After a Bayeux client has discovered the server’s capabilities with a handshake exchange and subscribed to the desired channels, a connection is established by sending a message to the “/meta/connect” channel. This message may be transported over any of the transports returned by the server in the handshake response. Requests to the connect channel must be immediately repeated after every response to receive the next batch of notifications.

Request

Advice

Example Request :

POST /cep/realtime
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: application/json
[
  {
    "channel": "/meta/connect",
    "clientId": "Un1q31d3nt1f13r",
    "connectionType": "long-polling",
    "advice":{"timeout":1200000,"interval":30000}
  }
]

Response

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "channel": "/cepModuleName/cepStatementName",
    "successful": true,
    "error": "",
    "data": [{
       "id" : "10",
       "self" : "...",
       "creationTime" : "2011-09-06T12:03:27.927+02:00",
       "type" : "com_cumulocity_model_DoorSensorEvent",
       "time" : "2011-09-06T12:03:27.845+02:00",
       "text" : "Door sensor was triggered.",
       "com_othercompany_Extension" : { ... },
       "source":{ "id":"12345", "self": "..." }
    }],
    "clientId": "Un1q31d3nt1f13r"
  },{
    "channel": "/cepModuleName/cepStatementName",
    "successful": true,
    "error": "",
    "data": [{
       "id" : "11",
       "self" : "...",
       "creationTime" : "2011-09-06T12:03:27.927+02:00",
       "type" : "com_cumulocity_model_DoorSensorEvent",
       "time" : "2011-09-06T12:03:27.845+02:00",
       "text" : "Door sensor was triggered.",
       "com_othercompany_Extension" : { ... },
       "source":{ "id":"12345", "self": "..." }
    }],
    "clientId": "Un1q31d3nt1f13r"
  },
  {
    "channel":"/meta/connect",
    "successful":true
  }
]

Disconnect

To stop receiving notifications from all channels and close the conversation, send a message to the “/meta/disconnect” channel.

Request

Example response :

POST /cep/realtime
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: application/json
[
  {
    "channel": "/meta/disconnect",
    "clientId": "Un1q31d3nt1f13r",
  }
]

Response

Example response :

HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "channel": "/meta/disconnect",
    "clientId": "Un1q31d3nt1f13r",
    "successful": true
  }
]