How To Enable Subscription Push Scenarios with SAP ...€¦ · How To Enable Subscription Push Scenarios with Gateway and Business Object Eventing June 2011 1 1. Introduction SAP

SAP NetWeaver How-To Guide

How to Enable Subscription Push Scenarios with SAP NetWeaver Gateway and Business Object Eventing

Version 2.0

June 2011

Authors:

Andrew Whitaker, SAP Customer Solution Adoption (CSA)

© Copyright 2011 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, Outlook, and PowerPoint are

registered trademarks of Microsoft Corporation.

IBM, DB2, DB2 Universal Database, OS/2, Parallel

Sysplex, MVS/ESA, AIX, S/390, AS/400, OS/390,

OS/400, iSeries, pSeries, xSeries, zSeries, z/OS, AFP,

Intelligent Miner, WebSphere, Netfinity, Tivoli, Informix,

i5/OS, POWER, POWER5, OpenPower and PowerPC are

trademarks or registered trademarks of IBM Corporation.

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.

MaxDB is a trademark of MySQL AB, Sweden.

SAP, R/3, mySAP, mySAP.com, xApps, xApp, SAP

NetWeaver, 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 in several other countries all over the world.

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.

These materials are subject to change without notice.

These materials are provided by SAP AG and its affiliated

companies ("SAP Group") for informational purposes only,

without representation or warranty of any kind, and SAP

Group shall not be liable for errors or omissions with

respect to the materials. The only warranties for SAP

Group products and services are those that are set forth in

the express warranty statements accompanying such

products and services, if any. Nothing herein should be

construed as constituting an additional warranty.

These materials are provided “as is” 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 not be liable for damages of any kind including

without limitation direct, special, indirect, or consequential

damages that may result from the use of these materials.

SAP does not warrant the accuracy or completeness of the

information, text, graphics, links or other items contained

within these materials. 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 NetWeaver “How-to” Guides are intended to simplify

the product implementation. 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

2.00 Gateway 2.0 Updates

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

2. Business Scenario .................................................................................................................. 2

3. Prerequisites ........................................................................................................................... 3

4. Step-by-Step Procedure ......................................................................................................... 4 4.1 Create a Gateway Object to Read a Backend Business Object .................................. 5 4.2 Configure the Backend Event Publisher ....................................................................... 6

4.2.1 Communications from the Backend to Gateway .............................................. 6 4.2.2 Define a Backend Event ................................................................................. 12 4.2.3 Assign Backend Event to Preset Business Object Repository Event ............ 13

4.3 Configure Gateway ..................................................................................................... 15 4.3.1 Enable communication between Gateway and Backend ............................... 15 4.3.2 Assign Backend Events to existing Gateway Object ..................................... 17 4.3.3 Add Gateway Object to Subscription Context ................................................ 18 4.3.4 Add the Subscription Object to Gateway Business Object Group ................. 19 4.3.5 Update Gateway Data Model for Subscription ............................................... 20 4.3.6 Update Gateway Consumption Model for Subscription & Notification ........... 21 4.3.7 Maintain Destinations for Client Notifications ................................................. 23 4.3.8 Enable Consumers ......................................................................................... 24

4.4 Executing the scenario ............................................................................................... 26 4.4.1 Create subscription ........................................................................................ 26 4.4.2 Trigger Event .................................................................................................. 29 4.4.3 Receive notification ........................................................................................ 31 4.4.4 Optional – List Subscription ........................................................................... 33 4.4.4 Optional – Subscription Detail ........................................................................ 34 4.4.5 Optional – Delete Subscription ....................................................................... 35

5. Appendix ................................................................................................................................ 36 5.1 Tracing ........................................................................................................................ 36 5.2 Payload Push ............................................................................................................. 38

5.2.1 Defining you XNotification Structure .............................................................. 38 5.2.2 Binding your new XNotification structure to the Gateway Consumption

model ............................................................................................................. 38 5.3 Transaction Map - Gateway ....................................................................................... 40 5.4 Transaction Map – Backend ....................................................................................... 41

How To Enable Subscription Push Scenarios with Gateway and Business Object Eventing

June 2011 1

