Message Alerting in SAP PI/PO: Sending Alerts as Push Notifications to Mobile Device

[vadimklimov]

Intro

Component Based Message Alerting (CBMA) functionality of Advanced Adapter Engine (AAE) of SAP PI/PO is already shipped with alert consumer that can be used to deliver alerts to recipients as e-mail messages. With increased popularity of smart mobile devices in alerting and notification solutions, some organizations experience demand in using alternative channels of alerts delivery and are interested in bringing them to mobile devices. Even though e-mail alerting is still very popular in enterprise IT world, during last few years, one of commonly raised questions in the area of alerting in SAP PI/PO, was feasibility of delivering alerts via SMS. SMS messages are surely more lightweight in comparison to e-mail messages, but large amount of SMS alerts on interface errors may overflow SMS inbox and cause other SMS messages becoming unnoticed among many alerts, unless some kind of SMS sorting and filtering is applied. Moreover, there is even more lightweight technique that is available on many smart devices - push notifications. What if an alert from a SAP PI/PO system is delivered to mobile device as a push notification?

 

Standard shipment of a SAP PI/PO system doesn't deliver functionality to implement this kind of requirement by means of pure customizing, so let me share an option how this can be introduced to a system with minor custom development.

 

It shall be stated upfront that I haven't yet found technical solution fulfilling this requirement, that would not involve intermediate services responsible for processing alert messages and delivering them to mobile device. High-level interaction diagram of involved components of the described solution is depicted on illustration below:



The solution is as following:

• Custom alert consumer is registered for an alert rule in a SAP PO system;


• Custom alert consumer job (which is a Java Scheduler job) is developed, deployed and scheduled for periodic execution in a SAP PO system: a job consumes alerts produced for a registered consumer, suppresses alerts that correspond to the same interface and the same error, and sends requests containing alert notifications to a RESTful service exposed by an external gateway service;


• On a mobile device (in the demo described in this blog, phone), an application provided by a gateway service provider, is installed and a device is registered as a recipient for messages produced by a gateway service.

 

As a result, when an alert is produced by a SAP PO system and is consumed by an alert consumer job, an alert message is sent to a gateway service, which forwards it to a mobile device. Mobile device processes it and renders in a form of push notification.

 

Please note that this mechanism of alert notifications delivery to a recipient is in no way considered as a replacement of e-mail notifications or other alert subscribers. Nature of push notification is delivery of very lightweight information notifications, commonly consisting of very few text lines. In contrast, e-mail messages containing notifications or other alert subscribers / alert aggregation and processing systems (like SAP Solution Manager, if it is used as a central engine for alerts processing) normally handle and deliver more extended version of an alert providing much more details about it. Having written so, I would rather encourage to consider push notifications for alerts as a complementary technique to already existing and commonly used alerting approaches.


 

Remaining part of the blog contains major configuration steps and technical details of solution implementation and a demo.

 

 

Prerequisites: AAE part

CBMA is activated in AAE and appropriate alert rule is configured and enabled. If you need more information on this, you may find decent SCN materials that describe concept, technical details and configuration of CBMA in general and alerts consumption and notifications via e-mails in particular:

• PI Alerting on AAE/AEX written by tihomir.stoyanov2;


• Michal's PI tips: Component-Based Message Alerting and Michal's PI tips: Component based message alerting - API written by michal.krawczyk2;

 

Architecture and configuration of CBMA is also described in SAP Help documentation: Component-Based Message Alerting - Administering Process Integration (PI) - SAP Library.

 

 

Prerequisites: Gateway service part

There are multiple services that are available for individuals and organizations to mediate incoming messages and deliver them as push notifications to various platforms running on mobile devices (and some of them provide services not only for mobile devices, but also for desktops) - here are just a couple of them which are commonly used:

• Pushover - https://pushover.net/;


• Boxcar - Boxcar — the original Push Notifications platform;

Please note that some services require paid subscription, so it is advisable to refer to corresponding provider official materials for more details regarding terms and conditions of their services usage.

 

In the demo below, I'm using gateway service provided by Pushover - some parts of the described job implementation are specific to Pushover API and are not service agnostic (should be adopted if you would like to use another gateway service provider or if you host and run such a service within your organization). Pushover service exposes a REST API (RESTful service), to which registered users can send POST requests over HTTPS. Message transmitted in a request, is then forwarded to a registered device (mobile device running iOS or Android, or desktop). Mobile devices process received message and deliver it to Notification Center software of a device in a form of push notification.

 

An account was registered and an application on behalf of which SAP PO alerts are going to be delivered to a mobile device, was created. For a registered account, Pushover platform generates a random user key, which will be required later on when sending alert notification messages to a gateway service. Similarly, for every created application, Pushover platform generates a random application key (token), which will also be required later on when sending notification messages to a gateway service.

 

 

Prerequisites: Mobile device part

