Notification Service – Samples for v4.x¶

Mobile Push notifications¶

Registering an application with Notification Service¶

Notification Service provides the functionality for sending push notifications for an application installed on the respective mobile devices. Mobile applications must be registered in FCM (Android or iOS)/APNS (iOS) to receive push notifications.

Either an iOS (sandbox & production) or Android configuration can be chosen for the app. Registration of the mobile app allows the developer to provide necessary push notification provider credentials for the app in Notification Service. App registration in Notification Service is a one-time activity for an app with respect to a tenant.

Here, fcmServerKey is the unique server ID for an application used by FCM to send push notification.

Instructions to provide the APNS related configurations for registering iOS app through this endpoint are given below.

Execute the below command on the PEM file provided by APNS for an iOS app. This will provide apnsSslCertificate and an encrypted APNS app private key to keys_out text file.

openssl pkcs12 -in MyRootCA.p12 -out keys_out.txt

Execute the below command to extract apnsAppPrivateKey from the above generated text file i.e, keys_out.txt to private.txt.

openssl rsa -in keys_out.txt -out private.txt

apnsSslCertificate and apnsAppPrivateKey are used together for App registration in Notification Service.

An application is registered using the following endpoint:

POST /mobileApps

Sample Request for Android mobile application:

{
  "name": "Voith_Service_App",
  "type": "android",
  "android": {
    "fcmServerKey": "serverKey"
  }
}

Sample Request for iOS mobile application:

{
  "name": "Voith_Service_App",
  "type": "ios",
  "ios": {
    "bundleId": "com.your-company.app-name",
    "apnsSslCertificate": "ssl certificate in string format",
    "apnsAppPrivateKey": "private key in string format",
    "production": false
  }
}

OR

{
  "name": "Voith_Service_App",
  "type": "ios",
  "ios": {
    "fcmServerKey": "serverKey"
  }
}

Sample Response:

{
  "id": "59f92744-7bbc-4540-8b78-ee9976befc1a",
  "type": "ios",
  "name": "Voith_Service_App",
  "android": {
    "fcmServerKey": "serverKey"
  },
  "ios": {
    "fcmServerKey": "serverKey",
    "bundleId": "com.your-company.app-name",
    "apnsSslCertificate": "ssl certificate in string format",
    "apnsAppPrivateKey": "private key in string format",
    "production": false
  }
}

The ID generated mobileAppId is referenced further for triggering the notification.

The following operations are also possible with a registered application.

• Fetching all registered apps for a tenant
• Updating a registered mobile app
• Deleting an existing registered mobile app from Notification Service

For more information, refer to Notification Service API Specification.

Registering a mobile device instance¶

A mobile device should be registered in Notification Service with respect to the above created mobile app entity. This can be done from the mobile app as per the convenience of app developers. Developer can provide an option to choose the preferred language of receiving notifications on the device of the user. These endpoints are accessed in accordance with guidelines from Mobile App Enablement. For more information about Mobile App Enablement, refer to Developing Mobile Apps.

When registering a mobile application in Developer Cockpit, select the mdsp:core:nose.mobileappuser role in "Authorization Management" in order to access API’s from the mobile device.

A mobile installation instance is registered using the following endpoint:

POST /mobileApps/{id}/instances

Sample Request:

{
  "deviceModel": "iPhone X",
  "deviceOS": "iOS 10",
  "language": "de",
  "pushNotificationToken": "7abcd558f29d0c1f048083e2134ad8ea4b3d87d8ae9c038b43c132706ff445f0"
}

Sample Response:

{
  "id": "59f92744-7bbc-4540-8b78-ee9976befc1a",
  "deviceModel": "iPhone X",
  "deviceOS": "iOS 10",
  "language": "de",
  "pushNotificationToken": "7abcd558f29d0c1f048083e2134ad8ea4b3d87d8ae9c038b43c132706ff445f0"
}

The ID generated appInstanceIds will be further used for triggering the notification.

The following operations are also possible with a registered mobile device instance.

• Show all registered mobile app instances for a given mobile app
• Edit a specific mobile app instance registration
• Delete a specific mobile app instance registration

For more information, refer to Notification Service API Specification.

Triggering a notification¶

For triggering the prepared notification to specific users or devices, use the following endpoint:

POST/multicastPushNotificationJobs

In the following sample request, the mobileAppId and appInstanceIds created in the previous steps are used. Here, mobileAppId is the ID of the respective mobile app and recipients contains the mobile instance or Email address of the logged in user of the app in device, where push notification should be sent.

Messages can be sent in multiple languages, having English (en) as the default language. The devices will receive the message in their preferred languages, else message will be received in default language (en).

Templates can be used for sending messages, in which case the specific template id can be passed to this API along with specific values for template parameters. If message and template, both are specified, message attribute will be used for sending Push notification.

