Create a Gateway Service Using the Bor Generator Advanced

SAP NetWeaver

How-To Guide

How To... Create a Gateway Service

Using the BOR Generator - Advanced

Scenario

Applicable Releases:

SAP NetWeaver Gateway 2.0 SP03

Version 2.0

February 2012

© 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, 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 Updated to reflect changes introduced in SP03

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

3. Prerequisites ........................................................................................................................ 1

4. Step-by-Step Procedure ...................................................................................................... 3

4.1 Create the Data Model based on BOR Object Data Sources ...................................... 3

4.2 Map the QUERY Operation .......................................................................................... 6

4.3 Map the READ Operation ........................................................................................... 13

4.4 Create a Consumption Model ..................................................................................... 17

4.5 Test the QUERY and READ Operations .................................................................... 18

4.5.1 View the Metadata ......................................................................................... 18

4.5.2 Configure a System Alias for the Service ...................................................... 20

4.5.3 Test the QUERY Operation ........................................................................... 21

4.5.4 Test the READ Operation .............................................................................. 25

4.6 Map the CREATE Operation ...................................................................................... 26

4.7 Map the UPDATE Operation ...................................................................................... 28

4.8 Map the DELETE Operation ....................................................................................... 30

4.9 Test the CREATE, UPDATE, and DELETE Operations............................................. 31

4.9.1 Test the CREATE Operation.......................................................................... 31

4.9.2 Test the UPDATE Operation.......................................................................... 34

4.9.3 Test the DELETE Operation .......................................................................... 36

5. Summary ............................................................................................................................ 37

How To... Create a Gateway Service Using the BOR Generator - Advanced Scenario

February 2012 1

1. Business Scenario

Maintaining users in an SAP system is one of the most common tasks for SAP system administrators.

In fact, transaction SU01 is one of the most actively used transactions among all SAP customers.

Many Business APIs (BAPIs) for the User object are available in any SAP NetWeaver AS ABAP

system which includes all the SAP Business Suite applications.

The Business Object Repository (BOR) is the central access point to the SAP business object types

and their associated BAPIs. With SAP NetWeaver Gateway, these BOR objects can be leveraged as

data sources so that simplified REST based services can be called to maintain business entities from

virtually any device or client application which could make tasks, such as user maintenance, easier for

SAP administrators.

This How-To Guide provides details on how to create and test an SAP NetWeaver Gateway service

based on the User related BOR objects. As a result, CRUD (CREATE, READ, UPDATE, and

DELETE) operations can be executed using the Gateway service to maintain users in an SAP system.

The User example can then be extended for other business entities with similar associated BOR

objects in an SAP application.

2. Background Information

SAP NetWeaver Gateway provides the capability to generate content automatically without the need

to write any code. A Gateway specific design time tool is offered in the ABAP Development

Workbench (transaction SE80) to create Gateway Data Models to design and maintain the content of

the service based on existing data sources, such as Remote Function Calls (RFCs), Screen Scraping,

and Business Object Repository (BOR) objects. A Consumption Model is then created to expose the

content to be consumed as an OData service adhering to REST (Representational State Transfer)

based principles.

Information in this document details this approach of creating the appropriate data model and

generating all the necessary model and runtime code. New in SP03 is the ability to generate the code

based on the OData channel.

This is not to be confused with the OData Channel approach, which is another means of building and

exposing SAP content offered by SAP NetWeaver Gateway that provides developers more control and

flexibility. Although this approach is not covered in this guide, detailed coverage of this topic is

available in other How-To Guides on the SAP Community Network (SCN).

For more information on these topics, refer to the following:

SAP NetWeaver Gateway Developer Guide

SAP NetWeaver Gateway Page on SCN

SAP NetWeaver Gateway How-To Guides on SCN

More information on OData can be found at http://www.odata.org.

3. Prerequisites

The following are the prerequisites to complete the steps in this guide:

Access to a configured SAP NetWeaver Gateway 2.0 SP02 system

Proper permissions in the system (Gateway and SAP backend system).

If the User objects are in another SAP backend system, you need valid connection configuration

from Gateway to that backend

http://help.sap.com/saphelp_gateway20sp02/helpdata/en/56/d0cc05b564411e841141f68294e29f/frameset.htm

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