1. Introduction SAP NetWeaver Gateway has two approaches to developing REST enabled services. The first is known as the Generic Channel and requires the adaptation in the Gateway server. This is enabled through the use of a generaton tool leveraging BOR, RFC and Screen Scraping. Subscription and notiication is supported in the Generic Channel utilizing the BOR generation tool and BOR events from the respective backend. This scenario will be the focus of this document. The other approach is the OData Channel. This is a programmatic approach and requires adaptation in the backend with only minimal configuration in the Gateway server. The added overhead of programming is offset by the impressive level of flexibility giving the developer complete control of the service being created. See bottom right corner of the illustration below.

For more information on the Odata Channel including subscription and notification please refer to SDN for appropriate How-To Guides and supporting information. The following documentation links will be of help and should be referenced frequently.

• SAP Official Documentation: http://help.sap.com/content/documentation/netweaver/docu_nw_gateway_design.htm

• SAP NetWeaver Gateway on SDN:

http://www.sdn.sap.com/irj/sdn/gateway

• SAP Netweaver Gateway How-To Guides: http://www.sdn.sap.com/irj/sdn/gateway?rid=/webcontent/uuid/c0a638d0-8478-2e10-8eb4-f157b64fb221


June 2011 2

2. Business Scenario With SAP Gateway 1.0 you can now subscribe to Business Object events using RESTful services. This integration between Gateway and SAP Business Objects enables event notifications to be pushed in SAP Data Protocol format to a given client at a specified URL. The following diagram highlights the process at execution followed by a step by step description. In this document we shall use the SAP ECC Material to demonstrate such a scenario. Any business repository object with supporting events can be used. It is important to note the client may be an application itself or any REST enabled device or service.

Execution Step Client Gateway Backend

Client issues a BO event subscription create HTTP Post

Gateway accepts BO event subscription request

Gateway persists subscription

Gateway routes request to Backend Event Publisher

Backend accepts BO event subscription request

Backend persists subscription

User triggers BO event via normal system usage.

Backend Event Publisher sends event to Gateway

Gateway accepts event

Gateway identifies subscribers

Gateway converts event to SAP Data Protocol notification

Gateway sends notification to requested URL

Client accepts HTTP notification and performs follow on activities.


June 2011 3

3. Prerequisites The following are required to be installed or ready before using this How-To Guide: • A Gateway object must already have been created calling a business object from a backend

with at least one method of type “read” or “getlist”. For more information please refer to the “How to Guide” called “How To... Create CRUD Operations in Gateway”

• Administrator access to a Gateway 2.0 system. • A SAP ERP system (referred as backend in this document). Corresponding Gateway 2.0

packages installed. • Trust relationship has already been setup between Gateway and the backend. For detail on how

to setup trust relationship, please refer to the online manual below: http://help.sap.com/saphelp_nw70ehp2/helpdata/en/f8/18da3a82f9cc38e10000000a114084/frameset.htm

• Firefox with REST Client installed for testing the RESTful services. • A HTTP trace tool to capture the notification posted from the Gateway Server.

For more information on the steps mentioned in this document and other development activities please reference the official Gateway Development Guide.


June 2011 4

4. Step-by-Step Procedure The scenario detailed in this document has four major configuration steps. The first is a pre-requisite to set up a business object Gateway with at least a read operation. Following this we move into the backend to configure the business object and event creation. In our example we will use the material object create event which is associated to the material create transaction “MM01”. After this step we configure the gateway application to accept subscriptions and notification and bind them to the material backend object. Finally the last step is test the scenario using a REST client to create a subscription, a backend transaction to create the material and resulting event then use a HTTP trace tool to capture the notification, which concludes the scenario.

Step Client Gateway Backend

Create a Gateway Object to read a Backend Business Object

Configure the Backend Event Publisher

• Communications from the Backend to Gateway • Define a Backend Event • Assign Backend Event to Preset Business Object

Repository Event

Configure Gateway Object for subscription and notification

• Enable communication between Gateway and Backend • Assign Backend Events to existing Gateway Object • Add Gateway Object to Subscription Context • Add the Subscription Object to Gateway BO Group • Update Gateway Data Model for Subscription • Update Gateway Consumption Model for Subscription • Maintain Destinations for Client Notifications • Enable Consumers

Execute the Scenario

• Create Subscription • Trigger Event in Backend • Receive Notification • Optional - List Subscription • Optional - Delete Subscription

For more information on the steps mentioned in this document please reference the Gateway Development Guide.


June 2011 5

4.1 Create a Gateway Object to Read a Backend Business Object