Gateway services may require installation of specific applications on mobile devices in order to enable communication between a gateway service and the device, before messages can be delivered and rendered by the device as push notifications.

 

Corresponding Pushover application was installed on the mobile device used in a demo (iPhone mobile running the latest iOS version).

 

After this was done, when an application was started for a first time, it was logged into the Pushover service using earlier created user account credentials, and device ID was specified. Device may be used later on to subscribe to specific applications or to be explicitly specified as a recipient of a notification when sending notification messages to a gateway service.

 

 

Screenshots below highlight major created objects in Pushover service account, that will be used in a demo:

• User key - masked due to security considerations;


• Application named "SAP", application key - masked due to security considerations;


• Device named "Vadim".

 

 

Register custom alert consumer

Custom alert consumer named "PUSH_NOTIFICATION" was assigned to an alert rule:



 

 

Develop custom alert consumer job

Steps required to develop custom Java Scheduler job, are well described in SAP Help documentation: Creating the Hello Job Definition -  Using Central Development Services - SAP Library.

 

Custom Java Scheduler job named "AlertConsumerPushNotificationJob" was developed. Job logic comprises following steps:

1. Consume alerts from local alerts store of AAE for a specified alert consumer. Job implementation provides two alert consumption methods:
   
   
   
   • Using SOAP service AlertRetrieveAPI_V2 provided by AAE. Alert Engine provides Alerting API exposed as a SOAP service, which can be used to develop custom external consumers, consume alerts and process them in custom specific way. Technical details about usage of this API can be found in SAP Help documentation: Alerting API on Alert Engine - Administering Process Integration (PI) - SAP Library. WSDL service definition of this SOAP service can be retrieved from a SAP PO system at http://<host>:<port>/AlertRetrieveAPI_V2_Service/AlertRetrieveAPIV2ImplBean?wsdl;
   
   
   • Using consumer specific JMS queue jmsqueues/alertingVP/jms/queue/xi/monitoring/alert/<consumer ID> registered in the JMS Provider of AAE. It shall be noted that even if an alert consumer is registered for an alert rule, corresponding JMS queue will only be created automatically when a first alert is generated and is due to delivery to that alert consumer. This means, access to local alerts store JMS queue may fail because corresponding JMS queue is not found, and it may not be necessarily due to an error, but because alerts haven't been produced for that alert consumer yet;
   
   
   
   


2. Parse consumed alerts and retrieve alerts' payload, which is stored in local alerts store in JSON format;


3. Suppress individual alerts in such a way that only one notification is generated for multiple alerts which correspond to the same scenario and are related to the same error. Generally speaking, this step is optional, but was introduced to avoid overflow of the mobile device with push notifications and degraded user experience in case there would be many alerts produced by a SAP PO system due to the same error for same scenarios in a short period of time;


4. Prepare and send requests to a RESTful service exposed by a gateway service. For each notification, individual request containing a reduced, only very basic and minimum set of original alert's attributes, is sent. Extensive documentation on REST API of Pushover gateway service is available at https://pushover.net/api.

 

Following 3rd party libraries where used in implementation and are dependencies for the developed job implementation:

• Google Gson (GitHub - google/gson: A Java serialization library that can convert Java Objects into JSON and back.) - used for conversion of Java objects to / from JSON representation. Alert payload is persisted in local alert store of AAE in JSON format - conversion from original JSON formatted message containing alert payload to Java object was used internally in an alert consumer job in order to further process consumed alerts;


• Jersey (Jersey) - used to enable RESTful client capabilities in an alert consumer job and send notification messages to a RESTful service of a gateway service.

 

Additionally, generation of Java class reflecting structure of JSON message was done using http://www.jsonschema2pojo.org/.

 

Both mentioned alert consumption methods (calling SOAP service and consuming from JMS queue) have advantages and disadvantages - here are few of them:

 

	SOAP	JMS
Authentication	SOAP service consumption requires explicit authentication, which has to be embedded into an alert consumer job logic. In the described demo, basic authentication method support is implemented, user and password required for authentication are exposed as job parameters, which is not secure enough (since they are stored in plain text in job details and can be further retrieved when looking into job parameters of a scheduled job). More complex logic for retrieval of valid authentication credentials can be implemented instead, if required.	JMS Provider and corresponding JMS queue registered in it is accessed using initial context and JNDI lookup. Additional explicit authentication is not required for server-side JNDI clients such as applications running in the same system - for example, for a deployed Java Scheduler job.
Performance	SOAP service internally accesses JMS queue associated with specified alert consumer, and consumes alert messages from it - in other words, it acts as a SOAP wrapper on top of that JMS queue. Thus, very minor extra latency may be expected when using SOAP service in contrast to direct access to JMS queue.	Core  components of local alert store persistence layer are alert consumer specific JMS queues - in this way, alert consumption from JMS queue corresponds to lower level access to local alert store and may result in slightly reduced processing time of alerts consumption logic.
Implementation efforts	Usage of JAX-WS Web Service Client generation wizard from provided WSDL in NWDS simplifies creation of required Java proxy interfaces and classes. Invocation of required SOAP related functionality (like creation of request, calling SOAP service operation, receiving and handling response) is abstracted and simplified.	Some more efforts are required to implement JMS consumer and respective resources cleanup.

 

