Notification Service¶

Idea¶

Insights Hub provides many functionalities to generate lots of valuable information. Often, these need to be transported quickly to operators or customers so that they can react in time.

The Notification Service provides interfaces to communicate and share information among the users of Insights Hub via e-mail, push notification or SMS. Notification Service enables the functionality for using templates to send messages via these notification types. E-mails can be supported with attachments as an optional feature.

Access¶

• The Notification Service API can only be accessed by third-party applications using a technical authorization token issued by the Token Management Service. Note that the hosttenant and the usertenant must be set to the tenant the application runs on.

• Notification Service specific roles/groups listed in Notification Service roles and scopes are not explicitly available except mdsp:core:nose.mobileappuser role, which is available in authorization management of Developer Cockpit .

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 SMS, 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 a unique ID, which is used to update, delete, obtain details of the template.
• 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. Expired certificates cannot be uploaded. After a certificate has expired, e-mails are sent without encryption until a valid certificate has been uploaded again.
• Template management: Use pre-defined templates for SMS, push notifications, e-mail notification types.
• 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.
• SMS Notifications: Send SMS notifications to a set of target recipients.
• Broadcast feature for e-mail channel: Send unencrypted e-mails (BCCed) to all users of a tenant including subtenant users or to a specific user group.
• Push Notification: Mobile applications (Android or iOS) must be registered in FCM/APNS to receive push notifications.
• E-mail attachment: Send e-mails to a set of target recipients along with attachments as optional.

Limitations & Restrictions¶

• E-mail, SMS and Push notifications shall not be used for time sensitive applications as Insights Hub does not own the total chain of communication.
• E-mail addresses for deliveries and templates are treated case insensitively and converted to lower case.
• 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 support team.

• The service may decide to throttle API requests temporarily returning a 429 status code.

  Note

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

• Only .pdf, .csv, .json and .zip file types are supported for e-mail attachments. The number of attachments per e-mail is limited to a maximum of 5 files, wherein the total size of all attachments must not exceed 8 MB. This limit is also applicable for an e-mail message (along with its attachments) resulting from a template.

• The e-mail attachments are scanned in accordance with the security standards. If one or more attachments are found infected, all the attachments will be removed from the mail. However, the mail with message content will be sent to the recipients with a disclaimer in the footer stating the same.
• Depending on the file types and size of the attachments, the scanning can result in a delivery delay of a few minutes because it analyzes each attachment against potential threats.
• The maximum number of recipients per e-mail is 50. A recipient is any e-mail address listed in "To", "Cc", or "Bcc". However, a broadcast group is considered as a single recipient and there is no limit for the maximum number of recipients.
• E-mails exceeding 250 kB must use a template.
• The supported file types for templates are the following:

• Maximum of 3 device instances can be added for a user (token email address) of a tenant.
• Information about the email job deliveries can only be retrieved up to 180 days from the creation of the email job. After this period, it will be automatically deleted from the system.
• The maximum number of recipients per SMS is 50.

• The SMS messages are scanned for any vulnerabilities in accordance with the security standards before dispatching. If an SMS is found infected, it will not be sent to any of the recipients and the operator receives a 400 status code.
• A single SMS message can contain up to 140 bytes of information wherein the character quota depends on the encoding scheme. If the SMS size exceeds 140 bytes, it will be split into multiple messages and sent. When message is split into multiple messages, each partial message will be billed as a single unit.
• Maximum size limit for an SMS is 1500 bytes. This limit is also applicable for an SMS message resulting from 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.