It is important to reiterate that push notifications and subscription of backend business objects is dependent on an existing gateway object which implements either a “read” or “getlist” method of an object from the Business Object Repository (BOR). This document does not detail these steps however the following table summarizes the approach.

For more information please refer to the “How to Guide” called “How To... Create CRUD Operations in Gateway”.

Step Client Gateway Backend

Create a Gateway Object to read a Backend Business Object

• Configure Backend Connectivity • Use Transaction /IWFND/GWO_GEN or SE80 • Create a Gateway Data Model • Select BO from Screen • Highlight Method Required • Create Mapping • Generate • Create a Gateway Consumption Model in SE80 • Add Gateway Model/Object from previous • Execute

For the purpose of this document we the following objects were developed as per this step and the mentioned documents. They will be referenced in subsequent sections and hence are worth noting.

Object Name

Gateway Data Model / Object in TX : /IWFND/GWO_GEN Z_ASW_MATERIAL

Backend System ECC

BOR Object Used Material : BUS1001

BOR Method Implemented GetList / GetDetail

Gateway Consumption Model Z_ASW_MATERIAL_0001

External Name ASW

Sample URL for Application

http://server:port/sap/opu/sdata/sap/ASW?sap-client=100&$format=xml


June 2011 6

4.2 Configure the Backend Event Publisher The Backend Event Publisher is a component that you enable in your existing SAP system to handle the events and actions activated in the SAP system and to publish these events and actions through Project Gateway. For our scenario we shall configure the Backend Event Publisher to create notifications when a standard Material is created using transaction „MM01“. The table below highlights the approach.

Configure the Backend Event Publisher Client Gateway Backend

• Communications from the Backend to Gateway • Define a Backend Event • Assign Backend Event to Preset Business Object

Repository Event

For a summary of transactions used in this section please see the Appendix: Transaction Map

Backend for more information. Software Requirements The following are the minimum software requirements for using Backend Event Publisher in your SAP system:

• SAP NetWeaver Application Server ABAP 7.0, or higher • SAP ECC 6.0, ECC-DIMP, 600, 0015 (SAPK-60015INECCDIMP), DIMP • Make sure that you have administrator privileges in the SAP system.

Enabling Backend Event Publisher You install the following installation packages to enable Backend Event Publisher:

• On the Project Gateway host, install the package IW_ BEP 200 Gateway. • In your SAP system, install the component, /IW_ BEP.

4.2.1 Communications from the Backend to Gateway Before configuring the actual scenario we need to enable communications between Gateway and the SAP Backend (ECC). This is done using RFC Destinations and the bgRFC protocol. There are two destinations to set up in this section. They are both use background RFC as the protocol and represent one for the bgRFC Supervisor for local communication and another for the actual call to the Gateway Server. The following steps guide you through the configuration of these two destinations.

1. Log on to the Backend system (ECC), go to transaction SM59. 2. Define Supervisor Destination BGRFC_SUPERVISOR with connection Type “3”.


June 2011 7

3. Enter user, password for the logon info. Be reminded that the user you enter needs to at least have authorizations in the SAP_BC_BGRFC_SUPERVISOR role or is assigned with the role.

4. Go to transaction SBGRFCCONF. On the Scheduler App Server tab, click on Create.


June 2011 8

5. Enter a server name with F4 help and save.

6. On Supervisor Destination tab, click on Change Button and enter the RFC Destination created in step 1. Then press the save button.

In the next steps, you will need to configure the Backend Event Publisher (BEP) in the backend system and define the connection between the Backend and Gateway through bgRFC. At runtime the Backend Event Publisher will push events over this RFC Destination into the Gateway server. Note if you have configured other Gateway scenarios such as Workflow Notifications this RFC Destination may already be configured. Please consult your Administrator for more information.


June 2011 9

1. Still in the backend system, go to transaction SPRO. Open the IMG structure SAP Netweaver

SAP NetWeaver Gateway Business Suite Enablement Connection Settings to SAP Netweaver Gateway. Then click on the Activity icon next to Create RFC Destination for Outbound Queues.

2. In the window of Configuration of RFC Connections, click on the Create button.

3. This will bring us to the RFC Destination transaction (i.e. SM59). We now need to create a bgRFC destination. Enter the followings to the corresponding fields and hit ENTER. • RFC Destination: GWDEMO_BGRFC_DEST <or any name you want> • Connection Type: 3 • Description 1: bgRFC for Backend Event Publisher <or your own description>