Sample Request:

{
  "mobileAppId": "59f92744-7bbc-4540-8b78-ee9976befc1a",
  "recipients": {
    "appInstanceIds": [
      "59f92744-7bbc-4540-8b78-ee9976befc1a"
    ],
    "userEmailAddresses": [
      "joe.smith@siemens.com"
    ]
  },
  "message": {
    "title": "{ \"en\": \"Siemens MindSphere October 2019\", \"de\": \"Siemens MindSphere Oktober 2019\"}",
    "text": "{ \"en\": \"Hi there, Welcome to MindSphere!\", \"de\": \"Hallo, Willkommen bei MindSphere!\"}"
  }
}

Sample Response:

{
  "id": "59f92744-7bbc-4540-8b78-ee9976befc1a",
  "status": "queued",
  "startTime": "2017-07-21T17:32:28.000Z"
}

E-mail Notifications¶

Sending e-mail with attachments¶

Notification Service provides the functionality for sending e-mails to a set of target recipients or a broadcast group along with attachments as optional. When using this endpoint, at least one of recipients or broadcastGroup is required to be provided.

The message to be sent in the e-mail can be provided directly through message attribute or passed through a template. When using template, message attribute may not be specified. When creating an e-mail job a message or template is required to be provided. If both attributes are provided, the message attribute is used for sending e-mail.

When an email is sent to recipients listed in broadcastGroup, the recipients are listed under 'bcc' field.

An e-mail with attachments is sent using the following endpoint:

POST/emailNotificationJobs

Sample Request without template:

{
    "subject": "[Status] Machine Data Analysis",  
    "message": "Machine data analysis completed. Analysis report attached with this email.",
    "fromApplication": "MachineMonitor",
    "priority": "Normal",
    "recipients": [ 
      "plantengineer@mdspcustomer.com",
      "plantmanager@mdspcustomer.com"
    ],
    "broadcastGroup": {
      "broadcastType" : "All",
      "subTenantId": "pnlmfg"
    },  
    "sendEncrypted": true
}

The message to be sent in the e-mail can be provided directly through message attribute or passed through a template. When using template, message attribute may not be specified. When creating an e-mail job, a message or template is required to be provided. If both attributes are provided, the message attribute is used for sending email.

Sample Request with template:

{
    "subject": "[Status] Machine Data Analysis",  
    "templateId": "0bff7e7a-cd25-4576-9908-4180ef086174",
    "templateParams": [{"FactoryName": "MachineFactory"}],
    "fromApplication": "MachineMonitor",
    "priority": "Normal",
    "recipients": [ 
      "plantengineer@mdspcustomer.com",
      "plantmanager@mdspcustomer.com"
    ],
    "broadcastGroup": {
      "broadcastType" : "All",
      "subTenantId": "pnlmfg"
    },  
    "sendEncrypted": true
}

Sample Response:

{
  "id": "59f92744-7bbc-4540-8b78-ee9976befc1a",
  "fromApplication": "MachineMonitor",
  "status": "Queued",
  "startTime": "2021-04-21T17:32:28.00"
}

The ID generated id is referenced further to request status of an e-mail job as well as the per recipient status of a dispatched e-mail.

For more information, refer to Notification Service API Specification.

Getting status of an e-mail job¶

The current status of an e-mail job is requested using the following endpoint:

GET/emailNotificationJobs/{id}

Here, the id created in the previous step is used.

Sample Response:

{
  "id": "59f92744-7bbc-4540-8b78-ee9976befc1a",
  "fromApplication": "MachineMonitor",
  "status": "DispatchedWithFailures",
  "startTime": "2021-04-21T17:32:28.00",
  "maliciousAttachments": [
    {
      "filename": "app.pdf",
      "threat": "worm found"
    }
  ]
}

The following statuses are available:

• Queued
• InProgress
• Dispatched
• DispatchedWithFailures
• Failed

The system will set the status dispatchedWithFailures in two cases:

• One or more attachments found infected. In that case, e-mail with message content without attachments is sent to the recipients with a disclaimer.
• Delivery to some of the recipients are failed (including bounced e-mails).

For more information, refer to Notification Service API Specification.

When email is sent to recipients listed in broadcastGroup, the recipients are listed under 'bcc' field.

Getting delivery information of an e-mail job¶

The per recipient status of a dispatched e-mail is requested using the following endpoint:

GET/emailNotificationJobs/{id}/deliveries

Here, the id created in the previous step is used.

Sample Response:

{
  "deliveries": [
    {
      "recipient": "plantengineer@mdspcustomer.com",
      "status": "Failed"
    }
  ],
  "page": {
    "size": 0,
    "totalElements": 0,
    "totalPages": 0,
    "number": 0
  }
}

Getting list of e-mail notification jobs¶

A list of email notification jobs can be requested using the following endpoint:

