Skip to content

Notification Service – Samples for v4.x

Sending 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 registeration in Notification Service.

An application is registered using the following endpoint:

1
POST /mobileApps

Sample Request for Android mobile application:

1
2
3
4
5
6
7
{
  "name": "Voith_Service_App",
  "type": "android",
  "android": {
    "fcmServerKey": "serverKey"
  }
}

Sample Request for iOS mobile aaplication:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "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

1
2
3
4
5
6
7
{
  "name": "Voith_Service_App",
  "type": "ios",
  "ios": {
    "fcmServerKey": "serverKey"
  }
}

Sample Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "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 for MindSphere.

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:

1
POST /mobileApps/{id}/instances

Sample Request:

1
2
3
4
5
6
{
  "deviceModel": "iPhone X",
  "deviceOS": "iOS 10",
  "language": "de",
  "pushNotificationToken": "7abcd558f29d0c1f048083e2134ad8ea4b3d87d8ae9c038b43c132706ff445f0"
}

Sample Response:

1
2
3
4
5
6
7
{
  "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:

1
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).

Sample Request:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "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:

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

E-mail with attachments

Sending e-mail with attachments

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:

1
POST /multicastEmailNotificationJobs

Sample Request:

Here, metadata and attachment are formdata properties.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
  { 
    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:

1
2
3
{
  "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

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

1
GET /multicastEmailNotificationJobs/{id}

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

Sample Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "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

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

1
GET/multicastEmailNotificationJobs/{id}/deliveries

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

Sample Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "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.

An SMS is sent using the following endpoint:

1
POST /multicastSMSNotificationJobs

Sample Request:

1
2
3
4
5
6
7
8
  {
  "message": "Monthly machine data analysis completed.",
  "recipients": [
    "+411xxxxxxx9",
    "+911xxxxxxx9"
  ],
  "fromApplication": "string"
}

Sample Response:

1
2
3
{
  "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:

1
GET /multicastSMSNotificationJobs/{id}

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

Sample Response:

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

The following statuses are available:

  • queued
  • dispatched

For more information, refer to Notification Service API Specification.

Getting delivery information of an e-mail job

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

1
GET/ /multicastSMSNotificationJobs/{id}/deliveries

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

Sample Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
"dispatchStatus": [
{
"recipient": "+911xxxxxxx9",
"status": "dispatched"
},
{
"recipient": "+411xxxxxxx9",
"status": "failed"
}
],
"page": {
"size": 20,
"totalElements": 2,
"totalPages": 1,
"number": 0
}
}

Any questions left?

Ask the community

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