http://www.sdn.sap.com/irj/sdn/gateway?rid=/webcontent/uuid/c0a638d0-8478-2e10-8eb4-f157b64fb221

http://www.odata.org/


February 2012 2

Firefox and the Firefox REST add-on for testing.

Other REST clients (e.g. WFetch) can be used as well, but the instructions in this guide are

specifically for the Firefox REST client.

Familiarize yourself with the specific BAPI you want to use. Refer to the function module

documentation for the specific BAPI in transaction SE37.

If you are using Internet Explorer to test the QUERY and READ operations as specified in this

guide, make sure it is not configured to show “friendly error messages”.

To configure, go to Tools Internet Options Advanced Uncheck “Show friendly HTTP

error messages”. This will help you analyze any errors if they occur.

Additional Information

SAP NetWeaver Gateway on SAP Help Portal

SAP NetWeaver Gateway Page on SCN

Note 1574568 - SAP NetWeaver Gateway 2.0 - Known Constraints

http://help.sap.com/saphelp_gateway20sp02/helpdata/en/57/a41787789c4eca867d9a09696fc42c/frameset.htm

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

https://service.sap.com/sap/support/notes/1574568


February 2012 3

4. Step-by-Step Procedure

The following steps guide you through the process of creating and testing a Gateway service based on

methods of the BOR User object. Given that the SAP User BOR objects are available in any SAP

NetWeaver AS ABAP based system, this exercise can be done based on User data that exists locally

in the SAP NetWeaver Gateway system or user data that resides in another backend SAP Business

Suite system.

4.1 Create the Data Model based on BOR Object

Data Sources

The Gateway Data Model you create contains the operations you want to perform at runtime, mapped

to specified data and attributes. At runtime, this Data Model is exposed to SAP NetWeaver Gateway

services to invoke the operations that you defined at design time, returning data to the end user. ...

1. Logon to the Gateway system and go to the ABAP Development Workbench – transaction

SE80.

2. In the Object Navigator, choose the object type GW Data Model from the drop down.

3. Enter Z_USER_BOR_<XX> as the name of the Data Model and click on the Display (eye

glasses) button. Replace <XX> with some unique identifier (e.g. your initials or student

number).

4. If prompted to find the model, just click to continue.


February 2012 4

5. Select Yes when prompted to create the Data Model object.

6. In the Create Data Model dialog, press F4 in Type and select PS (for Public Solution model) as

the data model type, and then select Generate from Data Source Object. Click the icon, to

continue.

7. Enter a Description, and in Data Source Type select 0 BOR.

8. In System Alias, press F4 and choose a system alias according to where the User object data

resides – locally or in another backend system. In this example, the backend is IDD_800.

9. Click Continue.


February 2012 5

10. Specify a package to which your objects can be saved for transport purposes. Select an

appropriate package or select Local Object to save as local objects that will not be transported.

11. You should now be navigated to the Create Data Model screen where the actual Gateway data

modeling process takes place.


February 2012 6

4.2 Map the QUERY Operation

Use the QUERY operation to get a list of the business objects to map to your Gateway Service. In this

step you will map the QUERY operation based on the GetList BOR method. ...

1. From the Data Source screen, under the Alphabetical tab, find the USER object and expand it.

2. Select GetList from the list.

3. Select the Create Mapping button, from the right hand side.


February 2012 7

4. Choose Query for the Operation Type.

Now we will map specific fields from the BOR method to our Query operation. First, we can set a

constant value for MaxRows.

5. Right-click on MaxRows to highlight it (left-clicking will uncheck the attribute!). Then select the

Set Constant Value button.

Note

BAPIs and RFCs (which are the basis for these BOR methods) that supply a MaxRows or similar import parameter also allow for an option to limit the number of items returned from the consumption side at runtime. To do so, the client can include the $top query string parameter

according to OData specifications (e.g. $top=5).

If a constant is set for MaxRows and the $top parameter is also provided, the value for the $top parameter will take precedence. For example, in order to prevent a large query result, a constant value can be set for MaxRows, for example, set to 100. If a larger result set is required, the $top parameter can be specified in the request.