GET/emailNotificationJobs

This list can be further filtered by providing a filter criteria.

Sample Response:

{
  "emailNotificationJobs": [
    {
      "id": "59f92744-7bbc-4540-8b78-ee9976befc1a",
      "fromApplication": "MachineMonitor",
      "status": "DispatchedWithFailures",
      "startTime": "2021-04-21T17:32:28.00",
      "maliciousAttachments": [
        {
          "filename": "app.pdf",
          "threat": "worm found"
        }
      ]
    }
  ],
  "page": {
    "size": 0,
    "totalElements": 0,
    "totalPages": 0,
    "number": 0
  }
}

The following statuses are available:

• Dispatched
• Failed

Managing e-mail encryption certificates¶

The below endpoint can be used to get a list of email encryption certificates to validate if certificates for all the recipients are available in the system, before sending an encrypted email:

GET/emailEncryptionCertificates

Sample Response:

{
  "emailEncryptionCertificates": [
    {
      "email": "plantengineer@mdspcustomer.com"
    }
  ],
  "page": {
    "size": 0,
    "totalElements": 0,
    "totalPages": 0,
    "number": 0
  }
}

Use the following endpoint to get the encryption certificate for a specific recipient:

GET/emailEncryptionCertificates/{email}

Use the following endpoint to upload a new encryption certificate for a specific recipient:

PUT/emailEncryptionCertificates/{email}

Use the following endpoint to update the encryption certificate for a specific recipient:

PATCH/emailEncryptionCertificates/{email}

Use the following endpoint to delete the encryption certificate for a specific recipient:

DELETE/emailEncryptionCertificates/{email}

Getting bounced recipients¶

The below endpoint can be used to get all the recipients to whom the email delivery failed/bounced:

GET/bouncedRecipients

Sample Response:

{
  "bouncedRecipients": [
    {
      "email": "plantengineer@mdspcustomer.com",
      "blacklistedDate": "2018-12-11"
    }
  ],
  "page": {
    "size": 0,
    "totalElements": 0,
    "totalPages": 0,
    "number": 0
  }
}

The recipients to whom the delivery failed/bounced are added to a blacklist.

Sending e-mail with attachments (Deprecated)¶

Notification Service provides the functionality for sending e-mails to a set of target recipients along with attachments as optional. The only file types supported for e-mail attachments are .pdf, .csv, .json and .zip.

An e-mail with attachments is sent using the following endpoint:

POST /multicastEmailNotificationJobs

Sample Request:

Here, metadata and attachment are formdata properties.

  {
      metadata = { 
      subject: "[Status] Machine Data Analysis",
      message: "Machine data analysis completed. Analysis report attached with this email.",
      fromApplication: "MachineMonitor",
      priority: "Normal",
      recipients: [
      plantengineer@mdspcustomer.com,
      plantmanager@mdspcustomer.com
      ]
    }
  }

attachment = "Multiple Binary Files to be uploaded as attachment"

Sample Response:

{
  "id": "59f67823-5bhc-4780-8b23-ee8876mbtg9a"
}

The ID generated id is referenced further to request status of an e-mail job as well as the per recipient status of a dispatched e-mail.

For more information, refer to Notification Service API Specification.

Getting status of an e-mail job (Deprecated)¶

The current status of an e-mail job is requested using the following endpoint:

GET /multicastEmailNotificationJobs/{id}

Here, the id created in the previous step is used.

Sample Response:

{
  "dispatchStatus": [
    {
      "recipient": "plantengineer@mdspcustomer.com",
      "status": "failed"
    }
  ],
  "page": {
    "size": 0,
    "totalElements": 0,
    "totalPages": 0,
    "number": 0
  }
}

The following statuses are available:

• queued
• dispatched
• dispatchedWithFailures

The system will set the status dispatchedWithFailures in two cases:

• One or more attachments found infected. In that case, e-mail with message content without attachments is sent to the recipients with a disclaimer.
• Delivery to some of the recipients are failed (including bounced e-mails).

For more information, refer to Notification Service API Specification.

Getting delivery information of an e-mail job (Deprecated)¶

The per recipient status of a dispatched e-mail is requested using the following endpoint:

GET/multicastEmailNotificationJobs/{id}/deliveries

Here, the id created in the previous step is used.

Sample Response:

{
  "id": "59f92744-7bbc-4540-8b78-ee9976befc1a",
  "fromApplication": "MachineMonitor",
  "status": "queued",
  "startTime": "2017-07-21T17:32:28.000Z",
  "maliciousAttachments": [
    {
      "filename": "app.pdf",
      "threat": "worm found"
    }
  ]
}

SMS notifications¶

Sending SMS notifications¶

Notification Service provides the functionality for sending SMS notifications to a set of target recipients.

