Skip to content

Notification Service

Idea

The goal of digitalization is the efficient and rapid exchange of information. Lots of valuable information/data are generated using MindSphere like analytics, events, etc. These need to be transported quickly to your customers so that they can react quickly based on the information type.

The notification service provides various interfaces (channels) to communicate and share information among the users of MindSphere via

  • E-Mail
  • Push notification
  • SMS

Access

  • The Notification Service API is only available in developer or operator tenants.
  • Third Party Applications can implement Notification Services via a Technical User only. Notification Service specific roles/groups will not be explicitly available in Developer Cockpit Application for Third Party App implementation.
  • Kindly contact the support team in order to generate a new Technical User.

For accessing this service you need to have the respective roles listed in Notification Service roles and scopes.

Basics

The notification service uses different controllers for the communication and information transmission. Each controller offers various tasks for message processing. The following list describes the content of each individual controller:

  • Communication Channel
    This resource gives information about available communication channels. It gets a list of all active communication types with the channel ID and the channel name such as e-mail and push notifications.
  • Address Type
    This resource lists all address types supported by recipient service such as personal mail, office mail or push notification.
  • Recipient
    With this API controller, you can create a new recipient using the e-mail and phone details and manage the accounts by using an API call. You can execute a search by recipient name and get a recipient based on the recipient ID. Thymeleaf is used as an HTML template engine. Hence, templates are expected to use thymeleaf tags.
  • Certificate Store
    The Certificate Store controller manages the recipient's certification system. You can update, check, retrieve and delete a recipient's certificate.
  • Template Param
    This resource gives information about template parameters. You can use this API to get available template parameters for a requested template set.
  • Template Manager
    The Template Manager allows you to use templates for sending messages such as e-mail and push notification. You can also merge template parameters in an existing template. Via the API you can get a list of available templates and view the template details and the contents. Each template has an ID.
  • Communication Category
    The Communication Category controller manages the communication categories. Every category has an ID. You can create and delete the categories. The communication category controller allows you to manage your recipients into different categories. You can also unsubscribe the recipients from a category. For example, a technical support can create a category using recipients and template to define one communication category.
  • Encryption Service
    The encryption service controller encrypts the CcMail, e-mail and plain text. If any of the recipients for a triggered message does not have the respective certificate, the e-mail notification is sent as unencrypted to all the recipients. PGP or S/MIME encrypted e-mails are signed with noreply@mindsphere.io. Users can download the public key of the PGP certificate from https://pgp.mit.edu/ for installing it in their e-mail client.
  • Message Publisher
    The Message Publisher controller is the basic component of the notification service. It publishes the messages to the queue for further processing and routing to the appropriate channel.
  • Communication Service Audit
    The Communication Service Audit controller saves the message in a database and logs the message information in an audit file. You can use the API to search for the stored audits in the database. The messages are stored with an audit log which would be available up to three months.

Features

The Notification Service exposes its API for realizing the following tasks:

  • Digital Certificate Management: Upload/update/delete public certificates for the e-mail encryption.
  • HTML template management: Use pre-defined HTML templates for the e-mail notifications. Upload different HTML templates and reuse them for the different notification channels.
  • Configuration: Configure HTML template and recipient or recipient group. Use a unique configuration name for the target audience and reuse the configuration.
  • Security: Use different e-mail encryption mechanisms, e.g. PGP or S/MIME. Encrypt the messages using different public certificate type of the intended recipients.
  • Audit logs: Trace the history of the sent notifications via audit log.

Limitations & Restrictions

  • E-mail and Push notifications shall not be used for time sensitive applications as MindSphere does not own the total chain of communication.
  • PGP encryption works only for plain text e-mails. E-mails using a pre-defined HTML template would not work correctly as it will display HTML tags after the decryption rather than rendering the HTML tags.
  • Customers/developers are responsible for the management of their public certificates like expiration of the certificates, replacement of the expired certificates etc. Notification Service will send encrypted e-mails with the expired certificate. However, the actual recipients will not be able to decrypt the e-mail using the expired certificate.
  • An invalid e-mail address is blacklisted immediately after the first bounce event (refusal). The tenant cannot send further e-mails to blacklisted e-mail addresses.
    If a tenant sends 10 e-mails to invalid addresses within up to 7 days, a warning e-mail is sent to the tenant admins. If the tenant continues to send e-mails to invalid e-mail addresses and the bounce rate of the tenant exceeds 5%, its capability to send e-mails using the Notification Service is disabled. In this case, a tenant admin must contact the MindSphere support.

    Note

    The bounced e-mails are counted as sent from the tenant's account.

  • The maximum number of recipients per e-mail is 50. A recipient is any e-mail address listed in "To", "CC", or "BCC".

  • E-mails exceeding 250 kB must use a template.

Example Scenario

The manager of a wind farm wants to trigger a push notification every time the wind speed exceeds a certain level.

The manager uses the API and connects the notification service with the aspect data of the wind turbine. At a wind speed of 8 km/h, the administrator of the wind turbine receives a notification. At a wind speed of 9 km/h, an additional notification is sent to a pre-defined service user list for further action.

Any questions left?

Ask the community


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