Mentioned aspects may be relevant or irrelevant in various environments and in application to specific requirements, so an implemented job supports both alert consumption methods and the one who schedules the job may decide which option suit them better.

 

Outcome of all major job steps is reflected in job log. If the job completes successfully, its return code is assigned value "0", if some error occurs during alerts consumption, parsing / suppression and push notifications generation, return code is assigned value "-1". Further details describing error reason can be found in job log.

 

 

Demo

After EAR file containing a custom alert consumer job is successfully deployed to a SAP PO system, we are ready to schedule a job and test its behavior.

 

Corresponding job definition name for which job task is to be scheduled, is "AlertConsumerPushNotificationJob":



Currently following job parameters are valid for this job definition:

 

Job parameter	Description
AlertConsumerMethod	Method that is used to consume alerts from local alerts store. Currently alerts can be consumed using SOAP service (value of the parameter: SOAP) or from a consumer specific JMS queue (value of the parameter: JMS)
AlertConsumer	Alert consumer ID (the one that was used when registering a new consumer in an alert rule)
AlertLanguage	Alert language (for example, EN)
AlertMaximumNumber	Maximum number of consumed alerts from local alerts store. This is used as a safety measure and mechanism preventing potential performance degradation in case extensive amount of alerts has been produced for a specified alert consumer
PushNotificationService	URL of a gateway service to which alert notifications are to be sent. In case of Pushover, following fixed URL exposed by Pushover, is used: https://api.pushover.net/1/messages.json
PushNotificationUser	User key that has been generated by Pushover for a registered user account and that is to be used for authentication of incoming requests containing alert notifications
PushNotificationToken	Application key (token) that has been generated by Pushover for a created application and that is to be used to differentiate incoming requests being produced for different applications. Generally speaking, it is possible to create multiple applications within same Pushover account and use different applications to associate requests with
PushNotificationDevice	Recipient device to which push notifications are to be delivered by Pushover service. If necessary, multiple devices can be specified, separated by a comma. A parameter is optional and can be left blank - if done so, push notifications will be delivered to all devices subscribed for an application for which push notifications are generated
AAEUser	A parameter is only mandatory if SOAP alert consumer method is selected and is a user account to be used for identification when calling SOAP service for alerts consumption. If JMS alert consumer method is used, a parameter can be left blank (it will be ignored by job logic)
AAEPassword	A parameter is only mandatory if SOAP alert consumer method is selected and is a password to be used for authentication when calling SOAP service for alerts consumption. If JMS alert consumer method is used, a parameter can be left blank (it will be ignored by job logic)

 

Below is an example of provided job parameters for a scheduled job task (push notification user key and application token are masked due to security considerations):



 

After a job is scheduled, I produce several errors for one of scenarios which were assigned to an alert rule created earlier for this demo.

 

If a job is executed successfully, then job log will look similarly to the one provided below:



 

Let me also demonstrate some erroneous cases by creating this job task with various combinations of job parameters. If job execution encounters errors, it is worth checking job log first to identify problematic area or step where error occurred - here are few examples of erroneous cases reflection in job log:

• Alert consumer method different from SOAP or JMS was specified in job parameterization:

• When using JMS alert consumer method, alerts consumption failed due to wrong consumer ID was specified (reason for warning and not error log entry in case JMS queue is not found, has been explained earlier):

• When using SOAP alert consumer method, alerts consumption failed due to invalid password was specified for AAE user account in job parameterization:

• Message delivery to a gateway service failed due to invalid Pushover user key and/or invalid application token was specified in job parameterization:

 

In case job executed successfully, after job completed and notification messages reached a gateway service, respective push notifications containing selected alert information, will be delivered and shown in the mobile device:







 

 

Downloads

You can download SAP EAR file that is a bundle containing the described job implementation, and source files from which it was built, from following locations:

• Assembled deployable SAP EAR file that contains application with implementation of the described job, generated used objects (like Java proxy objects of JAX-WS client, Java class used in Java/JSON conversion of alert payload) and dependency libraries: https://github.com/VadimKlimov/PO_AlertConsumerPushNotifications/releases/latest.


• Source code of corresponding EJB and EAR projects: GitHub - VadimKlimov/PO_AlertConsumerPushNotifications: SAP PO: Alert consumer job for push notifica....

 

Projects were built using NWDS 7.31 and compiled using JDK 6. Most recent stable versions of mentioned dependency libraries, which were released and at a time of a blog writing, were embedded into an assembled EAR file.


 

The job was tested in a SAP PO 7.31 SP16 system. This job has only been used and tested in a prototype, and has not been used in productive environment yet.