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:

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.

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.

{
  "ext": {
    "com.cumulocity.authn": {
      "token": "<base64 encoded credentials>"
    }
  }
}

Request

Name Type Occurs Description
id Integer 1 Id of message, required to match response message�
channel URI 1 Name of channel, required value "/meta/handshake".
ext Object 1 Authentication object passed to handshake. (only over websockets)
version String 1 Bayeux protocol version used by client.
minimumVersion String 0..1 Minimum server-side Bayeux protocol version required by client.
supportedConnectionTypes Array 1 List of connection types supported by client.
advice Object 0..1 Session configuration parameters.

Advice

Name Type Occurs Description
timeout Integer 0..1 Max. time in milliseconds between sending of a connect message and response from server. Overrides server default settings for session. Default value : 5400000, maximum value 7200000
interval Integer 0..1 The time, in milliseconds, that the client must wait between the end of one long poll request and the start of the next. Overrides server default settings for session. When not set server allows for max 10 sec delay between next connect request. Default value : 0

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","callback-polling"],
    "advice":{"timeout":120000,"interval":30000}
  }
]

Response

Name Type Occurs Description
id Integer 1 Id of message passed in request message
channel URI 1 Name of channel, required value "/meta/handshake".
version String 0..1 Bayeux protocol version used by server.
minimumVersion String 0..1 Minimum client-side Bayeux protocol version required by server.
supportedConnectionTypes Array 0..1 Connection types supported by both client and server (i.e., intersection between client and server options).
clientId String 0..1 Unique client ID generated by server.
successful Boolean 1 Result of handshake.
error String 0..1 Handshake failure reason.

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

Name Type Occurs Description
id Integer 1 Id of message, required to match reponse message
channel String 1 Name of channel, required value "/meta/subscribe"
clientId String 1 Unique ID of client received during handshake.
subscription String 1 Name of channel to subscribe to.

Example Request:

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

Response

Name Type Occurs Description
id Integer 1 Id of message passed in request message
channel URI 1 Name of channel, required value "/meta/subscribe".
clientId String 1 Unique ID of client.
subscription String 1 Name of channel.
successful Boolean 1 Result of subscription.
error String 0..1 Subscription failure reason.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "channel": "/meta/subscribe",
    "clientId": "Un1q31d3nt1f13r",
    "subscription": "/alarms/overHeatAlarms",
    "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

Name Type Occurs Description
id Integer 1 Id of message, required to match reponse message
channel URI 1 Name of channel, required value "/meta/unsubscribe".
clientId String 1 Unique client ID received during handshake.
subscription String 1 Name of channel.

Example Request:

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

Response

Name Type Occurs Description
id Integer 1 Id of message passed in request message
channel URI 1 Name of channel, required value "/meta/unsubscribe".
clientId String 1 Unique ID of client.
subscription String 1 Name of subscribed channel.
successful Boolean 1 Result of unsubscription.
error String 0..1 Unsubscription failure reason.

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

Name Type Occurs Description
id Integer 0..1 Id of message, required to match reponse message
channel URI 1 Name of channel, required value "/meta/connect".
clientId String 1 Unique ID of client received during handshake.
connectionType String 1 Selected connection type.
advice Object 0..1 Configuration paramaters for current connect message.

Advice

Name Type Occurs Description
timeout Integer 0..1 Interval between sending of connect message and response from server. Overrides server default settings for current request-response conversation.
interval Integer 0..1 Period above which server will close session, if not received next connect message from client. Overrides server default settings for current request-response conversation.

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

Name Type Occurs Description
id Integer 0..1 Id of message passed in request message
channel URI 1 Name of channel.
clientId String 1 Unique ID of client.
successful Boolean 1 Result of connect.
data Array 1 List of notifications from channel.
error String 0..1 Connect failure reason.

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

Name Type Occurs Description
id Integer 0..1 Id of message, required to match response message
channel URI 1 Name of channel, required value "/meta/disconnect".
clientId String 1 Unique ID of client received during handshake.

Example response :

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

Response

Name Type Occurs Description
id Integer 0..1 Id of message passed in request message
channel URI 1 Name of channel, required value "/meta/disconnect".
successful Boolean 1 Result of disconnect operation.
clientId String 1 Unique ID of client received during handshake.
error String 0..1 Disconnect failure reason.

Example response :

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

Network Traffic

Listening to notifications through long polling generates certain traffic depending on the choice of timeouts. The table below lists the traffic generated by long polling requests with a timeout of one hour and no intervals between requests. The calculation does not include received notifications and session reconnects.

Period Traffic
day 7 kB
week 50 kB
month 210 kB

During handshake or connect, a client can override default server connection settings such as timeout and interval. In case of the long polling transport, a client can change the long poll request duration by passing a timeout value. Longer timeout values reduce the traffic needed for sending request and response messages but can result in a loss of the connection. Clients can also set longer interval values and wait with sending the next connect message after receiving the last response (at the expensive of less interactivity).