June 2011 10

4. Under the tab Technical Settings, enter the host info of the system where Gateway is located. • Target Host: < hostname of the Gateway Server > • System Number: < system # of the Gateway Server >

5. Click on the tab Logon & Security. Enter the Logon info for logging on to the Gateway Server. Click on Save to save the changes.

6. Click on the tab Special Options. Under the area of Select qRFC Version, select 1 bgRFC for

qRFC Version.


June 2011 11

7. Click Save. A dialog of “Warning about selection of qRFC version” will be displayed. Click on Yes to proceed.

8. On the bottom of the screen, you should see a message “Destination GWDEMO_BGRFC_DEST saved”. Click on the button Connection Test to test the destination. A successful test should look like below.

9. Go to transaction SPRO and open the IMG structure SAP Netweaver SAP NetWeaver

Gateway Business Suite Enablement Connection Settings to SAP Netweaver Gateway. Click on the Activity icon next to SAP NetWeaver Gateway Settings.

10. In the window of Change View “Gateway Settings”: Overview, click on New Entries. Then enter the followings in the corresponding fields. • Destination System: W64 < i.e. Gateway Server SID > • Client: 100 < i.e. Gateway Server Client > • System Alias: W64_GWDEMO < an unique alias name > • RFC Destination: GWDEMO_BGRFC_DEST < the bgRFC destination created in

step 11 of this section >


June 2011 12

11. Click on Save. Create your Customizing Request when prompted.

4.2.2 Define a Backend Event You define the events and specify the different types of information and data for the events you want to make available in Gateway. In addition, you can define default text items to be sent with the specific event and specify the language for the text. For our scenario we are going to create a general event called “BUS1011_Material_Created”and then bind it later to the actual Business Object Repository Event “Material.Created”.

1. Go back to transaction SPRO. Open the IMG Structure SAP Netweaver SAP Neweaver Gateway Business Suite Enablement Backend Event Publisher Administration. Click on the Activity icon next to Event Definition.

2. In the Change View “Event Definition”: Overview window, select Event definition under Dialog Structure and click on the button New Entries. Enter the following in the Event definition table.

• Event ID: GW_BUS1001_CREATED • Active: <check this to enable the event for Gateway> • Event Description: <enter your description>

3. You can add default text that you want to send together with an event. Adding text to be sent with an event is optional. Your text entry can be in any of the supported languages in the SAP system. Only one text entry per language is allowed. Click on the Event row and then click


June 2011 13

Texts for Event. This allows you to customize the message displayed later when a notification is sent to the end user. The entry seen below would result in a message at runtime such as “Event GW_BUS1001_CREATED : NEW MATERIAL : CREATED”.

4. Click on Save. Create a Customizing Request when prompted.

4.2.3 Assign Backend Event to Preset Business Object

Repository Event You can assign and activate preset business object repository (BOR) events through the Backend Event Publisher. You assign and activate preset BOR event by linking the BOR event to the event you created in the previous step. In addition to this you are able to programmatically call the Backend Event Publisher via an application programming interface. For more information please see the Appendix section entitled “Backend Event Application Programming Interface (API)”. Open the IMG, Backend Event Publisher Administration, and select Event General Definition → Configure BOR Event.

1. Go back to transaction SPRO. Open the IMG Structure SAP Netweaver SAP Neweaver Gateway Business Suite Enablement Backend Event Publisher Administration. Click on the Activity icon next to Event Type Linkages.


June 2011 14

2. The Change BOR Event Configure: Overview window displays a table, Event Type Linkages. Click New Entries:

3. Enter the following information in the relevant fields: • Object Category: “BOR Object Type” • Object Type: “BUS1001” • Event: “CREATED” • Receiver Type: “GW_BUS1001_CREATED” • Receiver Call: “Method” • Class Name: “/IWBEP/BOR_ADAPTER” • Interface Name: “BI_EVENT_HANDLER_STATIC” • Method Name: “ON_EVENT” • Check Function Module N/A • Receiver Type Function Module N/A • Destination of Receiver N/A • Event Delivery: “Using tRFC (Default)” • Linkage Activated: Select it in order to activate • Enable Event Queue: N/A • Behavior Upon Error Feedback: “System defaults” • Receiver Status “No errors”

5. Click Save.