Templates can be used for sending messages, in which case the specific template id can be passed to this API along with specific values for template parameters. If message and template, both are specified, message attribute will be used for sending SMS notification.

An SMS is sent using the following endpoint:

POST /multicastSMSNotificationJobs

Sample Request:

  {
  "message": "Monthly machine data analysis completed.",
  "recipients": [
    "+411xxxxxxx9",
    "+491xxxxxxx9"
  ],
  "fromApplication": "string"
}

Sample Response:

{
  "id": "87e67823-5cha-5783-8b23-re8876m9ch4a"
}

The ID generated id is referenced further to request status of an SMS job as well as the per recipient status of a dispatched SMS.

For more information, refer to Notification Service API Specification.

Getting status of an SMS job¶

The current status of an SMS job is requested using the following endpoint:

GET /multicastSMSNotificationJobs/{id}

Here, the id created in the previous step is used.

Sample Response:

{
  "id": "59f92744-7bbc-4540-8b78-ee9976befc1a",
  "fromApplication": "MachineMonitor",
  "status": "queued",
  "startTime": "2017-07-21T17:32:28.000Z"
}

The following statuses are available:

• queued
• dispatched
• Not Implemented

For more information, refer to Notification Service API Specification.

Getting delivery information of an SMS job¶

The per recipient status of a dispatched SMS is requested using the following endpoint:

GET/ /multicastSMSNotificationJobs/{id}/deliveries

Here, the id created in the previous step is used.

Sample Response:

{
"dispatchStatus": [
{
"recipient": "+491xxxxxxx9",
"status": "dispatched"
},
{
"recipient": "+411xxxxxxx9",
"status": "failed"
}
],
"page": {
"size": 20,
"totalElements": 2,
"totalPages": 1,
"number": 0
}
}

Templates¶

Creating templates¶

Notification Service provides the functionality for using templates to send messages via e-mail, push notification or SMS notification types.

For creating a new template definition, use the following endpoint:

POST/templates

Sample Request:

When creating templates E-mail and SMS type of notifications, the place holders defined in the templates need to be specified as params in the api metadata attribute. Given below is a sample template for reference:

Dear PlantEngineer,
The regular maintenance of the machines is completed for %FactoryName%. Please plan to start the assembly line.
Kind regards,
Maintenance Engineer

Here, FactoryName is the formdata property under the metadata attribute.

Also, a template file needs to be attached under the templateFile attribute.

The maximum size of the e-mail template is limited to 8 MB. However, the e-mail message resulting from the E-mail template along with its attachments is limited by the e-mail size limit, that is, 8 MB.

In case of SMS, the SMS message resulting from the template is limited to maximum size of SMS notification, that is, 1500 bytes.

The supported filetypes for various notifications are listed below:

Templates for e-mail and SMS notification types should follow the model as described in definitions/CreateTemplate. Similarly, for push notification, follow the model available in definitions/PushMessageModel. For more information, refer to Notification Service API Specification.

Sample Response:

{
  "name": "FactoryAlertTemplate",
  "id": "0bff7e7a-cd25-4576-9908-4180ef086174",
  "templateFileName": "FactoryNotificationTemplate.html",
  "params": [
    {
      "FactoryName": "MachineFactory"
    }
  ],
  "type": "Email",
  "eTag": "1"
}

The ID generated id is referenced further to display, update, and delete a template.

Getting list of templates¶

A list of templates can be requested using the following endpoint:

GET/templates

This list can be further filtered by providing a filter criteria.

Sample Response:

{
  "Templates": [
    {
      "name": "FactoryAlertTemplate",
      "id": "0bff7e7a-cd25-4576-9908-4180ef086174",
      "templateFileName": "FactoryNotificationTemplate.html",
      "params": [
        {
          "FactoryName": "MachineFactory"
        }
      ],
      "type": "Email",
      "eTag": "1"
    }
  ],
  "page": {
    "size": 0,
    "totalElements": 0,
    "totalPages": 0,
    "number": 0
  }
}

Managing a template¶

Here, the id generated during the template creation is used.

Details of a specific template is requested using the following endpoint:

GET/templates/{id}

Sample Response:

{
  "name": "FactoryAlertTemplate",
  "id": "0bff7e7a-cd25-4576-9908-4180ef086174",
  "templateFileName": "FactoryNotificationTemplate.html",
  "params": [
    {
      "FactoryName": "MachineFactory"
    }
  ],
  "type": "Email",
  "eTag": "1"
}

An existing template definition can be updated using the following endpoint:

PATCH/templates/{id}

Here, the new template definition file provided with the request overrides the previous definition file.

When updating a template definition, the maximum size limit for e-mail and SMS type notifications must be within the limit as described in Creating templates.

An existing template definition can be deleted using the following endpoint:

DELETE/templates/{id}

It is possible to download an existing template file for review suing the following endpoint:

GET/templates/{id}/file