OSGi Events Application Specification

The OSGi Events WebSocket is an event subscription system based on the Bosch IoT Gateway Software WebSockets Server. It is implemented as a WebSocket Application, which contains all the server-side logic.

To use the OSGi Events WebSocket Application connect to the Event Application URI via:

ws://<osgi_host>:<port>/<application_uri>

where <application_uri> can be:

• remote/events for JSON-RPC subscriptions
• m2m/re/subscriptions for REST subscriptions

Subscribing and Unsubscribing with Message

To subscribe for additional events, a text messages contain a JSON Object can be used. The JSON Object contains:

• A mandatory command property.
• An optional userkey property. When you include it, the response from the server will include the userkey you sent so that you can match it with your subscription.
• Optional additional properties which can be different for every command.

Every property must be in lower-case.

The OSGi Events WebSocket Application supports Subscribe and Unsubscribe.

The Subscribing and Unsubscribing with Message approach is recommended over the Legacy Subscribing with URI approach.

Subscribe

The subscription format is as follows:

• command:subscribe – the subscription command;
• userkey:someKey – the optional userkey;
• params:... – the parameters of the subscription command which can be:
  1. A single String object which will be the topic. The subscription is for a single topic, without a filter – params:someTopic
  2. An array which contains only String objects which are the multiple topics. The subscription is for multiple topics, without a filter – params:[topicOne, topicTwo, topicThree,..., topicN]
  3. A JSON Object which contains:
     • a topic or topics property matched with its value which can be either a single String object or an array containing multiple topics;
     • an optional filter property matched with its value.
  4. A JSON Array which contains one or more JSON Objects which follow the format above contains:
     • Every JSON Object in the JSON Array represents a single subscription, thus multiple subscriptions with one command are allowed;
     • The format is as follows: params:[{topic:someTopic, filter:someFilter},{topic:[topicOne, topicTwo, topicThree,..., topicN],filter:anotherFilter},...,{topic:additionalTopic}].
• Error – if an error occurs during the subscription parsing the events application will attempt to send a subscription error message, with the error and userkey, before closing the connection – {errmsg:someErrorThatOccurred, errcode:4xxx, userkey:someKey};
• Success – if a subscription is successful a message with the subscription ID and your userkey will be sent – {subid:someSubId, userkey:someKey}.

Single topic subscription without a filter:

//Without userkey
{ "command": "subscribe",  "params": "someTopic"}
//With userkey
{ "command": "subscribe",  "userKey": "someKey",  "params": "someTopic"}

Multiple topic subscription without a filter:

//Without userkey
{ "command": "subscribe",  "params":[ "topicOne",  "topicTwo",  "topicThree"]}
//With userkey
{ "command": "subscribe",  "userKey": "someKey",  "params":[ "topicOne",  "topicTwo",  "topicThree"]}

One or more topic(s) with or without a filter:

//Every JSON object in the params array contains information for one subscription. It can have one or more topic(s) and one optional filter
//Without userkey
{ "command": "subscribe",  "params":[{ "filter": "oneFilter",  "topic": "oneTopic"}, { "filter": "oneFilter",  "topic":[ "one",  "two",  "three"]}, { "topic": [ "four",  "five"]}]}
//With userkey
{ "command": "subscribe",  "userKey": "someKey",  "params":[{ "filter": "oneFilter",  "topic": "oneTopic"}, { "filter": "oneFilter",  "topic":[ "one",  "two",  "three"]}, { "topic": [ "four",  "five"]}]}

Unsubscribe

The unsubscribe format is as follows:

• command:unsubscribe – the unsubscription command;
• userkey:someKey – the optional userkey;
• params:subscriptionid – a String containing one or more id's you want to unsubscribe from.

Once you send the unsubscribe command you will get a response from the server with the successful and unsuccessful cancellations.

Subscription cancelling:

//Single subscription cancelling
{ "command": "unsubscribe",  "userkey": "someKey",  "params": "someId"}
//Multiple subscriptions cancelling
{ "command": "unsubscribe",  "userkey": "someKey",  "params":[ "idOne",  "idTwo",  "idThree",  "idFour",  "idFive"]}

Response after cancelling subscription:

//Here subscriptions with idOne, idThree and idFive have been cancelled successfully while subscription with idTwo and idFour have failed
{ "unsuccessful":[ "idTwo", "idFour"], "successful":[ "idOne", "idThree", "idFive"], "userkey": "someKey"}

Additionally if you have subscribed with an URI, you can unsubscribe easily by putting first as the params value:

Unsubscribing from the first subscription made from the URI:

{"command": "unsubscribe",  "params": "first"}

Subscribing with URI (Deprecated)

This approach is deprecated, so Subscribing and Unsubscribing with Message approach described above is the recommended one.

To subscribe for events provide the subscription information after the application URI, which can be:

• An URI following the subscription URI which represents a single topic:
  • for a single topic only:

    ws://<osgi_host>:<port>/<application_uri>/<event-topic>

  • for a single topic with a filter:

    ws://<osgi_host>:<port>/<application_uri>/<event-topic>/?filter=<event-filter>

• A Query String, which contains the topic(s) and/or filter as fields. The value is connected to the field by an equality sign (=). Different fields are separated by an ampersand (&). The format is:
  • topic or topics separated by a comma (,)
  • filter (multiple filters are not allowed):

    ws://<osgi_host>:<port>/<application_uri>/?filter=<event-filter>&topic=someTopic

    ws://<osgi_host>:<port>/<application_uri>/?topics=<event-topic1>,<event-topic2>,<event-topic3>&filter=<event-filter>

    ws://<osgi_host>:<port>/<application_uri>/?topics=<event-topic1>,<event-topic2>

• A JSON Object or Array which contains the topic(s) and/or filter as properties
  • A JSON Object which contains:
    • A topic or topics property matched with its value which can be either a single String object, which is the topic or an array containing multiple topics
    • An optional filter property matched with its value
  • A JSON Array which contains one or more JSON Objects which follow the format above contain:
    • Every JSON Object in the JSON Array represents a single subscription, thus multiple subscriptions with one command are allowed and contains a topic or topics property matched with its value which can be either a single String object, which is the topic or an array containing multiple topics
    • The format is as follows: [{topic:someTopic, filter:someFilter},{topic:[topicOne, topicTwo, topicThree,..., topicN],filter:anotherFilter},...,{topic:additionalTopic}]

Error Codes

If the events protocol is not followed the webSocket connection will be closed. When the webSocket connection is closed, a closeFrame will be sent with a code and a reason. The following codes are defined for the events subprotocol:

Remote Events Push Notifications via WebSockets

For the new WebSocket/HTTP implementation the support for push notifications via WebSockets is provided by the following bundles and KitMan scripts:

All of the above mentioned KitMan Scripts work both with the default and the legacy HTTP Service / Websockets implementations, as they contain the new and the old Push Events Websocket bundles.