6. Set the value to '100' (include the single quotes!) and click to continue.

7. Next set another constant using 'X' for the attribute WithUsername.

Setting this attribute with the constant results in the inclusion of the name field values (i.e.

FIRSTNAME, LASTNAME, FULLNAME) in the query results.

The mapping should appear as in the image shown below:


February 2012 8

8. Uncheck the nodes RETURN and SELECTION_EXP. Now your mapping should look as shown

in the image below:

9. Click to continue and close the mapping window.

A key field must be designated for the data model. For BOR data sources (as opposed to RFC data

sources), Gateway takes care of this automatically. Back on the main data model screen, you can see

that USERNAME has been designated to serve as the key property for the data model.

We also want to add a couple of properties to our Gateway Data Model to leverage the use of SAP

range tables when querying for user data. This basically allows for additional filtering capabilities or

selection critieria when searching for particular users in the system.


February 2012 9

10. Right-click on root node Z_USER_BOR_<XX> and select Add Property.

11. Create the new property called USERID of type Edm.string with an appropriate label as shown in

the image below:

12. Click Continue.

13. Add another property called ISLOCKED of type Edm.string with an appropriate label as shown in

the image below:


February 2012 10

14. Click Continue.

Now you should see both new properties in the Data Model.

Now we want to adjust the Query mapping to take advantage of the supplied range table in the BAPI.

15. Select the QUERY operation and click the Change Mapping button.

16. Make sure the SelectionRange node is checked. Select it and click the Set Range Table button.

17. In the Map Range Table window, click on Add.

18. Select USERID and click to continue.


February 2012 11

19. Back in the Map Range Table window, delete the value P from the Semantic column for the

PARAMETER attribute (you will have to place the cursor in the field and delete it manually) and

set the constant value 'USERNAME' (include the single quotes!).

20. Add two more range table parameters – one with a mapping route through the ISLOCKED

attribute and another through the LASTNAME attribute.

Note that you will have to double-click into each mapping route parameter to set the respective

range table attribute.

For ISLOCKED, set the range table attributes as follows:


February 2012 12

For LASTNAME, set the range table attributes as follows:

Note

The permitted range table values for the PARAMETER and FIELD attributes can be found in the function module documentation for BAPI_USER_GETLIST in transaction SE37.

21. Click to close the Map Range Table window and click again to close the Map

Operation window. You should now be back in the Create Data Model main screen.

22. Now it is time to generate your data model. Click on the Generate button near the top left

corner.

Note

There is no option to save your data model. In order to save your work, you must generate it. Also, you will need to be a registered developer in your system to be able to generate successfully.

23. Upon successful generation, you should see the following:

_USERNAM E” includes the name of the user in the r


February 2012 13

4.3 Map the READ Operation

Use the READ operation to get the details of a particular business object to map to your Gateway

Service. In this step you will map the READ operation based on the GetDetail BOR method.

1. In the list of USER methods, find and select GetDetail.

2. With the method highlighted, click on the Create Mapping button.

3. Select Read as the Operation Type.

Note

You will notice that the GetDetail BOR method is rather complex, containing a large number of structure and table parameters. One of the significant benefits of Gateway is the capability to adapt and simplify such complex SAP interfaces so that external clients can easily consume SAP business data. In the following steps, this complex BOR method will be greatly simplified for easier consumption.

Since there are many more data nodes that will not be used, it will be easier to deselect everything

and then reselect the ones we will use.

4. Uncheck the root node GetDetail.

You will receive the following warning, but that‟s ok. Click Yes to continue.

5. Click the Collapse All button.

6. For now, only check the nodes CACHE_RESULTS, USERNAME, Activitygroups, and Profiles.


February 2012 14

7. Expand the Address node and check attribute TITLE_P (do not check the ADDRESS node itself

– this will be done automatically). Then click the Change Mapping Route button.

8. Map TITLE_P to the root node by highlighting it and changing its name to TITLE.

9. Click on to continue. The mapping so far should appear as shown in the image below:

10. Still under the Address node, select FIRSTNAME, LASTNAME, and FULLNAME.

As you can see, these are matched and mapped automatically to existing properties under the

root node in the data model. They exist due to the work done previously for the QUERY

operation.

