Skip to content

Receiving MindSphere Notifications

This section describes how to receive the MindSphere 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 MindSphere 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 MindSphere notifications, there is no need to poll the APIs anymore. Instead, an application can be notified by the MindSphere on the new data arrival.

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

How does the MindSphere send notifications

MindSphere 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 MindSphere topics follow a naming convention: mdsp.core.<publisher>.<topic-version>.<topic-type>.<topic-name>[.<topic-additional-name>]

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 MindSphere Message Broker uses to make a REST API call, on every new notification in the topic.

Registering a subscription

The MindSphere 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:

1
2
3
4
5
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 MindSphere Developer or Operator Cockpit. the subscriber version is the version of an application that it is registered with, in the MindSphere 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 the MindSphere. 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 MindSphere 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 MindSphere so that, the provided HTTPs endpoint to deliver notifications follows the MindSphere URL scheme.
  • The application HTTP endpoint to deliver notifications to, need to follow the MindSphere 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 MindSphere 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 MindSphere API, refer Application Credentials.
  • By default, the MindSphere 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 MindSphere 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 MindSphere 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

Any questions left?

Ask the community


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