June 2011 15

4.3 Configure Gateway Now the Backend system has been configured we must turn our attention to the Gateway server and complete configuration, binding our scenario to the specific backend event and existing Gateway object. This configuration is limited to RFC Destinations, IMG Gateway settings and SE80 Service Document settings. The table below highlights the approach.

Configure Gateway Object for subscription and notification Client Gateway Backend

• Enable communication between Gateway and Backend • Assign Backend Events to existing Gateway Object • Add Gateway Object to Subscription Context • Add the Subscription Object to Gateway BO Group • Update Gateway Data Model for Subscription • Update Gateway Consumption Model for Subscription • Maintain Destinations for Client Notifications • Enable Consumers

For a summary of transactions used in this section please see the Appendix: Transaction Map

Gateway for more information.

4.3.1 Enable communication between Gateway and Backend ...

The first step is to configure the RFC communications between Gateway and the Backend (ECC). This is done through standard RFC Destination in SM59 followed by an Alias definition in the Gateway IMG configuration.

1. Logon to the Gateway Server. Then go to transaction SM59. You will need to create a RFC destination to the backend system. This may already be created so you should check existing Alias definitions and underlying RFC Destinations. Consult your Administrator for more information. Create a destination with the info below. Save and test the connection to make sure it works. • RFC destination: ERPCLNT400 < or any unique name you want > • Connection Type: 3 • Target Host: < SAP Backend Hostname > • System Number: < SAP Backend Sys Number ##>


June 2011 16

2. Go to transaction SPRO and open the IMG Structure SAP NetWeaver Gateway Gateway

Configuration Connection Settings SAP Netweaver Gateway to SAP System. Click on the Execute icon next to Manage SAP System Aliases.

3. Click on the button New Entries. Define a SAP system alias with info below:

• SAP System Alias: ERP_400 < or any unique name you want > • Description: < any description > • RFC Destination: < choose the RFC destination defined in step 1 >

4. Click on Save.


June 2011 17

4.3.2 Assign Backend Events to existing Gateway Object This step binds the event you configured in the backend with a gateway business object. The gateway object is the one described as a pre-requisite and should already exist in your system.

1. Go to transaction SPRO. In the toolbar click on SAP Reference IMG.

2. Expand the IMG structure to the find the Gateway Subscription setting via the following path SAP Netweaver Gateway Configuration Subscription Settings. Click on the Activity icon Maintain Subscription Settings for GSDO.


June 2011 18

3. Click New Entries and add a row with the following information. • GSDO Type: <Your existing Gateway Business Object> • System Alias: <The Backend Alias you are using> • Event Group ID: <The Event ID configured in the Backend> • Description: <Add anything in the description> • Xnotification Type: “IWF_NOTIFICATION”

4.3.3 Add Gateway Object to Subscription Context This step is a prerequisite for other steps in this section. It effectively allows the F4 list to be populated with your Gateway object and is mandatory to complete this scenario. This is necessary as you may have multiple subscription objects bound to you or scenario and by adding the gateway object ot the subscription context we can support multiple subscription objects.

1. Go to transaction SPRO and expand the IMG structure SAP Netweaver Gateway Development Generic Service Data Object (GSDO). Click on the Activity icon GSDO Types & GSDO Contexts & GSI Implementations.

2. Locate the GSDO object IWF_Subscription. This is a standard Gateway Object that we will bind

to our scenario. We need to click GSDO Type Context from the top left index.


June 2011 19

3. Add an entry in the context list pointing to your Gateway Object created earlier. This will allow us to configure the subscription scenario in the next section.

4.3.4 Add the Subscription Object to Gateway Business

Object Group This step assigns the standard Gateway Object representing Subscription to your scenario. Without this a user is unable to subscribe a given business object.

1. Go to transaction SPRO. Expand the IMG structure to the find the Gateway Subscription setting via the following path SAP Netweaver Gateway Configuration Subscription Settings. Click on the Activity icon Maintain Subscription Routing.

2. In the right hand detail section select the row with your system alias representing the backend you are integrating with. Double Click Assign GSDOs from the left hand index section.

3. In right hand detail section, highlight the row IWF_SUBSCRIPTION and add your Gateway

Business Object to the GSDO Context field. If IWF_SUBSCRIPTION is not in the list you will need to add it by clicking New Entries. If you have multiple Gateway Objects requiring subscription in the same Business Object Group then simply add multiple entries of