We want to “flatten” the remaining ADDRESS attributes by changing the mapping routes so that they

fall under the root node and not within the ADDRESS node.

11. Select the following attributes and change their mapping route to the root node. Also, rename

them to the mapping route value if different (Hint: Look at the TITLE_P example in steps 7 to 9).


February 2012 15

Attribute Mapping Route

LANGU_P LANGUAGE

DEPARMENT DEPARMENT

COMM_TYPE COMM_TYPE

NAME NAME

CITY CITY

COUNTRY COUNTRY

REGION REGION

TEL1_NUMBR TELEPHONE

E_MAIL E_MAIL

The final result for the Address node should look as shown in the image below:


February 2012 16

12. Expand the Activitygroups and Profiles nodes, then rename and set their properties as shown

below. Notice that they are renamed but are kept under their respective nodes (i.e. do not map

them to the root node).

13. Click the icon to close the Map Operation window

14. Within the Data Model section on the lower right, scroll to the bottom to find the

ACTIVITYGROUPS and PROFILES object nodes with cardinality 0..n.

A key has to be set for objects with cardinality 0..n.

15. Expand ACTIVITYGROUPS, right-click on ROLE and choose Set Key.

16. Do the same for PROFILES by setting PROFILE as key.

17. Generate your data model. You should see success messages in the logs.


February 2012 17

4.4 Create a Consumption Model

Now that some of the Data Model has been created, the associated content is ready to be exposed to

the outside world and consumed as an OData service adhering to REST based principles. This is

done by creating a Consumption Model. Once a consumption model is created, the Gateway service

is exposed via the Internet Communication Framework (ICF). ...

1. Proceed to the ABAP Development Workbench (transaction SE80).

Tip

If you are currently in the data modeling tool, you can navigate back to SE80 using the Object Navigator button.

2. Expand node Z_USER_BOR_XX_0001_PS if necessary. Right-click on Related GW

Consumption Models and select Add Consumpt. Model.

Tip

Here we are creating the consumption model by adding it to an existing data model.

It is also possible to initiate the creation of a consumption model on its own by selecting object type GW Consumption Model.


February 2012 18

3. For the Identifier, enter z_user_bor_<XX> (it will automatically convert to upper case) and

click on to continue.

4. Select Yes to confirm the creation of the consumption model.

5. Enter a description and click to continue.

6. Save the object to a package or as a local object (package $TMP).

4.5 Test the QUERY and READ Operations

In order to test the service operations, a simple HTTP client tool is required. In this guide, Firefox (with

REST add-on) will be used as an example, but there are other tools available such as WFetch from

Microsoft. Either of these can be downloaded for free. The following steps assume that have the

Firefox browser and have installed the REST Client add-on.

4.5.1 View the Metadata

When the Data Model is created, you can get a good description of the resulting service and its data

format by looking at the service metadata. This can be done after the consumption model is created.

1. Expand the Related GW Consumption Models node and double-click on your consumption

model, Z_USER_BOR_XX_0001.


February 2012 19

2. To view the metadata, click on the Metadata button.

This launches the default browser and displays the service metadata document in EDMX

format. It also describes the service in Entity Data Model terms according to OData

specifications.


February 2012 20

Note

The XML button will also launch a browser window and display what‟s called the “Service Document”. The service document is the entry point for an OData service and provides information on all the collections of resources available and the relative links to the resources.

For a detailed breakdown of the Service Document and Service Metadata document, refer to How To Write an OData Channel Gateway Service. Part 1 - The Model Provider Class.

Note

Notice the string “Z_USER_BOR_XX” in the URL.

http://<GatewayHost>:<port>/sap/opu/odata/sap/Z_USER_BOR_XX/

$metadata

This is the service name that was specified when creating the consumption model. Also take

note of the “$metadata” string needed to access the service metadata document.

4.5.2 Configure a System Alias for the Service

Starting with SP03, a system alias must be configured for OData channel based data models to

identify which backend system will process the OData. ...

1. Using transaction SPRO, select SAP Reference IMG and navigate to SAP Customizing

Implementation Guide SAP NetWeaver Gateway OData Channel Administration

General Settings Assign SAP System Aliases to OData Service

