MindSphere provides many functionalities to generate lots of valuable information. Often, these need to be transported quickly to operators or customers so they can react in time.
The Notification Service provides interfaces to communicate and share information among the users of MindSphere via e-mail, push notification or SMS.
- The Notification Service API is only available in developer or operator tenants.
- The Notification Service API can only be accessed by third party applications using a technical authorization token. Use the Token Management Service for fetching this access token. Note that the
usertenantmust be set to whichever tenant the application runs on.
The Token Management Service is currently only available in region Europe 1.
In region Europe 2, contact the support team as only they can generate a technical user for your application.
Notification Service specific roles/groups will not be explicitly available in Developer Cockpit Application for Third Party App implementation.
For accessing this service you need to have the respective roles listed in Notification Service roles and scopes.
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.
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 firstname.lastname@example.org. 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.
The Notification Service exposes its API for realizing the following tasks:
- Digital Certificate Management: Upload/update/delete public certificates for the e-mail encryption. Expired certificates cannot be uploaded. After a certificate has expired, e-mails are sent without encryption until a valid certificate has been uploaded again.
- 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.
- Broadcast feature for e-mail channel: Send unecrypted e-mails (BCCed) to all users of the tenant.
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.
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.
- Broadcast feature for e-mails is not supported for subtenant users yet.
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?
Except where otherwise noted, content on this site is licensed under the MindSphere Development License Agreement.