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?
Except where otherwise noted, content on this site is licensed under the MindSphere Development License Agreement.