http://www.sdn.sap.com/irj/sdn/go/portal/prtroot/docs/library/uuid/109c15ed-d8a3-2e10-7c9f-dcb1168aa1ff


February 2012 21

2. Choose New Entries.

3. Under Service Doc. Identifier, enter the name of your data model – Z_USER_BOR_XX_0001.

For SAP System Alias, use F4 to select the appropriate backend alias for this service. For

example, IDD_800. You can press <Enter> to validate your entries.

Since there‟s only one entry right now, the default system checkbox can be checked or left

blank.

4. Save your system alias configuration.

4.5.3 Test the QUERY Operation

Actual testing of the Gateway service can start with the Query operation. The Query operation can

potentially return large sets of data. To address this, Gateway provides mechanisms to restrict the

number of results as well as the capability to filter query results according to mapped selection criteria.

Executing the Main Query Operation

To execute the Query operation, let‟s use the Firefox REST client.

1. Open up the Firefox REST client (you can find it under the Firefox Tools menu).


February 2012 22

2. The Query operation URL is similar to the URL used to get the metadata. In the URL, replace

the string “$metadata” with z_user_bor_<xx>Collection. So the complete URL would be:

http://<GatewayHost>:<port>/sap/opu/odata/sap/Z_USER_BOR_XX/

z_user_bor_<xx>Collection

3. User credentials can be supplied in advanced by pressing the Login button or can

be supplied when prompted at execution time.

4. Using the Query operation URL, set the Method to GET and select Send.

Results are at the bottom. The Response Header should show an HTTP status code of 200.

In the Formatted XML tab, you should be able to see a number of user entries returned from the

query.


February 2012 23

Notice that only the firstname, lastname, and fullname properties hold values. That‟s mainly because

function module BAPI_USER_GETLIST is not designed to return detailed user data. That is reserved

for BAPI_USER_GET_DETAIL. Of course how the service is mapped in the data model also usually

plays a major role on what data is returned – just not in this case.

Also, there should be a maximum of 100 user entries returned by default. Remember that the

property MAX_ROWS was set to a constant value of '100'.

Restricting Results with $top

Now let‟s limit the number of user entries returned by using the $top parameter.

Add $top=5 to the end of the URL as a query parameter by first appending a '?' and then adding

the parameter:

…/Z_USER_BOR_XX/z_user_bor_<xx>Collection?$top=5

After clicking on Send, here should be no more than 5 entries returned:

Note

Remember that $top takes precedence over the constant set for MAX_ROWS. If more than 100 results are needed, $top can be used.

Target Queries using $filter and Mapped Range Tables

Since there is potentially a large user base, besides limiting with $top, it would be helpful to filter the

returned data using available selection criteria. This is where we can take advantage of the range

table mapped for the Query operation.


February 2012 24

Specific User

To find a specific user, modify the URL as follows:

…/Z_USER_BOR_XX/z_user_bor_<xx>Collection?$filter=userid eq

'<UserID>'

Example

http://mygwserver:8000/sap/opu/odata/sap/Z_USER_BOR_XX/z_user_bor_xxC

ollection?$filter=userid eq 'SMITH'

This returns one result – an entry for user Danny Smith.

Locked or Unlocked Users

If you wanted to only look for users that are locked, the following filter can be user:

…?$filter=islocked ne '0'…

For only unlocked users:

…?$filter=islocked eq '0'…

Other Filters

…?$filter=lastname eq 'SMITH'… Users with LASTNAME equal to „SMITH‟

…?$filter=substringof(lastname,'SM')… Users with LASTNAME containing „SM‟

…?$filter=substringof(lastname,'SM')

and islocked ne '0'…

Users with LASTNAME containing „SM‟

and that are also locked

Note

Although OData specifications for the $filter option include a large variety of logical and arithmetic operators along with various String functions, Gateway does not currently support all of them today.

You can get the latest on the supported filter options by checking Note 1574568 - SAP NetWeaver Gateway 2.0 - Known Constraints.

http://www.odata.org/developers/protocols/uri-conventions#FilterSystemQueryOption




February 2012 25

4.5.4 Test the READ Operation

Returned in the Query operation for each entry is a set of links that allows for easy access to