June 2011 20

IWF_SUBSCRIPTION with the GSDO Context referencing your many Gateway Business Objects.

4.3.5 Update Gateway Data Model for Subscription This step makes changes to Gateway Data Model to add subscription support. In the prerequisite document for creating a Gateway Business Object CRUD scenario you have to create a service document which results in a valid web application being created which is viewable in the transaction SICF under the nodes /sap/opu/sdata/sap/<your application>.

1. In the pull down options in the left hand index pane select Gateway Data Model. In the text

field underneath enter the Gateway Object previously created from the Business Object CRUD scenario. This entry was created in the transaction /IWFND/GWO_GEN. Please see section Prerequisite section in this document for references to previous scenarios.


June 2011 21

2. Once the index is populated on the left hand side double click on the second node which represents the Gateway Object without the suffix 0001_PS. This will load the right hand side detail information which we will change.

3. In the right hand detail section click on the radio button to enable subscription support.

4.3.6 Update Gateway Consumption Model for Subscription

& Notification This step adds the SAP standard objects for subscription and notification to your consumption model.


June 2011 22

1. Open your Consumption model in SE80. In the pull down options in the left hand index pane select Gateway Consumption Model. In the text field underneath enter the Gateway Consumption Model previously created from the Business Object CRUD scenario. Please see section Prerequisite section in this document for references to previous scenarios.

2. Add Gateway Object /IWFND/SUBSCRIPTION_0001_UC by right clicking on the top node of

the object tree. In this case Z_ASW_MATERIAL_0001. Select Add GW Data Model and enter the following object : /IWFND/SUBSCRIPTION_0001_UC.

3. Add Gateway Object /IWFND/ NOTIFICATION _0001_UC by right clicking on the top node of the object tree. In this case Z_ASW_MATERIAL_0001. Select Add GW Data Model and enter the following object : /IWFND/ NOTIFICATION _0001_UC.


June 2011 23

4.3.7 Maintain Destinations for Client Notifications Before testing the scenario we need to maintain the destination from which a business object event notification will be sent to. This is a security measure and allows cental configuration of not only the destination but also the authentication requirements specific to a single destination.

1 Go to transaction SM59 or use the navigation path seen below. SAP Netweaver

Gateway Configuration Subscription Settings and then click Maintain RFC Destination to Connectivity Provider.

2 Create a new destination of type G “HTTP to External Server” and maintain the URL, Service

and Log on information. Click Save. This could point to your tracing program or http listener. In real world environment this would point to the device infrastructure, which would then forward to any subscribed device etc.


June 2011 24

4.3.8 Enable Consumers This step enables the SAP Data Protocol, which will be used to push notifications to a specific location. This may already have been activated by the system administrator, however it is worth checking to avoid problems during testing.

1. Go to transaction SPRO. Expand the IMG structure to the find the Gateway Consumer

settings via the following path SAP Netweaver Gateway Configuration Consumer Settings. Click on the Activity icon Activate or Deactivate Consumers


June 2011 25

2. Make sure the following entry IWD_SDP is Active. You can F4 the Identifier to see analyze other options relevant to consumers. The SAP Data Protocol is required for our scenario.


June 2011 26

4.4 Executing the scenario After completing the configuration described in the previous section we are now ready to test the scenario. The table below highlights the approach.

Execute the Scenario Client Gateway Backend

• Create Subscription • Trigger Event in Backend • Receive Notification • Optional - List Subscription • Optional - Delete Subscription

4.4.1 Create subscription 1. To issue a subscription request we will use the REST client for Firefox as a test harness for this.

Start Firefox, click on Tools REST Client. In the drop-down box of Method, choose POST. Then enter a URL with the format below in the text field: Syntax: http://<Gateway hostname>:<Gateway host http port> /sap/opu/sdata/sap/<your service document>/SubscriptionCollection

Example: http://usphlrig15.phl.sap.corp:8001/sap/opu/sdata/sap/asw/SubscriptionCollection

Click on the Login button and enter your username and password to login to the Gateway Server. This will add an Authorization header to the request. Click on the Add Request Header button. Add a header:

• Name: x-requested-with • Value: XMLHttpRequest

In the Request Body area, enter an XML like below: <atom:entry xmlns:atom="http://www.w3.org/2005/Atom">

<atom:id/>

