#7 How To... Implement End-to-End Push Notifications with HCPms and SAP Gateway

[kenichi_unnai]

This is a part of the implementation details of How To... Implement End-to-End Push Notifications with HCPms and SAP Gateway.

Steps to Test

Testing the Push Report

Let's test if your test push message can really create a queue. First thing is to "subscribe" a specific OData collection. Start your REST Client. (This example uses Firefox REST Client)

Set those parameters for the client:

Method - GET

URL - https://<hcmps server>/<your app id>

Headers - X-CSRF-Token = Fetch

          X-SMP-APPCID = <your app connection id on HCPms>

          Content-Type = application/atom+xml; charset=UTF-8

The URL maps to the Service Document of the Gateway service that was configured on HCPms.

As an extra security measure, Gateway services guard against Cross-Site Request Forgery (CSRF) by requiring a Gateway-supplied token in all modifying requests (for example, POST). To retrieve a token, use the GET method to set the header “X-CSRF-TOKEN” with value “Fetch” on one of the given service’s read operations. This also applies when you are accessing the service document.

The service document is shown in the response. Take a look at the various collections (for example, “SubscriptionCollection”).

You can obtain the CSRF token (valid throughout a session) from the Response Headers tab:

Set up the REST Client with the following parameters:

Method - POST

URL - https://<hcmps server>/<your app id>/SubscriptionCollection

Headers - X-CSRF-Token = <the value obtained>

          X-SMP-APPCID = <your app connection id on HCPms>

          Content-Type = application/atom+xml; charset=UTF-8