subsequent data – in this case, the details for each user. For example, for our user Danny Smith, the

following links are provided:

In particular, look for the href attribute value provided. These are relative links that can be plugged

into the URL of the service to access the data mapped by our READ operation.

The top href link performs the main READ operation and gets the data mapped to the root node (e.g.

our address data).

The other two href links correspond to the ACTIVITYGROUPS and PROFILES nodes that we did not

flatten in our mapping and have a cardinality of 0..n.

1. To execute the READ operation, for any entry (i.e. enclosed within <atom:entry> tags), plug

in the top href link provided by replacing z_user_bor_<xx>Collection with the href value.

For example, in the Danny Smith entry:

…/sap/opu/odata/sap/Z_USER_BOR_XX/z_user_bor_xxCollection('SMITH')

Delete any $filter options that may be present.

2. To read the ACTIVITYGROUPS or PROFILES data, you can do the same thing.

Copy the href link for one of these and replace z_user_bor_<xx>Collection with the href

value.

For example, in the Danny Smith entry, to retrieve the ACTIVITYGROUPS data:


February 2012 26

…/sap/opu/odata/sap/Z_USER_BOR_XX/z_user_bor_xxCollection('SMITH')/act

ivitygroups_r

4.6 Map the CREATE Operation

The CREATE operation is used to create a business entity. In order for Gateway to support the

CREATE operation via the Generic Channel, the structure of the business object mapping must be

completely flat. No structures or tables are allowed to be passed as input. Starting with Gateway

2.0/SP02, via the OData Channel, deep insert functionality is possible, allowing the creation of

business entities using structures or tables. Please refer to the SAP Online Help portal for more

information on Deep Insert functionality.

In this step you will map the CREATE operation to the Create1 BOR method. ...

1. In transaction SE80, access your Gateway Data Model object (you may need to enter it as

Z_USER_BOR_<XX>_0001_PS).

2. Once displayed, double-click on the root object Z_USER_BOR_<XX>_0001_PS.

3. Navigate to the Gateway data modeling tool by clicking on the Open generator icon.

4. Click on the Display <–> Change icon to go into edit mode.

5. Scroll to find the USER object and highlight method Create1.

http://help.sap.com/saphelp_gateway20sp02/helpdata/en/63/b45e1756d94c748affe4282fd3ff55/frameset.htm


February 2012 27

6. Click on the Create Mapping button.

7. In the Map Operation window, choose Create.

8. As done for the READ operation, uncheck root node Create1, confirm the warning, and collapse

the structure.

9. Check the Password node and the USERNAME attribute.

10. Expand the Password node and rename the property name BAPIPWD to PASSWORD.


February 2012 28

11. Expand the ADDRESS node without checking it. Map the address attributes as shown below,

renaming and mapping to the root node where necessary. Note that many of these fields (e.g.

DEPARTMENT) already exist and simply have to be selected in the Change Mapping Route

window:

12. Leave everything else unchecked and close the Map Operation window.

13. Generate the data model.

4.7 Map the UPDATE Operation

The UPDATE operation updates a business entity. Just like with the CREATE operation, in order for

Gateway to support the UPDATE operation the structure of the business object mapping must be

completely flat. No structures or tables are allowed to be passed as input. In this step you will map the

UPDATE operation to the Change BOR method.

1. Highlight the Change method.


3. In the Map Operation window, choose Update.

4. As done for the CREATE operation, uncheck root node Change, confirm the warning, and

collapse the structure.


February 2012 29

5. Check the Password node and the USERNAME attribute. Notice that Passwordx gets checked

automatically when Password is checked.

6. Expand the Password node and rename the property name BAPIPWD to PASSWORD and map it

to the root node if necessary.

7. Expand the Address node without checking it. Map the address attributes as follows, renaming

and mapping to the root node where necessary:

All corresponding attributes in Addressx and Passwordx will be set to a constant value

of 'X' automatically.

8. Leave everything else unchecked and close the Map Operation window.



February 2012 30

4.8 Map the DELETE Operation

The DELETE operation deletes a business entity. Many SAP interfaces do not provide a direct delete

operation given the risk of losing potentially critical business data. If they do, sometimes it is only to