<atom:title>This is my title</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://myserver.sap.corp:8080</d:deliveryAddress>

<d:collection>ZAswMaterialCollection</d:collection>


June 2011 27

<d:filter></d:filter>

<d:select></d:select>

</m:properties>

</atom:content>

</atom:entry>

The following table describes the most important XML elements and their meaning in relation to our scenario

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.

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 business object 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>

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.

2. Then click on the Send button to post the subscription request. You should receive a HTTP 201

Created response code, which can be seen in the bottom window detail section. If you do not receive such a response code you may have a subscription already created or there is an issue with the configuration done in the previous sections. Please see the Appendix section “Monitoring and Troubleshooting” for more information.


June 2011 28

Note: If you get an error of “Subscription already exists” from an HTTP response and you want to remove the old subscription please see the List Subscription and Delete Subscription sections following the Receive Notification section.

3. To prove you have created a subscription in the Gateway Server go to transaction SE11 and view the contents of table /IWFND/D_SUB_CNT. You should see an entry representing your newly created subscription.


June 2011 29

4. To prove you have created a subscription in the Backend ECC Server go to transaction SE11

and view the contents of table /IWFND/D_SUB_CNT. You should see an entry representing your newly created subscription.

4.4.2 Trigger Event Now that we have created a subscription successfully and verified it has been propagated from the REST client to Gateway and into the relevant Backend, we can trigger the actually Business Object event.

1. Log into the Backend where the SAP Business Object resides. In our case it is ECC. As we have configured our scenario to create events on Material create, we need to actually create a material. Go to transaction MM01.

2. If you are using an IDES system you can follow the screen shot below and create a simple non stock material. Please consult a Material Management resource to assist you if you cannot create a Material. Sometimes there may be dependent configuration which may restrict you created a material of a certain type or sector. Hit Enter if any warnings are displayed.


June 2011 30

3. You should be faced with the material view selection which enables you to create different sub sections of a material. Please select Basic Data 1 only to avoid complexity and background functional restrictions. Click the Tick Button at the bottom left corner of the dialogue box.

4. You should see the material overview screen. Please add a simple description and a Unit of

Measure as per the screen shot below. Click Save.

5. As a result the material will be created in ECC and as per our configuration in the Backend Event Publisher an event will be published to the Gateway server via BgRFC. From Gateway


June 2011 31

it will read the subscription information and determine the relevant subscribers and the URL for notification via HTTP.

4.4.3 Receive notification A notification will be sent from Gateway to the URL specified in the original subscription create HTTP POST. For testing purposes you could run a trace on the specified location which would be a web server etc. In our scenario I have used a simple HTTP trace program implemented in java. See below for setting up this program.

1. Download the a HTTP Trace program such as http://httptrace.sourceforge.net/httptrace.zip

2. Unzip the files to a location which can has access to the java executable. SAP takes no responsibility for this application and recommends consulting your system administrator for compliance with organizational policies. You could simply create a subscription with the deliver address element pointing to a web server and set up tracing or logging on your own web server.

3. Run the HttpTrace java program and configure the trace to listen on a free port and forward to an existing web server. Note the free port must correspond to the DeliveryAddress element in your subscription creation HTTP Post done earlier.

4. Once a notification has been sent at runtime you will see it hit the trace program and display as

per the following. Note you may need to create more materials as the events are processing in real time.


June 2011 32

5. To demonstrate the content of the notification the xml has been saved to a separate file and can

be seen below.


June 2011 33

4.4.4 Optional – List Subscription

1. To get a list of subscriptions issue a GET request to the following URL: Syntax: http://<Gateway hostname>:<Gateway host http port>/sap/opu/sdata/sap/<service document>/<your bo>Collection

Example: http://usphlrig15.phl.sap.corp:8001/sap/opu/sdata/sap/asw/SubscriptionCollection

You should receive an xml representation of your subscriptions similar to below.


June 2011 34

4.4.4 Optional – Subscription Detail

1. To retrieve detail of an existing subscription please follow the below syntax in the REST client with the HTTP method of GET.

Syntax: http://<Gateway hostname>:<Gateway host http port>/sap/opu/sdata/sap/<service document>/<your bo>Collection(value='[Subscription GUID ]',scheme_id='IWF_SUBSCRIPTION',scheme_agency_id='[Scheme Agency ID]')

