Skip to content

Receiving Insights Hub Notifications

This section describes how to receive the Insights Hub notifications and the notifications on new data arrival.

Currently, to perform any data processing on the time series data as it arrives or new event created, it is necessary to constantly poll the Industrial IoT APIs, identify the latest data, and perform the required operations. This process is not only resource-consuming but also time-consuming, as the time-series data can be queried for a specific asset only. With the Industrial IoT notifications, there is no need to poll the APIs anymore. Instead, an application can be notified by the Industrial IoT on the new data arrival.

This section also explains the requirements that should be considered for receiving the Insights Hub notifications.

How does the Insights Hub send notifications

Insights Hub uses the publish-subscribe messaging pattern where senders of messages, called publishers, do not send notifications to specific receivers, called subscribers, directly. Instead, they categorize the published notifications into classes, called topics, without knowledge of subscribers. Similarly, subscribers express interest in one or more topics and only receive notifications that are of interest, without knowledge of publishers.

Publishers post messages to an intermediary Message Broker, and the subscribers register subscriptions with that broker, by letting the broker perform the notification delivery.

Flow diagram

The Insights Hub topics follow a naming convention: mdsp.core.<publisher>.<topic-version>.<topic-type>.<topic-name>[.<topic-additional-name>]

The list of topics are mentioned here.

The topic name and structure of notifications sent via a topic is described by means of the Async API specification. You can use the Async API Playground to explore the API in a swagger-like manner.

The notification delivery happens via the HTTPs protocol. A subscriber expressing an interest in a topic provides their own HTTPs endpoint that the Message Broker uses to make a REST API call, on every new notification in the topic.

Registering a subscription

The Message Broker maintains all the available topics, subscriptions and implements the routing of the notifications to the subscribers. Every subscription is uniquely identified by:

  • topic name
  • subscriber name
  • subscriber version
  • tenant context

Additionally, every subscription has an associated HTTPs endpoint to deliver notifications to.

A subscription is created via the Message Broker API endpoint:

POST https://gateway.{region}.mindsphere.io/api/messagebroker/v4/subscribers/{subscriber’s name}/versions/{subscriber version}/topics/{topic name}

{
      "uri": {HTTPs endpoint}
}

where,

the subscriber’s name is the name of an application that it is registered with, in the Developer or Operator Cockpit. the subscriber version is the version of an application that it is registered with, in the Developer/Operator Cockpit.

Tenant Context

A subscription is always created in a tenant context. Also, every notification is sent in a tenant context. The Message Broker ensures that notification is only delivered to the subscribers with the same tenant context. While creating a subscription, the Message Broker identifies the tenant context by validating and evaluating the JSON web token passed on with the subscription creation request.

HTTPs Endpoint

To deliver notifications, the Message Broker requires an endpoint to make a REST API call to. The Message Broker accepts only endpoints of applications registered in Insights Hub. On every new notification in a topic, the Message Broker will pass the notification on to the provided endpoint in the payload of the HTTP POST request.

The same endpoint can be used in multiple subscriptions. It is possible to provide the same endpoint while creating subscriptions to different topics and while creating different subscriptions to the same topic, i.e., in different tenant contexts. The latter is the use case where an application hosted by a provider or operator tenant is subscribed to a topic in the providers’ context as well as in the context of every user tenant that has got the application provisioned. For details on how to acquire a token for a user tenant, refer to the Token Management Service.

Please also note that in this case the application must be multi-tenant aware and ensure the tenant separation in the application’s data store and logic. The Message Broker will then deliver notifications with the registered tenant contexts to the same endpoint.

Every notification forwarded to the subscription’s endpoint has attributes pointing to the topic the notification was sent to and the tenant context.

Getting the user tenant details

An application is provisioned to multiple user tenants and should receive notifications for all these tenants. To get the notifications, the application must subscribe to an endpoint in a corresponding user tenant context and so to know the tenants.

There are at least two ways to know the user tenants in runtime:

  • either the application periodically queries the List of all Authorized Users of an Application
  • or the application can subscribe to the topic of the Provisioning Service and get notified on every new tenant provisioned

To find the Async API specification of the Provisioning Service, contact the support team.

Notifications sent by the Industrial IoT Services

Prerequisites

The following prerequisites must be fulfilled:

  • The application should be an API type application, that has application credentials of type Read&Write
  • The application should have the Message Broker to scope mapping done in Developer Cockpit. For more details, refer to "Developer Cockpit" documentation.

General considerations

The following points are to be considered while creating a subscription:

  • The notifications can be delivered to the applications of type API only. If it is required to process the notification in a UI application, for example, to update some UI elements, please refer to Integrating API application to the UI application.
  • The subscriber can be a self-hosted or a Cloud Foundry application. However, the application should already be registered in Insights Hub so that, the provided HTTPs endpoint to deliver notifications follows the Insights Hub URL scheme.
  • The application HTTP endpoint to deliver notifications to, need to follow the Insights Hub URL scheme and so contains a tenant name: https://gateway.{region}.mindsphere.io/api/{application name}-{hosting tenant name}/{application version}/{endpoint}. The tenant name changes while handing over the application from a Developer tenant to an Operator tenant. This requires a developer of the application to not hardcode the payload parameter uri passed to the Message Broker while subscribing to a topic, but to dynamically generate it depending on a tenant hosting the application.
  • A subscription is identified by a tenant context, topic name, subscriber’s name, and version so that, different versions of the same application create independent subscriptions.
  • A subscription is created via the Message Broker API. Similar to any other Industrial IoT API, it is required to pass on a token with every REST API call. Currently, the Message Broker accepts tokens that are issued using the application credentials of type “Read and Write” only. For details on how to access Industrial IoT API, refer Application Credentials.
  • By default, the Industrial IoT services in general and the Message Broker in particular, are unable to make REST API calls to an application’s endpoints unless it is explicitly configured. Without this configuration, the Message Broker will not be able to deliver notifications even if there is a valid subscription. The configuration includes granting the Insights Hub the permissions to make the REST API calls as well as the scope mapping. The scope mapping defines which of the application-defined scopes should be included in the token passed on by the Message Broker while making the REST API call. It is the application’s responsibility to validate the token for every incoming request and check the presence of the configured scopes. For details on how the permission grant and scope mapping can be done in the Developer Cockpit, refer "Developer Cockpit" document.
  • The Message Broker keeps trying to deliver notifications to the provided endpoint until it gets a successful response (HTTP code 2xx) or the message retention period of 4 days expires. If the Message Broker fails to deliver a message within the retention period, the message is dropped and there is no way to retrieve it.
  • The messages can be delivered out of order, especially in cases of failed deliveries, and at least once.

Deleting a subscription

If you no longer wish to receive notifications, you can delete the subscriptions for the relevant events. This can be done by using the Message Broker API. For information, refer to the Message Broker Service.


Last update: January 19, 2024

Except where otherwise noted, content on this site is licensed under the Development License Agreement.