mark the object for deletion instead of completely wiping out the business object. However, for some

objects, such as the User object, a direct delete function module is available. In this step you will map

the DELETE operation to the Delete BOR method. ...

1. Highlight Delete.


3. In the Map Operation window, choose Delete.

4. Uncheck the Return node.

5. Close the Map Operation window. Now you should see all the CRUD (Create, Read, Update,

and Delete) operations along with the Query operation included in the data model.



February 2012 31

4.9 Test the CREATE, UPDATE, and DELETE

Operations

Starting with Gateway 2.0/SP03, Cross-Site Request Forgery (CSRF) protection using token

exchange and validation is enabled by default for all data modifying requests (e.g. Create, Update,

Delete).

This means that a valid CSRF token must first be retrieved using a non-modifying request (e.g. using

the GET method). Then it can be sent along with the subsequent modifying request and validated

before normal processing continues.

For more information on CSRF protection mechanisms in SAP NetWeaver Gateway, please visit the

SAP Help Portal: Cross-Site Request Forgery Protection.

4.9.1 Test the CREATE Operation

A CREATE operation uses the HTTP POST method and is called against the same URL as the

QUERY operation.

Retrieve the CSRF Token First

...

1. Open the Firefox REST client.

2. Set the method to GET.

3. Set the URL to the same one used for the QUERY operation:

Example

http://mygwserver:8000/sap/opu/odata/sap/Z_USER_BOR_XX/z_user_bor

_xxCollection

4. Click the Add Request Header button and add the HTTP header X-CSRF-Token with a value of

Fetch as shown:

5. From the Firefox main menu, choose Tools Web Developer Web Console so that you will

be able to copy the token from the Firefox window.

6. User credentials can be supplied in advanced by pressing the Login button or can

be supplied when prompted at execution time.

7. Click on the Send button to execute the query.

8. On the Web Console at the top, click on the link that appears corresponding to the request just

executed.

http://help.sap.com/saphelp_gateway20sp03/helpdata/en/e6/cae27d5e8d4996add4067280c8714e/frameset.htm


February 2012 32

9. In the pop-up window, scroll to Response Headers at the bottom and copy the token value

returned.

Close the pop-up window.

Execute the Create Operation

...

1. Set the method to POST and change the value for header X-CSRF-Token to the token value

that was retrieved in the previous step (Hint: Just double-click on “Fetch” to edit the value).

2. Add a new HTTP header called Content-Type with value application/atom+xml and keep

the URL set to the Query URL.

Next you need to supply the actual data that will be used to create the user. The XML format used is

basically in the form of an <atom:entry> which you‟ve already seen when calling a READ

operation. Main difference is that you‟ll only need to supply the data that is mapped in the data model

for the CREATE operation. A sample XML dataset is provided below.

3. Copy the sample XML below to the Request Body of the Firefox REST client.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>

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

xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"

xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/meta

data">

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

<m:properties>

<d:username>TEST_GW1</d:username>

<d:password>initial</d:password>

<d:title>Mr.</d:title>

<d:firstname>Joe</d:firstname>

<d:lastname>Smith</d:lastname>

<d:language>E</d:language>

<d:department>Sales</d:department>

<d:comm_type>INT</d:comm_type>

<d:telephone>111-222-3333</d:telephone>

<d:e_mail>[email protected]</d:e_mail>

<d:city m:null="true" />

<d:country m:null="true" />

<d:fullname m:null="true" />

<d:islocked m:null="true" />

<d:userid m:null="true" />

<d:name m:null="true" />

<d:region m:null="true" />

</m:properties>


February 2012 33

</atom:content>

</atom:entry>

Note

Even though every field in your Gateway data model may not be relevant for the CREATE operation, they must be supplied in the request with either a valid value or with its null attribute set to “true”.

For example, in the sample above, the property “city” is not needed for the CREATE operation, but it still must be included with its null attribute set to “true” ( <d:city m:null=”true” /> ). Otherwise, a HTTP 500 error can result with error message “The Data Services Request could not be understood due to malformed syntax”.

4. Now that the request is ready, click on the Send button.

5. Upon successful creation, you should receive an HTTP “Status Code: 201 Created” in the

Response Header.

