SAP How-to Guide Mobile Technology
Sybase Unwired Platform
SAP NetWeaver Gateway
Applicable Releases:
Sybase Unwired Platform 2.1.1
SAP NetWeaver Gateway 2.0
Version 1.0
February 2012
How-To…Subscription & Notification with SAP NetWeaver Gateway - Android + Code Sample
© Copyright 2012 SAP AG. All rights reserved. No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP AG. The information contained herein may be changed without prior notice. Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors. Microsoft, Windows, Excel, Outlook, and PowerPoint are registered trademarks of Microsoft Corporation. IBM, DB2, DB2 Universal Database, System i, System i5, System p, System p5, System x, System z, System z10, System z9, z10, z9, iSeries, pSeries, xSeries, zSeries, eServer, z/VM, z/OS, i5/OS, S/390, OS/390, OS/400, AS/400, S/390 Parallel Enterprise Server, PowerVM, Power Architecture, POWER6+, POWER6, POWER5+, POWER5, POWER, OpenPower, PowerPC, BatchPipes, BladeCenter, System Storage, GPFS, HACMP, RETAIN, DB2 Connect, RACF, Redbooks, OS/2, Parallel Sysplex, MVS/ESA, AIX, Intelligent Miner, WebSphere, Netfinity, Tivoli and Informix are
trademarks or registered trademarks of IBM Corporation. Linux is the registered trademark of Linus Torvalds in the U.S. and other countries. Adobe, the Adobe logo, Acrobat, PostScript, and Reader are either trademarks or registered trademarks of Adobe Systems Incorporated in the United States and/or other countries. Oracle is a registered trademark of Oracle Corporation. UNIX, X/Open, OSF/1, and Motif are registered trademarks of the Open Group. Citrix, ICA, Program Neighborhood, MetaFrame, WinFrame, VideoFrame, and MultiWin are trademarks or registered trademarks of Citrix Systems, Inc. HTML, XML, XHTML and W3C are trademarks or registered trademarks of W3C®, World Wide Web Consortium, Massachusetts Institute of Technology. Java is a registered trademark of Sun Microsystems, Inc. JavaScript is a registered trademark of Sun Microsystems, Inc., used under license for technology invented and implemented by Netscape. SAP, R/3, SAP NetWeaver, Duet, PartnerEdge, ByDesign, SAP BusinessObjects Explorer, StreamWork, and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and other countries.
Business Objects and the Business Objects logo, BusinessObjects, Crystal
Reports, Crystal Decisions, Web Intelligence, Xcelsius, and other Business
Objects products and services mentioned herein as well as their respective
logos are trademarks or registered trademarks of Business Objects Software
Ltd. Business Objects is an SAP company.
All other product and service names mentioned are the trademarks of their respective companies. Data contained in this document serves informational purposes only. National product specifications may vary. The information in this document is proprietary to SAP. No part of this document may be reproduced, copied, or transmitted in any form or for any purpose without the express prior written permission of SAP AG. This document is a preliminary version and not subject to your license agreement or any other agreement with SAP. This document contains only intended strategies, developments, and functionalities of the SAP® product and is not intended to be binding upon SAP to any particular course of business, product strategy, and/or development. Please note that this document is subject to change and may be changed by SAP at any time without notice. SAP assumes no responsibility for errors or omissions in this document. SAP does not warrant the accuracy or completeness of the information, text, graphics, links, or other items contained within this material. This document is provided without a warranty of any kind, either express or implied, including but not limited to the implied warranties of merchantability, fitness for a particular purpose, or non-‐infringement. SAP shall have no liability for damages of any kind including without limitation direct, special, indirect, or consequential damages that may result from the use of these materials. This limitation shall not apply in cases of intent or gross negligence. The statutory liability for personal injury and defective products is not affected. SAP has no control over the information that you may access through the use of hot links contained in these materials and does not endorse your use of third-‐party Web pages nor provide any warranty whatsoever relating to third-‐party Web pages.
SAP “How-‐to” Guides are intended to simplify the product implementtation.
While specific product features and procedures typically are explained in a
practical business context, it is not implied that those features and procedures
are the only approach in solving a specific business problem using SAP
NetWeaver. Should you wish to receive additional information, clarification or
support, please refer to SAP Consulting.
Any software coding and/or code lines / strings (“Code”) included in this
documentation are only examples and are not intended to be used in a
productive system environment. The Code is only intended better explain and
visualize the syntax and phrasing rules of certain coding. SAP does not warrant
the correctness and completeness of the Code given herein, and SAP shall not
be liable for errors or damages caused by the usage of the Code, except if such
damages were caused by SAP intentionally or grossly negligent.
Disclaimer
Some components of this product are based on Java™. Any code change in
these components may cause unpredictable and severe malfunctions and is
therefore expressively prohibited, as is any decompilation of these
components.
Any Java™ Source Code delivered with this product is only to be used by SAP’s
Support Services and may not be modified or altered in any way.
Document History Document Version Description
1.00 First official release of this guide
Typographic Conventions Type Style Description
Example Text Words or characters quoted from the screen. These include field names, screen titles, pushbuttons labels, menu names, menu paths, and menu options.
Cross-‐references to other documentation
Example text Emphasized words or phrases in body text, graphic titles, and table titles
Example text File and directory names and their paths, messages, names of variables and parameters, source text, and names of installation, upgrade and database tools.
Example text User entry texts. These are words or characters that you enter in the system exactly as they appear in the documentation.
<Example text>
Variable user entry. Angle brackets indicate that you replace these words and characters with appropriate entries to make entries in the system.
EXAMPLE TEXT Keys on the keyboard, for example, F2 or ENTER.
Icons Icon Description
Caution
Note or Important
Example
Recommendation or Tip
Table of Contents
1. Business Scenario .................................................................................................................................... 1
2. Background Information ........................................................................................................................ 1 2.1 SAP Business Suite .................................................................................................................... 2 2.2 SAP NetWeaver Gateway ......................................................................................................... 2 2.3 Sybase Unwired Platform (SUP) & Online Data Proxy (ODP) ................................................ 3 2.4 Clients & Sybase OData SDK Development ............................................................................. 4 2.5 Process Flow ............................................................................................................................. 5 2.6 Offline/Online ............................................................................................................................ 8 2.7 Push/Pull .................................................................................................................................... 8
3. System Prerequisites ............................................................................................................................ 10
4. Tasks ....................................................................................................................................................... 11
5. Gateway Configuration ........................................................................................................................ 12 5.1 Check the SUP SM59 Destination in Gateway. ....................................................................... 13
6. SUP/ODP Configuration ........................................................................................................................ 14 6.1 Create Security Configuration ................................................................................................. 14 6.2 Create Application ................................................................................................................... 16 6.3 Create Application Connection ............................................................................................... 18
7. Configuring the Development Environment ..................................................................................... 20 7.1 Download the IDE ................................................................................................................... 20 7.2 Setting up the Android SDK Manager .................................................................................... 21 7.3 Update you Android SDK with 2.2 API 8 Libraries .................................................................. 22 7.4 Create an Android Project ....................................................................................................... 22 7.5 Importing Libraries to your Android Application Project ...................................................... 25 7.6 Setting Project Properties ...................................................................................................... 26
8. Developing your Application ............................................................................................................... 27 8.1 A typical application ................................................................................................................. 27 8.2 Initialization ............................................................................................................................ 28 8.3 Calling Gateway Services ....................................................................................................... 33 8.4 Creating & Deleting Subscriptions ......................................................................................... 39 8.5 Receiving Notifications .......................................................................................................... 43
9. Running the Sample Application ........................................................................................................ 45 9.1 Application Structure .............................................................................................................. 45 9.2 Preparing the Application ...................................................................................................... 46 9.3 Running the application ......................................................................................................... 47
10. Notification Routing Explained ......................................................................................................... 50
11. Communication Architectures (Device Specific) ............................................................................... 51
12. Appendix – Subscription Collection ................................................................................................... 52
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 1
1. Business Scenario
SAP NetWeaver Gateway offers the ability to send notifications to a device and user who have subscribed to a suitable Gateway service. This capability does not need to be mobility centric however for the purpose of this document we shall assume it is. The illustration below highlights the basic premise behind notifications with SAP NetWeaver Gateway. This capability is different to SUP’s Data Change Notification function and is not covered in this document. For this document we will discuss how to create an Android application to consume subscription and notification enabled Gateway services via SUP.
Subscription and Notification with SAP NetWeaver Gateway allows you to send events to the mobile device for changes of a specific SAP Object. Hypothetically you could subscribe to all new employee hires or sales order creation events and push these to an interested user or device.
2. Background Information
Before we create the Android application it is important to describe how each component is used in the architecture above and how it fits into the Subscription & Notification process flow of SAP NetWeaver Gateway. This document is one of a number of guides that cover this topic.
Overview
• How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Overview
Gateway Configuration
• How-‐To…Subscription & Notification with SAP NetWeaver Gateway – Generation Tools • How-‐To…Subscription & Notification with SAP NetWeaver Gateway – Custom Development (OData Channel) • How-‐To…Subscription & Notification with SAP NetWeaver Gateway – Workflow
Client Development & SUP Configuration
• How-‐To…Subscription & Notification with SAP NetWeaver Gateway – iOS + Code Sample • How-‐To…Subscription & Notification with SAP NetWeaver Gateway – Android + Code Sample • How-‐To…Subscription & Notification with SAP NetWeaver Gateway – Blackberry + Code Sample
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 2
2.1 SAP Business Suite The SAP Business Suite represents the business logic or application layer responsible for holding the actual business data. SAP ERP, CRM & SRM are examples of SAP Business Suite applications and represent the core location for the application logic. In the context of Gateway and RESTful services objects such as Purchase Order, Employee and Material can be exposed to allow various clients to interact using Create, Read, Query, Update and Delete methods. Developers and architects need to choose between generating Gateway services off existing entities such as BOR/RFC & Screen Transactions or implement a programmatic service leveraging the Odata Channel framework. See Design Decisions and Variations for more information.
2.2 SAP NetWeaver Gateway SAP NetWeaver Gateway is a REST enabler that is available as a SAP NetWeaver Application Server ABAP (AS ABAP) add-‐on, which you can install on top of your existing SAP Business Suite or application platform. SAP NetWeaver Gateway offers development and generation tools to create OData services to a variety of client development tools. This is the vehicle to connect SAP Business Suite data and functionality to the target clients, platforms and programming framework. In this document we shall describe the subscription and notification scenario with a standalone Gateway instance integrating with a separate back-‐end Business Suite application server.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 3
2.3 Sybase Unwired Platform (SUP) & Online Data Proxy (ODP)
For the purpose of this document we shall assume a mobile device scenario and hence SUP plays a very important role in this scenario. The diagram below illustrates the inclusion of SUP in the architecture independent of security and 3rd party device specific messaging services.
Sybase Unwired Platform is SAP’s mobility platform and provides various capabilities beyond the scope of subscription and notification discussed in this document. In addition to SUP the Online Data Proxy (ODP) is a lightweight edition of the Sybase Unwired Platform that provides a robust mobile infrastructure for enterprise IT organizations to securely rollout and manage the deployment of light-‐weight applications in a controlled and monitored approach. For the purpose of this document SUP & ODP refer to the same capability or component. If you install SUP in full you have the ODP capabilities already embedded and no further action is required.
The ODP or SUP installation option provides the following in the context of subscription and notification with SAP NetWeaver Gateway:
• Device & User Onboarding • Application creation and management • Security profiling • Secure proxy connection to SAP NetWeaver Gateway abstracting SAP Business Suite Applications • Notification queuing & routing to specific device • Device online v offline determination • Device push notification registration • Connectivity to 3rd Party messaging services. APNS, BES etc.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 4
2.4 Clients & Sybase OData SDK Development To integrate clients with SUP into SAP NetWeaver Gateway, SAP has delivered a number of device specific libraries that abstract the developer from low activities. This is known as the OData SDK and consists of a collection of runtime libraries and classes. Note for Gateway standalone (non-‐SUP) scenarios these libraries are not required. For more information please the OData.org website here.
The SAP OData SDK supports Android, BlackBerry and iOS platforms and it is based on the native device SDKs of the platforms. There is an implementation for each platform. Native applications installed on the devices allow the client application to leverage the support provided by the given platform, for example:
• Adapt to each device’s form factor (for example, automatic layout)
• Exploit different input methods (for example, touch screen, keyboard or trackball)
• Cache data in native device data stores for better performance • Tightly integrate with the features of the device
The main function of the libraries is to provide the following high-‐level abstracted functions. For more information please see the official help documentation here.
• Parsing – Parsing of OData XML to native OData objects, Validate OData XML, Provide easy access to all OData Fields and structures via objects.
• Cache Management – Storing/accessing OData objects in memory, Efficient search OData entries in memory, Managing size of Cache.
• Persistence – Storing objects and raw data on the physical storage of the device, Easy and quick access to stored objects and raw data, Data Encryption
• Supportability – Common exception and error handling, Event logging, Tracing (SAP Passport) • SUP Connectivity – Synchronous and asynchronous HTTP request handling, Compresses payload
handling, Request types as support by OData Protocol, Connection pools for optimal performance
For our sample application we shall use a subset of what is available above and focus on Cache Management, Data Parser, Connectivity, Security, Supportability & Configuration.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 5
2.5 Process Flow The Subscription and Notification scenario is explained greater detail within the document “How-‐To…Subscription & Notification with SAP NetWeaver Gateway – Overview”. For the purpose of brevity the following high-‐level process summarizes our scenario. The following illustration depicts the basic architecture independent of 3rd party messaging and security components, followed by a description of each step in the process. Note the use of security firewalls, relay servers and 3rd party messaging services are left out of the diagram intentionally.
2.5.1 Step 1 - Registration (SUP) This process can be automated however for to explain exactly what is configured a SUP Administrator logs onto the Sybase Control Center and creates the following:
• Creates an application. • Creates a security profile to determine how user will be
authenticated in SUP. • Creates an application connection that binds a SUP
User, Application ID, Security Profile and activation codes.
• Maintains application connection properties with Gateway service URL and push endpoint URL.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 6
2.5.2 Step 2 – SUP Activation (Client) Using the SAP Odata SDK the developer creates a mobile application in the appropriate IDE and at runtime the client programmatically over HTTP/s:
• Connects to SUP • Activates the user and binds a device ID to the application connection created in
the first step. • Registers the mobile application for push notifications. (Long poll initiated) • Retrieves the Gateway URLs from the SUP application connection properties • Retrieves the push URL endpoint form the SUP application connection properties • Retrieves messages from SUP found in the application connection queue
2.5.3 Step 3 – Calling Gateway Services (Client) Once the activation and initialization is done the client then calls the gateway services a normal application independent of a subscription and notification scenario. If you were developing an standard SUP/Gateway enabled application you could stop here and just perform CRUD operations of your Collections.
The initial Gateway Service calls in sequence (once only):
• Gateway Service Document – send, receive, parse & cache • Gateway Metadata Document – send, receive, parse & cache
Subsequent Data Calls (as many as required):
• Data Collection/s. In out case we perform a simple query on FlightCollection – send, receive, parse & cache
• Display on screen. • Call as many collections as you need and perform create, read, update & delete operations as
required.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 7
2.5.4 Step 4 - Create Subscription (Client) Before a user can receive any notifications the client application needs to subscribe explicitly to a Gateway service entity that is subscription enabled. We will talk more about how to enable Gateway Services for subscription in other How-‐To guides but for now we can assume that for a given Gateway Service such as SFLIGHT subscription is enabled.
2.5.5 Step 4 - Trigger Notification (Backend) Once a subscription has been created against a suitable Entity or Collection the client waits for a notification. Normal business processing occurs in the Backend until a trigger is fired and starts the notification process back to Gateway, SUP and the observing device and user. Depending on how the Gateway Service was implemented the trigger may be executed by normal business processing such as a Purchase Order Create or Sales Order Change which forces a Business Object Repository object state change. This method is a SAP concept and is leveraged by SAP Business Workflow and many other applications. For more information have a look at transactions SWO1 & SWO2. If you choose to use the custom development approach known as the OData Channel you will need to implement the trigger yourself in the appropriate business process location, such as a exit or BADI. Asynchronous communications between the Backend system and Gateway are executed using Background Remote Function calls (BGRFC).
Once a notification has been received in Gateway the message is sent to SUP via a SM59 RFC Destination. SUP always listens on a set URL for inbound HTTP/s notifications coming from Gateway and this value was stored in the application connection properties in SUP and also would be defined in the SM59 HTTP Destination: http://host:port/GWC/SUPNotification/.
2.5.6 Step 5 - Receive Notification (Client) In SUP the server checks if the mobile device is online and then sends the message to the device via a response using the long poll connection established continuously at application initialization. The device application accepts the message or notification via a standard class method and then the developer can execute any action he or she wants. Note – For Android scenarios SAP only supports online scenarios. Please see the next chapter for more information regarding push/pull and offline/online.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 8
2.6 Offline/Online Offline and online capabilities are supported generically with SUP however with Android and the current lack of support for C2DM only online scenarios are available. When a notification arrives in SUP the server determines if a device is offline or online and routes the notification via ODP (default) mechanism or 3rd party messaging service if configured appropriately. The following describes each in more detail:
2.6.1 Offline A device is offline when it is not connected to SUP and the application is not in foreground. You may be in an area where connectivity is restricted such as a plane or tunnel. In such situations notifications cannot reach the phone or mobile device. Notifications are stored in the messaging queues and once a device re-‐connects with SUP the notifications are send to the device in push scenarios.
If you have a Blackberry or iOS device you can integrate vendor specific messaging services such APNS. This configuration is performed in the application connection properties in SUP SCC. In this scenario you device may have Internet capability yet not explicitly connected to SUP. For Android only online scenarios are supported.
2.6.2 Online A device is determined to be online if is has connectivity to SUP and initiated or started the client communications explicitly. In addition to this the device must register for push notifications. You can check if a device is online or offline via the SUP SCC application connection screen. We will demonstrate this capability with our sample application.
2.7 Push/Pull SAP NetWeaver Gateway & SUP supports two types of notifications. They are described below in further detail and are implemented via configuration and application design within the IDE. Push is where the notifications are sent to device and pull is where the device explicitly requests the notifications.
2.7.1 Pull Notifications are stored in SAP NetWeaver Gateway for later retrieval explicitly made by the client. The client needs to call a separate Gateway service that comes standard and is dependent on the framework used at design time within Gateway. i.e. SP3 & SP2 have different URLs. The persistNotifications element in the subscription create step defines if push or pull is used. This approach is effectively an explicit request/response made from the client as if you were attempting to query a Flight service you would be querying a Notification service. In such cases SUP does not perform any queuing functionality or communications to 3rd part messaging services like APNS etc.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 9
2.7.2 Push The push scenario is where notifications are sent from SUP to the Device in one of two methods. These methods are described below and can be used together via configuration to maximize the reach of notifications to your device. When a device is connected to SUP and registered for push notifications it is determined to be online and therefore ODP will be used. If a device is not connected to SUP then the 3rd Party Messaging Service will be used if configured correctly in SUP SCC.
2.7.2.1 ODP Notifications are sent to the device using a SUP protocol leveraging a long poll mechanism. As each mobile device does not have a discrete web server addressed uniquely, the device at the initialization stage establishes a connection to SUP (request) and keeps it alive for a default of 5 minutes. If a notification is sent to SUP in this time it is sent to the device as the direct response. This simulates a push by always maintaining an open connection that SUP can respond to via a normal request/response cycle. So in fact the push is really client initiated. SUP passes on what ever it gets from Gateway.
2.7.2.2 3rd Party (APNS + BES) Notifications are sent from SUP via a 3rd part messaging service such as APNS. The pushed message can be received if the application is „background“ (or offline) or „foreground“ via Apple’s APNS channel. The device and application doesn’t have to be directly reachable to SUP server. APNS works if the device is in the public Internet and not able to connect to SUP.
CAUTION
The diagram above is one very simple example to explain how push technology works with SUP. The landscape in the production system would have additional elements such as a relay server to handle firewall
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 10
3. System Prerequisites The following are the prerequisites to complete the steps in this guide:
• You have access to a NetWeaver 7.02 SP6 or higher system, which the SAP NetWeaver Gateway ABAP add-‐ons have been installed.
• You have SUP 2.1 installed.
• Backend SAP application with the IW_BEP Gateway add-‐on installed.
• Connections between SAP NetWeaver Gateway system and backend SAP application are configured.
• You have a subscription and notification enabled service configured in Gateway such as RMTSAMPLEFLIGHT.
• You have access to the Sybase Developer Workspace (required libraries)
• You have access to SUP SCC.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 11
4. Tasks
The scenario detailed in this document has four major configuration steps. The first is a pre-‐requisite to ensure you have the sample SFLIGHT gateway service running in your system. There are a couple of variations of this service depending on the SP level of your Gateway instance. Following this we move into SUP and perform the configuration for manual user onboarding. Once this is done we will look at the Android development environment and discuss the coding steps to get an application working.
The code sample attached demonstrates holistically and can be run easily. It is important to emphasize any sample code is purely for demonstration purposes and not for production. Aspects such as strong security mechanisms, persistence, Android release compatibility and application state changes are not covered.
Step Android SUP Gateway
Gateway Configuration
• Check the Service is available • Maintain Destinations for Client Notifications
SUP/ODP Configuration
• Security Profile • Application / Application Template • Application Connection
Android – Configuring your Development Environment
• Download the IDE • Setting up the Android SDK Manager • Update Android SDK with Libraries • Create an Android Project • Importing Libraries to your Android Application Project • Setting Project Properties
Android – Develop your application
• Initialization • Calling Gateway Services • Creating & Deleting Subscriptions • Receiving Notifications
OData SAP NetWeaver Gateway
SAP Business
Suite
SUP (ODP)
Subscription
Notification
RFC
bgRFC
OData
2 1
3
4
5
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 12
5. Gateway Configuration
Before we can build an application you need to have a gateway service configured and available. There a many ways to create a service using Gateway and other “How..To” guides explicitly describe the required steps to configure such scenarios. For the purpose of discussion and our sample code we will be referencing RMTSAMPLEFLIGHT, which is shipped with all Gateway instances. The typical URL for this service can be seen below. Note for SP3 enabled services this URL may differ. Please official help for more information.
• http://gatewayserver:port/sap/opu/sdata/IWFND/RMTSAMPLEFLIGHT
Once you have a created or enabled you service to be subscription and notification enabled the metadata document and service document should reflect this. Below is an example of the service document from the RMTSAMPLEFLIGHT. You can see the service document indicates it is subscription and notification enabled and that the FlightCollection can be subscribed against.
Below is an example of the metadata document. You can see the metadata document indicates it is subscription and notification enabled and actually shows the schema of the each. That tells us what an inbound notification would look like and how the client API can easily covert to consumable data types. Conversely it also shows us what a subscription request would look like from a payload perspective. We will use this when we create the subscription highlighted later in this document.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 13
It is important to note that the Subscription Collection acts like any other Collection. You can create, update, delete, read and query any subscriptions using the HTTP Verb combination with an appropriate URL and payload. For more information please see „Appendix – Subscription Collection“ for more information.
5.1 Check the SUP SM59 Destination in Gateway. This step is described in other documents and is specific to the gateway configuration. At runtime when a notification is created in gateway it looks at who created the subscription and matches a delivery address used in the payload on creation and then checks if a SM59 Destination exists with the same server/port/url. This URL determines how to send the notification to SUP. For SUP scenarios this should be constant and equal to below. “/GWC/SUPNotification” on port 8000 subject to security and SSL.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 14
6. SUP/ODP Configuration Before we actually create an Android application we need to configure SUP using the Sybase Control Center. The steps are easy and would be performed by an administrator. In some cases these steps may be automated (onboarding) but to gain a clear understanding of what is happening it is beneficial to create these manually. It is really important to do these steps prior to creating and running an application on a device as there are key entities our Odata SDK API or client application will interact with dynamically at runtime.
6.1 Create Security Configuration In the Sybase Control Centre you need to login and create a security configuration to determine how your application will be authenticated in SUP. There are a couple of options available and are discussed in further detail in other documents. For external authentication SUP checks another system according to the option selected and then responds with success or failure. SUP does not hold the security information in the server but checks the external provider in line with your corporate security strategy. The following options are available:
• Manual User Onboarding – No Authentication • External Authentication – Username/Password • External Authentication – SSO2 • External Authentication – Certificates
For the purpose of our simple application we will be using manual user onboarding and hence will create a security profile with no authentication requirements. The following steps describe this configuration.
1. Log onto the Sybase Control Center. 2. Click on the Security Node on the left hand side.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 15
3. Click on “New” in the main tab and enter a new Name such as “ManualUserOnboarding”.
4. Find the newly created profile as a child to the Security node on the left hand side. In the main screen click the tabe “Authentication” and then click the button “New”.
5. A new screen will appear in dialogue. From the pull down option select “NoSecLoginModule” and click “OK”.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 16
At this stage we now have a security profile with no security requirements. Of course in production you would not have this and would select a strong level of authentication. For the purpose of our application and a development environment it meets our needs. For more information on ODP/SUP security options please refer to the appropriate help documentation here:
• http://infocenter.sybase.com/help/index.jsp?topic=/com.sybase.infocenter.dc01212.0152/doc/html/mqu1264545412442.html
6.2 Create Application The next step is to create an application object in SUP SCC representing our Mobile application. This is the key as is allows us to specify the security profile and connectivity URLs pointing to Gateway. Other options cab be configured here such as 3rd party messaging connections like APNS. This step creates a template that we can bind application users to in the next step.
1. In SCC click on the “Applications” node in the left hand index. 2. In the “Applications” tab on the right hand side click on “New”.
3. In the dialogue box fill in the details as per below using “Gateway_Flight_Push”. For the security configuration select the profile you created in the previous step “ManualUserOnboarding” and select a valid domain. It is important to select the “Configure additional settings” at the bottom and the click “Next”.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 17
4. In screen shown you need to maintain the Proxy tab settings and enter the URL pointing to your
Gateway service. This screen creates a template that we will use as we add device users in subsequent steps. Take note of the template name, as we will use this in the next step.
Template Name – “Gateway_Flight_Push_default_ManualUserOnboarding”
Maintain the following URLs in the “PROXY” tab. Why? Both the application endpoint and push endpoint values will be dynamically retrieved by the client application at runtime to provide landscape abstraction. This could be QA or Production and it allows you to abstract between tiers.
• Application Endpoint – This is the Gateway URL our application is bound to. In our
case this is the flight service shipped with all Gateway instances. It represents the starting place for your application from which at runtime your client application would suffix Collections or $metadata calls to retrieve and navigate through your application. http://GATEWAYHOST:PORT/sap/opu/sdata/IWFND/RMTSAMPLEFLIGHT
• Push Endpoint -‐ This is the SUP entry point for inbound notifications coming from Gateway. Please look at the chapter “Notification Routing Explained" to see how this is used at runtime and mapped to device when the notification arrives in SUP. Also this address will match the SM59 destination created by the Gateway Administrator. http://SUPHOST:8000/GWC/SUPNotification
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 18
Before you click “Finish” have a look at the APNS and Blackberry Push Notification tabs. This would be where you configure connectivity to these services. For Android we only support online push/pull and therefore we do not need to maintain these. Click “Finish”. Your newly created application show is now visible and if you click “Application Connection Template” tab you will see a new template created in this step.
6.3 Create Application Connection Now that we have an application created with a useful template, we can now manually onboard users. This user will represent the mobile device user. We do this by creating “Registering” and “Application Connection”.
1. In the “Applications” screen click on the “Application Connections” tab. 2. Click the “Register” button.
3. On the screen provided enter a username we will use at runtime. Note this is user is not the gateway ABAP user but a abstracted device user which will be specified in device application.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 19
4. On the screen provided select the template we created earlier. This will pre-‐fill many fields and
bind the connectivity parameters in background.
5. On the screen provided check the “Specify activation code” radio box and maintain an activation code such as “abc”. We will use these values in the Android java code later!
1. Click the “OK”.
2. Once this step is complete you can now see your user has been on-‐boarded manually. Notice that the Status is “Pending Activation”. This will happen at runtime once the device connects to SUP using the Odata/SUP libraries. You can also see “Pending Items” in the queue. We will see how this changes once we get an application running.
3. Click on the “Properties” button. On the screen displayed you will see the properties maintained earlier when we created the template. Make sure the endpoint hosts names are correct and will be accessible from your SUP server and Device or development environment.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 20
7. Configuring the Development Environment
Now that we have a Gateway service ready and the configuration in SUP/ODP is complete lets look at the steps required to get an Android application working. The first step is to set up your development and correctly reference the SUP/Odata SDK libraries.
7.1 Download the IDE
1. Download the Java Standard Edition (6 Update 24) Development Kit from the following URL: http://www.oracle.com/technetwork/java/javase/downloads/index.html
2. Download Eclipse Helios (3.6.2) from the following URL: http://www.eclipse.org/downloads/
3. Start the Eclipse environment and perform the following:
• From the Help menu, select Install New Software.
• Click Add.
• In the Add Repository dialog, enter a Name for the new plugin.
• Enter one of the following for URL:
• https://dl-‐ssl.google.com/android/eclipse/
• http://dl-‐ssl.google.com/android/eclipse/
• Click OK.
• Select the Developer Tools checkbox and click Next.
• Review the tools to be downloaded.
• Click Next.
• Read and accept the license agreement and click Finish.
• Once the installation is complete, restart Eclipse.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 21
7.2 Setting up the Android SDK Manager The Android SDK Manager handles the Android library versions specific to a device O.S release like 2.2 etc. You need to download this and install the required libraries in our case 2.2. Once we have done this we can integrate it into our Eclipse environment.
1. Download the Android SDK Manager based on your system requirements from the following URL: http://developer.android.com/sdk/index.html
2. Download the zip file such as android-‐sdk_r15-‐windows.zip. 3. Unzip the archive to a location of you choosing.
4. In the Eclipse environment, from the Window menu, select Preferences.
5. In the left navigation pane, select the Android node.
6. Click Browse to search for the location where you have stored the Android SDK.
7. Click Apply and OK.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 22
7.3 Update you Android SDK with 2.2 API 8 Libraries 1. In the Eclipse environment, from the Window menu, select Android SDK Manager.
2. The available Android libraries will be listed.
3. Check Android 2.2 and any other packages you wish to download. You may want to create an Android application for a device with a later operating system version. It is up to you to decide what you need here. I’ve used 2.2 for a basic application.
4. Click Install Packages
7.4 Create an Android Project We assume you have a basic understanding of creating Android projects and are familiar with Android programming. The purpose of this document is not to explain Android best practices but rather demonstrate the key APi’s and methodology associated with integrating SUP and NetWeaver Gateway for subscription and notification scenarios.
1. From the toolbar, select New -‐> Project-‐>Android-‐>Android Project.
2. In the New Android Project wizard, select Create new project and enter the project name GatewayFlightPush. If you would like to use our sample code I suggest you stick to csa.sap.com that way you can easily copy and paste the classes into your project with little alteration.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 23
3. Click Next.
4. Select the build target from the Android Release Libraries you downloaded in the previous step. E.g. Android 2.2 API 8.
5. Click Next.
6. Enter a suitable package name like csa.sap.com. If you would like to use our sample code I suggest you stick to csa.sap.com that way you can easily copy and paste the classes into your project with little alteration.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 24
7. Click Finish.
You will now have an empty project that represent the starting point for development. The next step is to add the SAP shipped libraries specific to Odata SDK and SUP.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 25
7.5 Importing Libraries to your Android Application Project 1. In your IDE project structure create a folder called lib.
2. Copy the SUP/Odata SDK Libraries centrally from the following location:
<UnwiredPlatform_InstallDir>\MobileSDK\OData\Android\libraries\
• sup-‐json.jar • ClientLib.jar • SUPProxyClient.jar • SDMCache.jar • SDMCommon.jar • SDMConnectivity.jar • SDMParser.jar • SDMPersistence.jar
In the IDE import the files to your project under the directory lib. You can do this by selecting lib and right click to find the menu item IMPORT. Select from File System and point to the physical file locations. Make sure they are highlighted. You should end up with a project structure similar the image below.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 26
7.6 Setting Project Properties Now that our libraries are in our project structure we need to set the project properties and build path so they are referenced correctly.
1. Click on the top node of your project in the left hand index and right click to select Properties.
2. Select Java Build Path from the index and select the Libraries tab on the main screen to the right.
3. Select Add JARs… button, locate and highlight all the Jar files from in the newly created lib subdirectory.
1. Click OK.
2. Click the Order and Export tab and should now see you Jar files are available for selection.
3. Select the two project GatewayFlightPush items and select Bottom.
4. Check the radio boxes for all the libraries you just imported into the lib directory.
5. Click OK.
You are now ready to start developing your SUP/ODP Gateway enabled application. This process is the same for every project so it makes sense to copy the library files somewhere handy. Our next chapter will look at the API’s available and the general process for developing an application with subscription and notification scenarios. Please refer to the example project chapter to see how to plug in the shipped code sample into the structure you just created above. The Chapter developing your application talks about the basic steps and the approach without stepping through copy/paste, which is not the aim here.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 27
8. Developing your Application Now we are ready to develop an application and talk about the API’s available to integrate and Android application with SUP and Gateway. This chapter will talk about the steps and code examples in isolation. It does not go into best practice for Android application design. The sample application associated with this document is purely a demonstration of how the code can be executed. For productive scenarios it is recommended not to use this example as it doesn't cater for security, state change, persistence, model view control patterns etc. It is just an EXAMPLE. How you leverage MVC and listener classes is up to you. You may want to separate this more and provide a smaller unit of operation and it would be recommended when considering productive scenarios. This chapter can be referenced with steps or API’s listed in the Sybase Help Website here:
http://infocenter.sybase.com/help/topic/com.sybase.infocenter.dc01708.0212/doc/html/nkr1315676693912.html
8.1 A typical application The standard Odata/SUP/Gateway enabled application follows similar process or pattern independent of any subscription and notification requirement. The following steps highlight the approach with the subsequent sections giving more detail per step. I have left out some optional steps, which embrace alternate security and persistence activities and possible Afaria integration. Please refer to the help documentation mentioned above to understand what possibilities exist.
1. Initialization • SUP Onboarding • Register for Push Notifications (Long Poll) • Retrieve Endpoints • Starting the client
2. Calling Gateway Services
• Get Service Document • Get Metadata Document • Get Data (Flight Collection) • Display
3. Creating & Deleting Subscriptions
• Create Subscription • Delete Subscription
4. Receiving Notifications
• Capturing inbound notifications
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 28
8.2 Initialization The initialization phase start the application and establishes connection to SUP with additional registration activities. We will step through each of these and show some sample code for each. Remember the sample application associated with this document demonstrates how they all work together in sequence bound to a user interface. Before we even connect you must initialize the objects or libraries we imported previously. From the total SDK libraries available the following will be used in our application.
You can see from the code snippet above we need to initialize the objects that will be used in the project, such as preferences, logger, parser, cache, parameters and request manager. They will be used at length during our interaction and calling of Gateway services. I’ve created a method to wrap these steps neatly but there is nothing stopping you from putting this into one. How you segment your code is up to you.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 29
8.2.1 SUP Onboarding As we are using SUP in this solution we need register the device/user with SUP at runtime using the matching activation code and user we created manually in SUP. Have a look at the code snippet and see how is it executed. You can see we check to see if the device is already registered with the Boolean check.
Remember the “Andy/abc” user and activation code combination? Here is where it is used.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 30
8.2.2 Start the client In the same segment of code we start the client to initiate the communications such that the messages in the pending queue of the application connection for the given device are sent to the application. It is only one line of code. If the device has already been registered the client needs to be started explicitly. If it has not been registered the messaging happens automatically when you call the registration method and so is not needed. See below.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 31
8.2.3 Register for Push Notifications (Long Poll) In the same segment of code we need to register the application for notifications. It is as simple as one lin of code but it technically kicks off a long poll which continuously sends a request to SUP every 5 minutes so SUP can send notifications back as part of the response. This was discussed in the chapter “Background Information – Push v Pull”. You can see that we pass “this” to the method. This tells the program that this class will listen for notifications via a specific method. As mentioned previously you can implement your own separate class to keep the size reasonable and improve android application design. We will talk about this in the next chapter.
If you really wanted to see how this works you could set up a http trace program to sit between SUP and the device and listen on the 5000 port for HTTP.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 32
8.2.4 Retrieve Endpoints In the same segment of code we need to retrieve the two URLs that were maintained manually by the SUP Administrator. Remember we did this in the SUP configuration steps? Once retrieved, we save them to local variables and use them later. It is up to the developer to save or just check the endpoint each time. The SDK offers a listener to notify the client at runtime if a change in the URLs has taken place. It is up to you to implement what is suitable for your application design best practice.
Application Endpoint
For the Application Endpoint or Gateway Service Document URL we can then dynamically build URLs at runtime with particular suffixes to call service in the way we wish. The example can be seen below.
Application URL = http://gatewayserver:port/sap/opu/sdata/IWFND/RMTSAMPLEFLIGHT
Then we can build this into various combinations at runtime such as :
• Application URL + “/FlightCollection” • Application URL + “/BookingCollection”
Push Endpoint
The Push endpoint will be used later when we create a subscription. We will dynamically insert it into the payload of a subscription request so in Gateway the notification will come back to the correct SUP landscape dependent URL.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 33
8.3 Calling Gateway Services At runtime the Android application will need to interact with Gateway services. To do this we need to use the connectivity libraries to build Odata requests and send them either as a batch (synchronously) or in isolation. The process is always the same with every Odata application running through SUP.
You need to always retrieve the Service Document, then retrieve the metadata document and finally execute Data calls to perform CRUD operations with your actual service. We need to get the service document and metadata document first as this holds important schema information for the subsequent collection calls. As an example there is no point calling a Flight Collection when you don't even know what the structure of a Flight may be. So its important to execute these in a particular order and control it sequentially.
How is this done? Using the API’s we easily build request and send them to the request manager. The important thing to note here is the request is not synchronous from the code perspective. You schedule a call and execute and then implement an onSuccess and onError method to capture the response from SUP and Gateway. These methods or listener class can be separate to the one we have used. All calls are asynchronous from a coding perspective releasing the Android application to perform other activities. Over the wire it is still a synchronous call. The next section explains this in detail.
8.3.1 Call the Service Document When you create an Android application for use with SUP & Gateway you need to determine what class is going to handle the data calls. This is your decision as there is nothing stopping you from putting it in a standard java class, the application class or an activity class. Either way the process is the same.
8.3.1.1 Calling In the class you have chosen you simply use the SDMConnectivity library to build a request and send to the Request Manager. The screens shot below shows an example. When we initialized the application we create the object requestmanager so we only have to create a request object and fill it with the URL, HTTP Verb and payload if any. Then we simply add it to the request bundle and fire the request manager to make the call. Note a bundle is a series of calls which will be execute sequentially. It is up to you if you want to use bundles or not.
In this code snippet you can see I call a helper method call buildRequest. I’ve created this to add HTTP headers and payloads depending on my CRUD operation. The method can be seen below and is just an example of abstraction. The key point here is we set a listener to “this”, meaning the class will receive the responses elsewhere in another method. It is not the best programming and is just an example!
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 34
8.3.1.2 Receiving Once the call has been sent, the code continues independent of the request manager executing the call. So you need to manage your code appropriately. In my example I chose to use a Boolean variable to wait for a state change and then continue. You can see this in the code snippet below from the same segment of code as the initial request. This is just an example and ideally you would not hold the UI in such a state. I’ve done this to push a dialogue box to the UI for demonstration purposes.
Even though we are waiting for the response here, the actual response is captured elsewhere in you class. To do this you always have to implement the ISDMNetListener interface for the class doing the work. The example below shows a class called model. Here I’ve declared it to implement ISDMNetListener.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 35
Once we have done this we have to implement two methods onSuccess and onError. These methods are used to capture the responses to any Odata calls we make to Gateway via SUP. See below for the signature of each method. You must implement them! For the onSuccess method you need to interrogate the incoming response “aResponse” and check for additional HTTP Status codes. By looking at the request URL also you can determine whether the response was a Service Document, Metadata, Subscription, Notification or Collection call.
8.3.1.3 Parsing As mentioned above in the onSuccess method you need to put some logic to determine what the response is actually in response to. Once you have done this you need to parse the payload into an existing Entity which is defined from your service. Now you see why we have to call the Service Document and metadata documents in a particular order. Have a look at the code snippet below and see how we call the parser for in this case the Service Document. You will do this with every call except you will cast it to a different entity.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 36
8.3.1.4 Caching So now that we have captured and parsed a call coming in from Gateway and SUP we then need to put it into the cache so we can leverage it easily later in our application. This is really easy and is one line of code. You can see it from the code snippet below. Once this is done you now have the approach for all subsequent calls using this methodology. All that changes is the HTTP method, payloads and interrogation on the response coming back in.
Note – See how I used the Boolean statement at the end to signal the other method data is available? You can implement this however you want. It is just an example.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 37
8.3.2 Call the Metadata Document So the same process applies to the metadata document except we will use a different URL and receive a difference entity. I will not describe the process again rather show the differences in via code snippets.
8.3.3 Calling
8.3.4 Receiving & Parsing & Caching
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 38
8.3.5 Call the Data Collection (Flight) Once again we execute in the same manner with some slight variations. I want to call the Flight Collection so I can display a particular flight on the user interface before we actually subscribe. You can implement whatever call you want here. I’ve chose to use the $filter notation as an example instead of an explicit read of a unique flight. This was direct decision as I was not sure of what data would be available cross system. I will not describe the process again rather show the differences in via code snippets.
8.3.6 Calling
8.3.7 Receiving & Parsing & Caching
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 39
8.4 Creating & Deleting Subscriptions Once we have an application running and the core Gateway services in cache we can display the data appropriately. This document does not describe how to render the data, as it is really core Android programming. The sample code demonstrates an example of how you could separate and Android Activity with a model class but is only for demonstration purposes. More on that later!
8.4.1 Create Subscription The process of create a subscription is no different to interacting with any other Gateway Collection except we just have a specific payload to adhere to. What is really nice about the Odata SDK is the classes will help you build the subscription payload very easily. Remember all we need to do is call the SubscriptionCollection with a HTTP POST (Create), some HTTP Headers (SP2/Sp3 specific) and attached the payload. Let’s take a look at how we do this in the code.
8.4.1.1 Calling
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 40
What does that actually build? The XML Payload can be seen below.
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom">
<atom:id/>
<atom:title>Subscription</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>http://SUPHOST:8000/GWC/SUPNotification</d:deliveryAddress>
<d:collection>FlightCollection</d:collection>
<d:filter></d:filter>
<d:select>*</d:select>
<d:persistNotifications>false</d:persistNotifications>
</m:properties>
</atom:content>
</atom:entry>
The following table describes the most important XML elements and their meaning in relation to our scenario. In our sample application we are not subscribing to a particular flight using the filter element. I am just connecting the end-‐to-‐end scenario for a demonstration.
Element Description
title This can be any text
deliveryAddress Specifies the location of subsequent notifications for Business Object events. We will put a trace on this location to demonstrate what is posted in when a Backend Business Object event is created. At runtime this URL and port is compared to the HTTP destinations defined in SM59. If there are two or more SM59 destination it will retrieve the first entry only. For mobile scenarios with SUP this URL can be retrieved dynamically from SUP application connection properties set by an administrator.
Collection The Gateway Business Object Collection created in the pre-‐requisite scenario. If you are unsure of this name you can always search for it in the metadata document available by performing a HTTP Get on http://<Gateway hostname>:<Gateway host http port> /sap/opu/sdata/sap/<your service document>/$metadata
filter A filter enables the user to either subscribe to all business object instances or only a specific entity instance. This complies to the normal Odata $filter notation and supports only AND operators. E.g If the filter is left empty we will subscribe to all material creation events. We can put something like the following to subscribe only to a specific material. The following is an example of Sales Order. E.G. <d:filter>value eq '0000004003' and scheme_id eq 'SALES_ORDER' and scheme_agency_id eq 'Q5K_004'</d:filter>
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 41
select Either * or blank. It is possible to retrieve the object content instead of just the event information. This is the responsibility of the application in the backend to populate the entire payload or business object contents. Please consult the backend application documentation to understand if this is supported.
persistNotifications This element determines if notifications are sent (pushed) to SUP and persisted or whether they are stored in Gateway for later retrieval via a pull. To retrieve notifications via pull you need to call a different service all together.
Example : http://<hostname>:<port>/sap/opu/sdata/iwfnd/NOTIFICATIONSTORE/NotificationCollection?$format=xmlsap-‐client=<clientnumber>
Note – This is only supported when implementing subscription and notification when using the OData channel.
8.4.1.2 Receiving & Parsing & Caching The same process applies for creating the subscription. You simply check the request/response information in the onSuccess and then parse and cache accordingly. Note you will need to check the HTTP response codes as they will bring back 201 and possibly 204 for a successful create. Remember you need to save the subscription GUID that comes back from the Gateway Server. This uniquely identifies the subscription so you can unsubscribe later.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 42
8.4.2 Delete Subscription Deleting a subscription is very easy and follows the normal convention of deleting an entity in a RESTful paradigm. All we need to do is build a URL with a suffix of SubscriptionCollection and the unique ID we want to delete. We combine this with some HTTP headers and the HTTP verb DELETE. We don't need to parse or cache the response, as it will be empty. You may just want to delete any cache items to be consistent. As long as it is successful!
8.4.2.1 Calling
8.4.2.2 Receiving
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 43
8.5 Receiving Notifications When a trigger occurs Gateway or a Backend the notification comes into SUP and into the device via our long poll mechanism described earlier. All we need to do is use the same onSuccess method to check the inbound message and see if it is a notification. So we don't have to do the call here is just a case of receive, parse and cache.
8.5.1 Receive & Parse & Cache The code below shows the same process is followed in the onSuccess method. The difference here is in my application I’ve separated the Activity class (UI) with the model (calls/etc) class.
Given in here I cannot raise UI events or interact the notification center I use a observer/observable pattern to notify the Activity class. This is done with the setChanged and notifyObserver methods. This is really outside the scope of this document as its up to you to determine how to design your Android application. The code snipper below comes from my Activity class (DIFFERENT) and shows how I receive the state change and then retrieve the notifications from the model using a get method. This retrieves it from the cache.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 44
The step in the Activity class is just to pass it to the notification center of the operating system. You can see that below. It is just an example.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 45
9. Running the Sample Application
9.1 Application Structure The sample application mentioned in this document is really simple and does not reflect a complete approach to Android application design. The sample application is attached! Please use Adobe Viewer to view the attachments. You will not see this if you use Apple Preview. It is just a connectivity example, which enables the basics. Please use your own java class pattern combination that suited your requirements and is production worthy. This is not production worthy as it is just an example! There are only two classes and three other files requiring change in this project:
• Activity – (GatewayFlightPushActivity.java) The Activity class was automatically created for you when you created the project. This class handles the lifecycle of the application and enables interaction with the user interface. I’ve abstracted the data calls away from this class to demonstrate abstraction. This file is located in the folder src/csa.sap.com
• Model – (Model.java) This class represents the engine room for interaction with SUP and Gateway. It handles the calling, onboarding and eventing capability from which the activity class would call as required. This is the class that implements the SUP/Odata SDK specific interfaces with the onSuccess and onError methods. This file is located in the folder src/csa.sap.com
• AndroidManifest.xml The android manifest xml document is created automatically however we need to make alterations to allow permission for accessing phone capabilities.
• Layout_border.xml & Main.xml These files are stored under the folder /res/layout directory and describe the screen layout.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 46
9.2 Preparing the Application
9.2.1 Copy the files To make you application runnable you need to copy and paste the files listed above which are attached to this PDF document into the directory structures mentioned above. In some cases you will need to overwrite and existing file.
9.2.2 Change Model.java Before we can run the application you need to make changes to the model class replacing the user logon information specific to your landscape. In a productive environment you would leverage the vault api and not embed the username and password information in the code! Please change the following.
// Settings for Connectivity protected static final String SUP_HOST = "10.1.1.55"; // SUP Server Host protected static final String SUP_PORT = "5001"; // SUP Port protected static final String SUP_COMPANYID = "0"; // Farm ID protected static final String SUP_USERNAME = "Andy"; // SUP User Name protected static final String SUP_ACTCODE = "abc"; // Activation Code protected static final String GW_USERNAME = "XXXXX"; // Gateway User Name protected static final String GW_PASSWORD = "XXXXX"; // Gateway Password
protected static final String SUP_APPLICATION = "Gateway_Flight_Push"; //
1. Change the GW_PASSWORD and GW_USERNAME to equal your intended SAP NetWeaver Gateway credentials.
2. Change the SUP_HOST and SUP_PORT to reflect your SUP specific information. 3. You should not need to change the SUP username, activation code and application if you followed
the instructions correctly in the previous chapters.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 47
9.3 Running the application Run the application as per a normal Android application and view the SUP logs to see the interaction. I highly recommend you debug this application first as you will see meaningful debugging information in the logcat view within the eclipse environment. You should see the following screens if the services are called correctly.
1. The application loads and steps through the SUP onboarding and gateway service call process. You can check in SUP SCC to see the application connection shows the device or simulator is registered!
2. The application UI shows the steps are being performed. You can see these below. Activation/Registration.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 48
3. You should see the Gateway Services being called Service Document, Metadata Document and finally the Data Collection. For us the FlightCollection.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 49
4. To perform a subscription click the subscribe button and wait for the subscription create call to be executed. You should see the subscription status updated appropriately.
5. Once this is done. Log into the gateway instance and run the sample report that will trigger a notification for the flight scenario. The report is “/IWBEP/R_MGW_PUSH_TEST”.
6. In the application you should see the event notification arrive and displayed appropriately. Remember this is just an example of the end-‐to-‐end connectivity. Also look at the SUP logs to see how the notification is routed to the device. For more info please see the next chapter notification routing explained.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 50
10. Notification Routing Explained So the big question. How is subscription and notification bound and what information is required to reverse route back to the device? The table below shows the key information and routing process.
Step Key Info Example
1. Registration Push Notification Endpoint URL maintained in the
application connection properties.
http://SUPHOST:8000/GWC/SUPNotification
2. Activation The client retrieves the URL and saves.
In the application connection SCC screen the
values are assigned as seen to the right. This is
the KEY!
Application Connection Id = Simulator3930223a-‐
f36f-‐4da7-‐a47c-‐573acb106e6c__ Gateway_Flight_Push
Application Id = Gateway_Flight_Push
User = Andy
Domain = default
3. Create Subscription The client uses the URL and suffixes with
application connection id, user, application and
domain and includes in subscription create
payload element deliveryAddress.
NOTIFICATION PERSISTED IN GATEWAY
FORMAT =
http://SUPHOST:port/GWC/SUPNotification/Applica
tionConnectionId/User/Application/Domain
http://SUPHOST:8000/GWC/SUPNotification/Simul
ator3930223a-‐f36f-‐4da7-‐a47c-‐573acb106e6c__ Gateway_Flight_Push
/Andy/Gateway_Notification/default
4. Trigger Notification Once the notification is in Gateway the SM59
destination with a constant host, port and basic
URL prefix is matched to previous step persisted
in a table at subscription creation time.
NOTIFICATION SENT TO SUP
If notification persisted = true then notifications
stored in gateway for later PULL and not sent to
SUP.
NOTIFICATIONS STORED IN GATEWAY SM59 Destination
Target Host: 10.1.1.55
Service No: 8000
Path Prefix: /GWC/SUPNotification
SUP looks at application connection table and
compares with the full URL used.
DEVICE & USER FOUND
SUP checks if user/application is online or offline.
SUP checks if offline connectivity settings exist.
APNS etc.
NOTIFICATION SENT TO DEVICE
Application loaded in foreground.
ONLINE NOTIFICATIONS RETRIEVED FROM SUP
5. Receive Notification Client accepts response in specific method if
online. Client accepts response from proprietary
messaging service. APNS etc. Client may call
notification service if PULL scenario chosen
NOTIFICATION ACCEPTED
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 51
11. Communication Architectures (Device Specific)
The communications between SUP and device in online mode utilize HTTP/s however what we have not discussed thus far is the use of 3rd party device specific messaging services such APNS or BES. The following diagram illustrates the relationship between SUP and the device specific architectures. The first step in the process flow dictates that these settings must be maintained against the application connection properties. For more detailed configuration steps please see the relevant How-‐To guide for each device.
Apple and Blackberry notification services are supported however at this point in time (Gateway SP3 & SUP 2.1.1) Android C2DM is not supported. Also the intention for using APNS and NOC is to not channel the payload through this mechanism but rather trigger the application to load in foreground and perform an online notification against the pending device specific queues.
How-‐To…Subscription & Notification with SAP NetWeaver Gateway -‐ Android
April 2012 52
12. Appendix – Subscription Collection
The subscription collection bound to you enabled Gateway service follows the same principal as any Gateway service. This means that a user or application can Query, Create, Read, Update and Delete subscriptions simply by using the combination of URL, HTTP verb and payload.
Action HTTP Verb Request Payload Sample URL
Query GET Empty …/SubscriptionCollection
Read GET Empty …/SubscriptionCollection(‘ID=1323098ASDAS’)
Create POST Subscription Entity …/SubscriptionCollection(‘ID=1323098ASDAS’)
Delete DELETE Empty …/SubscriptionCollection(‘ID=1323098ASDAS’)
Update PUT Subscription Entity …/SubscriptionCollection(‘ID=1323098ASDAS’)
www.sap.com/contactsap
www.sdn.sap.com/irj/sdn/howtoguides