Body - The XML body contains the payload needed for the subscription request. You can use the sample subscription payload (but be sure to replace the value of deliveryAddress😞

-- test payload --

<?xml version="1.0" encoding="UTF-8"?>

<atom:entry xmlns:atom="http://www.w3.org/2005/Atom">

  <atom:id />

  <atom:title>Subscription for sample user</atom:title>

  <atom:author />

  <atom:updated />

  <atom:content type="application/xml">

    <m:properties xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices">

      <d:deliveryAddress>urn:sap-com:channel:HCPMS_PUSH:db4dcf68-d511-40fd-91f6-88e49e8b1441</d:deliveryAddress>

      <d:collection>FlightCollection</d:collection>

      <d:filter></d:filter>

      <d:select>*</d:select>

      <d:persistNotifications>false</d:persistNotifications>

      <d:changeType>created</d:changeType>

    </m:properties>

  </atom:content>

</atom:entry>

-- test payload --

For the detailed explanation of this payload, have a read at the appendix section, but in a nutshell, here's the format of <d:deliveryAddress>:

urn:sap-com:channel:<HTTP destination of HCPms defined in SM59>:<application connection id of HCPms>

Click Send. A successful request results in an HTTP “201 Created” response.

Run the transaction code SE11. You can verify this in the ABAP table “/IWBEP/D_MGW_SUB”. You should be able to confirm a newly created subscription entry.

Remark> Make sure "SOURCE SYSTEM ID" in the /IWBEP/D_MGW_SUB table equals with "Destination System" value in SPRO path "SAP NetWeaver" > "Gateway Service Enablement" > "Backend OData Channel" > "Connection Settings to SAP NetWeaver Gateway" > "SAP NetWeaver Gateway Settings".

Here you'll find the current setting - and the value of "Destination System" has to be the same with the value of "SOURCE SYSTEM ID" in the table "/IWBEP/D_MGW_SUB". If you don't have the value, create a new one with System Alas = LOCAL and RFC Destination = NONE.

Now you can run the test report /IWBEP/R_MGW_PUSH_TEST in the transaction code SE38!

(Be sure to have the flight service & data exist - the FLIGHT data can be generated via transaction code SE38 with the program name "SAPBC_DATA_GENERATOR".)

Enter the value ID/1. Execute. You won't get neither successful nor error message (unless you debug the code one line by one)... time to check the queue!

Check the queue via the transaction code SBGRFCMON. The queue should be created.

You don't find it? Yes you might not be able to find it. That's because it is created so fast and deleted if the queue was transferred successfully to HCPms. So it is actually a good idea to post a subscription with a wrong value, such as:

--

<d:deliveryAddress>urn:sap-com:channel:DUMMY ENDPOINT</d:deliveryAddress>

--

Note - The DUMMY_ENDPOINT is the value that actually does exists in SM59, but it contains the wrong value (such as the host name doesn't exist). So the queue should be created and be there with the error status messages. In this way you can ensure if the queue is really created or not. You need to make sure the DUMMY_ENDPOINT exists in SM59, otherwise the message doesn't stop at the queue, but only shows up in the Gateway Error Log.

Other useful error log location for troubleshooting:

• Gateway Backend Error Log: tx code /IWBEP/ERROR_LOG


• Gateway Error Log: tx code /IWFND/ERROR_LOG


• Application Log: tx code SLG1 (Object = /IWBEP/* for Backend info, /IWFND/* for Gateway Hub info)
  

Once you confirm the queue is successfully created, let's check how it goes to HCPms side.

Tip - An ABAP report "SRT_ADMIN_CHECK" with a "Check bgrfc configuration" checkbox shows the current status of bgRFC config.

Check the HCPms push log. Go to the log console of HCPms - typically the Mobile Service Cockpit URL is like https://hcpmsadmin-<id>trial.dispatcher.hanatrial.ondemand.com.  Find and click "Logs" icon.

Click on "Log Settings" and change the log level for the Push component with Debug/Enabled. It should be a good idea to disable all the other components so that you can focus on the Push message only.

After you run the push test report and ensure the queue is successfully created and transferred to HCPms, check the log file. You should be able to find log information for Notification, which indicates the pushed messages are coming in and HCPms is communicating with Push Provider.

Check the device for push notification. The push messages shall come in!

Note - If you're so sure that it will work by confirming the HCPms log but the message doesn't come in the device, please be aware of the fact that the subscription should be made with the app connection id, which is currently alive on the device. That means every time an app gets installed after the uninstallation, it registers with a new app connection id. You might forgot this during your active app development cycle.

What's next? If you need the ERP backend in addition to a single Gateway Hub box, wire the Gateway Hub and ERP backend.

#8 How To... Implement End-to-End Push Notifications with HCPms and SAP Gateway

Appendix:

Details of the subscription payload

(Note - formal help document: Subscription Push Scenario - SAP NetWeaver Gateway - SAP Library)

OData services exposed by SAP Gateway are not automatically enabled for subscription. Confirm this by calling the Gateway service document URL and checking the collections that are exposed. A “SubscriptionCollection” indicates that you can subscribe to the collections of a given service. For more information about enabling subscription for a Gateway service, see the SAP help portal.

 

The demo Flight service (RMTSAMPLEFLIGHT) that is included with an SAP Gateway server is enabled for subscriptions out-of-the-box.

 

In general, to subscribe for notifications, the app must send a subscription request that specifies the following:

 

• User (specified in the HTTP header)


• Delivery address


• OData collection


• Select
  


• Change type


• Filter

 

deliveryAddress

 

The delivery address is the location to which the notification is sent from Gateway. The delivery address must use the format:

 

urn:sap-com:channel:<HTTP destination of HCPms>:<application connection id of HCPms>

 

In the sample request, suppose this delivery address is used:

 

<d:deliveryAddress>urn:sap-com:channel:HCPMS_PUSH:db4dcf68-d511-40fd-91f6-88e49e8b1441</d:deliveryAddress>

 

An HTTP destination of type G called “SMP_PUSH” is referenced (defined in tx SM59), followed by the application connection ID given by the HCPms.

 

collection

 

The collection is the name of the business object collection for which the subscription is being created, in this case, “FlightCollection”. The service document of the OData service shows the collections that are available for the service.

 

select

 

The select attribute must follow the OData $select notation. This attribute allows the subscriber to control the notification format by specifying the subset of the business object hierarchy sent along with the notification. Currently only two values are supported:

 

<d:select></d:select> (empty or missing attribute) A short (base) notification without a business object is sent to the subscriber.

<d:select>*</d:select> The complete hierarchy of the business object is sent.

 

changeType

 

The changeType attribute allows you to subscribe to notifications based on a particular operation that is performed in the SAP back end, and must be one of:“created”, “updated”, “failed”, or “deleted”. . For example, to subscribe notifications only for create operations, use a change type of “created”. However, you must also develop application specific handling for sending notifications in the back end based on the subscribed changeType.

 

filter

 

A filter is where the device user can specify whether to subscribe to all business object instances or to only a specific business object instance. Adhere to theOData $filter syntax and combine any fields using only the AND operation. The only filter criteria that SAP Gateway evaluates is business object ID.