Introducing Some Cumulocity IoT Notification 2.0 Enhancements
The release of Notifications 2.0, the new Cumulocity notifications API, beta in 10.13, and subsequent trial availability on eu-latest.cumulocity.com earlier this year, has allowed Cumulocity product management and development to gather some valuable feedback and schedule development of a round of enhancements planned to be released in 10.16.
Currently, still an optional feature in 10.14 & 10.15, as it requires enabling the new Message Service, Notification 2.0 is being rolled out to all hosted environments, with the expectation that it will become a standard feature soon.
Thanks to all who have contributed to this evaluation and provided feedback! This blog post describes some enhancements resulting from your feedback that will be available in the upcoming Cumulocity 10.16 release. We first describe two minor usability enhancements before introducing shared and nonpersistent subscriptions and the new filtering features.
Unsubscribe a Subscriber
One API enhancement that was made in 10.14 is the ability to unsubscribe a subscriber from Notification subscriptions. In normal usage, a subscribing application would simply delete the subscription using the “remove subscription” API. No new notifications would then be captured and persisted, and the application would drain down (by consuming) any remaining stored notifications.
However, in some cases (e.g., development/deployment lifecycle scenarios), an application can be removed without first draining down notifications, so an additional mechanism to “unsubscribe” a notification consumer is required.
In 10.14, this is possible to do both in-band on the Web Socket protocol and via a new REST endpoint. To unsubscribe over the Web Socket, just send an “unsubscribe_subscriber” string back to the WebSocket server instead of a message acknowledgment on a single line (i.e., command string terminated by “\n”).
For out-of-band unsubscribing, the new control endpoint is “/notification2/unsubscribe” and a token for Notifications (created using the Notification 2.0 create token API and which names the subscriber) can be posted to that endpoint, supplying it as a query string “token” argument:
curl -X POST -u <username>:<password> https://<your_cumulocity_domain>/notification2.0/unsubscribe?token="<your-jwt-token>"“Get subscriptions for” Enhancements
With the original “retrieve” Notification 2.0 API, it was possible to get subscriptions on a particular managed object (the “source”) or to get all subscriptions under a tenant. We’ve enhanced this by allowing all subscriptions with a particular “subscription name” to be retrieved. This should help in managing subscriptions on multiple managed objects that feed into the same notification topic — which is a very common use case that uses a single subscription name for the aggregated common topic.
It’s also now possible to retrieve all subscriptions that include a given type filter value by allowing a retrieve of all subscriptions in a context that match a particular string literal in their “type” filter. Please see the 10.16 API preview when it becomes available for details and note that you can now have multiple type filters as described below, here we are just checking for one particular “type” filter value.
Shared Subscriptions for Scale Out
If an application needs to subscribe to a high volume of notifications or if the processing of notifications requires considerable time, then one common approach is to scale the subscribing application or consumer horizontally.
When creating a token for consuming notifications, it is now possible to specify that the consumer will not be exclusive, but that instead consuming will be “shared” between a set of consumers. This is done by creating the token via a REST request that has an extra (and optional, defaulting to false) “shared=true” query parameter.
The number of consumers can then vary as the application instances scale up or down, and notifications will be sent to one or other of the current set of consumers. To aid in this, consumer connections on the WebSocket endpoint should specify a unique consumer name (using another query parameter consumer=). E.g,
wss://<your-environment-or-tenant>/notification2/consumer?token=<jwt-token>&consumer=<the-consumer-instance>The details are given in the User documentation for this feature. One important consideration is the order of notifications from a single source device (or managed object). Notifications will be delivered in-order for any device, but, as consumers start or stop/fail, delivery of notifications from a particular device may switch to another consumer. Providing the above consumer name, on WebSocket connection, to consume notifications helps achieve this. Please see the user documentation messaging reference section for 10.16 for further details when it becomes available.
Non-persistent Subscriptions
To learn about the latest enhancements in more detail, please refer to the original article on the Software AG Tech Community Knowledge Base:
Originally published at https://tech.forums.softwareag.com on October 6, 2022.