An OData standard is that after every CREATE operation has completed, the client should

automatically perform a READ operation. In the Response Header section, look at the Location


February 2012 34

parameter in the HTTP header returned to the client. This is the URL to perform the READ

operation.

6. Now select the Formatted XML section. In this section, you see the resulting XML returned after

the client has performed the automatic READ.

4.9.2 Test the UPDATE Operation

An UPDATE operation uses the HTTP PUT method and is called against the same URL as the READ

operation.

1. Change the method to PUT in the Firefox REST client.

2. The URL should be set to the same one used for the READ operation. For example:

http://mygwserver:8000/sap/opu/odata/sap/Z_USER_BOR_XX/z_user_bor_

xxCollection('TEST_GW1')

3. Make sure the HTTP headers X-CSRF-Token and Content-Type are set.

You should be able to use the same token used for the CREATE operation earlier.

4. The same XML request body can be used as the one used for the CREATE operation.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>

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

xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"

xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/meta

data">

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

<m:properties>

<d:username>TEST_GW1</d:username>

<d:password>initial</d:password>

<d:title>Mr.</d:title>

<d:firstname>Joseph</d:firstname>

<d:lastname>Smith</d:lastname>

<d:language>E</d:language>

<d:department>Sales</d:department>

<d:comm_type>INT</d:comm_type>

<d:telephone>111-222-3333</d:telephone>

<d:e_mail>[email protected]</d:e_mail>

<d:city m:null="true" />

<d:country m:null="true" />

<d:fullname m:null="true" />

<d:islocked m:null="true" />

<d:userid m:null="true" />

<d:name m:null="true" />

<d:region m:null="true" />

</m:properties>

</atom:content>

</atom:entry>


February 2012 35

5. Change a field for testing (e.g. changing firstname from Joe to Joseph) and click on Send.

6. Upon successful update, you should receive an HTTP “Status Code: 204 No Content”. This

means the update succeeded but as implied by the status text, there is no response body

returned.

Tip

To perform a quick verification of the update, simply change the HTTP method to GET and Send. This performs a READ of the same object and you can verify the results in the Response Body or Formatted XML tab.


February 2012 36

4.9.3 Test the DELETE Operation

A DELETE operation uses the HTTP DELETE method and is also called against the same URL as the

READ (or UPDATE) operation. No request body is needed for the DELETE operation.

1. Change the method to DELETE in the Firefox REST client.

2. The URL should be set to the same one used for the READ (or UPDATE) operation. For

example:

http://mygwserver:8000/sap/opu/odata/sap/Z_USER_BOR_XX/z_user_bor_

xxCollection('TEST_GW1')

3. Make sure the HTTP headers X-CSRF-Token and Content-Type are set.

You should be able to use the same token used for the CREATE/UPDATE operation earlier.

4. Clear the request body if necessary. For a DELETE operation, a request body is not necessary

as the object to delete is identified from the key fields in the URL.

5. Click the Send button in your Firefox REST client.

6. Similar to an UPDATE operation, upon successful deletion you should receive an HTTP “Status

Code: 204 No Content”.

7. You can verify by executing a GET against the same URL. In the Response Header tab, the

result shows a HTTP 400 “Bad Request”.


February 2012 37

In the Formatted XML tab, the error message shows that user does not exist which confirms the

user was deleted.

5. Summary

Without having to write a single line of code, SAP NetWeaver Gateway allows SAP customers to

create and expose REST compliant services enabling the ability to search for and maintain business

entities in an SAP system.

Existing resources (e.g. BOR objects and corresponding RFCs/BAPIS) can be leveraged as data

sources in order to minimize any potential disruption on the backend as consumers look for new and

innovative ways to access SAP data

In the previous steps, a Gateway service that allows for all the CRUD (CREATE, READ, UPDATE,

and DELETE) operations was quickly modeled, simplified, and exposed to allow client applications to

more easily consume and maintain SAP business data.

This guide covered the approach of creating an appropriate data model and generating all the

necessary model and runtime code. Starting with 2.0/SP03 is the ability to generate the code based

on the OData channel.

www.sdn.sap.com/irj/sdn/howtoguides

Documents

Create a Gateway Service Using the Bor Generator Advanced