Example: http://usphlrig15.phl.sap.corp:8001/sap/opu/sdata/sap/asw/SubscriptionCollection(value='0019BBC8B15E1EE08FDFF5A31853201C',scheme_id='IWF_SUBSCRIPTION',scheme_agency_id='ERP_400')

Element Description

Subscription GUID The actual GUID of your subscription. This is the one in the SE11 table mentioned before and can also be retrieved by using the collection method with GET shown in the previous section.

Scheme Agency ID Backend Alias


June 2011 35

4.4.5 Optional – Delete Subscription

1. To delete an existing subscription please follow the below syntax in the REST client with the

HTTP method of DELETE.

Syntax: http://<Gateway hostname>:<Gateway host http port>/sap/opu/sdata/sap/<service document>/<your bo>Collection(value='[Subscription GUID ]',scheme_id='IWF_SUBSCRIPTION',scheme_agency_id='[Scheme Agency ID]')

Example: http://usphlrig15.phl.sap.corp:8001/sap/opu/sdata/sap/asw/SubscriptionCollection(value='0019BBC8B15E1EE08FDFF5A31853201C',scheme_id='IWF_SUBSCRIPTION',scheme_agency_id='ERP_400')

Element Description

Subscription GUID The actual GUID of your subscription. This is the one in the SE11 table mentioned before and can also be retrieved by using the collection method with GET shown in the previous section.

Scheme Agency ID Backend Alias

2. The resulting HTTP response should be a 204 No Content as seen from the screenshot below.

Note you can check the tables in both ECC and Gateway to test if the subscription has been deleted.


June 2011 36

5. Appendix

5.1 Tracing When testing your scenario is a possibility that a configuration step may not have been completed or the scenario just does not work. If this does occur we recommend increasing the trace configuration settings so you can see what is happening at runtime. For Gateway information please use the standard application log with transaction SLG1. The following procedure highlights how to increase tracing or logging for Gateway runtime diagnostics.

1. Go to transaction SPRO. In the toolbar click on SAP Reference IMG.

2. Expand the IMG structure to the find the Gateway Subscription setting via the following path Cross-Application Components Project Gateway Project Gateway Administration Logging Settings. Click on the Set Log level for All Users

.


June 2011 37

3. For each entry in the table change the logging to the required level.

4. Test your scenario again and look at the application log with SLG1 for more information.


June 2011 38

5.2 Payload Push In Gateway 2.0 it is possible to modify or extend the notification structure sent back to the subscriber to add your own properties and/or add the business object as part of the payload. The application is responsible for authorization checks. For more information please consult the documentation at the following location:

• Enabling the Payload Push Scenario in Your Application: http://help.sap.com/saphelp_gateway20/helpdata/en/56/d0cc05b564411e841141f68294e29f/frameset.htm

5.2.1 Defining you XNotification Structure You must explicitly define the format of your XNotification in the SAP NetWeaver Gateway system. Each XNotification must inherit from the basic notification IWF_NOTIFICATION. The following options may be used simultaneously:

1. Extend the basic notification structure with additional properties to contain business data.

2. Define the relation to the subscribable Data Model, to indicate that the whole GSDO is to be sent along with the notification:

Both options are performed In SE80 to model your own XNotification Gateway Object inheriting from the default base notification one /IWFND/OM_NOTIFICATION_0001_PS.

5.2.2 Binding your new XNotification structure to the

Gateway Consumption model You must explicitly define the format of your XNotification in the SAP NetWeaver Gateway system. Each XNotification must inherit from the basic notification IWF_NOTIFICATION. The following options may be used simultaneously:


June 2011 39

Assign XNotification to your Gateway object


June 2011 40

5.3 Transaction Map - Gateway

IMG Gateway

System Alias

Consumer Types

RFC Destination

RFC Destination

BO Context Routing

Backend Event

Binding

SE80 Consumptio

n Model

SE80 Gateway Object


June 2011 41

5.4 Transaction Map – Backend SPRO

Backend Event

Publisher

Gateway Settings

bgRFC Supervisor

bgRFC Supervisor Destination

RFC Destination Outbound

Queue

Event BO Linkage

Event Definition

Event Text Variables

Event Linkage Method

Documents

How To Enable Subscription Push Scenarios with SAP ...€¦ · How To Enable Subscription Push Scenarios with Gateway and Business Object Eventing June 2011 1 1. Introduction SAP