Create Odata Services BOR

SAP NetWeaver

How-To Guide

How To... Create OData Services

using the BOR Generator in SAP

NetWeaver Gateway

Applicable Releases:

SAP NetWeaver Gateway 2.0 SP3+

Version 1.1

July 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 SAPs Support Services and may not be

modified or altered in any way.

Document History

Document Version Description

0.5 First beta release of this guide only available internally and Gateway

1.0 pilot customers.

1.0 Upgraded to Gateway 2.0

1.1 Upgrade to SAP NetWeaver Gateway SP3+ functionality

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.

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 ...................................................................................................... 2

4.1 Create the BOR based Gateway Object. ..................................................................... 2

4.2 Create the QUERY Operation. ..................................................................................... 4

4.3 Create the READ Operation. ........................................................................................ 6

4.4 Create the CREATE Operation. ................................................................................... 9

4.5 Create the UPDATE Operation. ................................................................................. 12

4.6 Simplify the Data Model Name. .................................................................................. 17

4.7 Create the Gateway Consumption Model .................................................................. 18

4.8 Add an Alias to the Service. ....................................................................................... 19

4.9 Test the REST Operations. ........................................................................................ 23

How To... Create OData Services using the BOR Generator in SAP NetWeaver Gateway

July 2012 1

1. Business Scenario

This How to Guide goes over how to create and test all CRUD (minus Delete since the BOR Bank

object doesnt have a delete method) operations for the Bank BOR object.

2. Background Information

You will need a SAP NetWeaver Gateway 2.0 SP3 or higher system to go over thru this How to Guide.

3. Prerequisites

You will need the following tools to test your services:

SAP NetWeaver Gateway SP3+ installed and configured.

FireFox browser and the RESTClient plugin for testing the services. Note: other similar REST

clients exist that certainly can be used; that said this guide uses the FireFox RESTClient.


July 2012 2

4. Step-by-Step Procedure

The following steps will guide you thru creating and testing a Gateway service based on the BOR

Bank object.

4.1 Create the BOR based Gateway Object. ...

1. Logon to the SAP NetWeaver Gateway system and go to the ABAP Development Workbench

transaction SE80.

2. Create a GW Data Object set the object type drop down to GW Data Object:

3. In the object name input field enter the name Z_BANK_BOR_:

4. Click on the eye glasses button to create the object.

5. Click the Yes button in the popup window:

6. In the Create Data Model popup window set the type to PS Public Solution Model and select

the radio button for Generate from Data Source Object. Make sure to leave the OData Channel

check box selected:


July 2012 3

7. In the popup window enter a Description, Data Source Type (BOR), and the System Alias (this

is the alias that is connected to the back end system in this case I am simply going against the

local system). Click Continue.

8. Your Model should now be displayed along with the BOR (Business Object Repository) of the

System Aliass associated backend system:


July 2012 4

4.2 Create the QUERY Operation.

OData services support the CRUD operations and an additional QUERY operation which is used for

search for the associated entities. Typically an OData service will support this QUERY operation and

READ operation at a minimum.

1. In the BOR find the Bank object and in the Bank object highlight the GetList method:

2. Click the Create Mapping button found on the right hand side of the screen.

3. In the Map Operation set the Operation Type to Query:


July 2012 5

4. We need to make the BankCtry attribute available as an input parameter to our service. Right

click on the BankCtry attribute and then click the Change Mapping Route button.

5. In the popup window select BANK_CTRY (the one with the key icon next to it) and click the

Enter button:

6. Your mapping should now look like the following:

7. Click the Enter button to complete the operation mapping. Your data model should now look like

the following:


July 2012 6

4.3 Create the READ Operation.

The READ operation is used get a specific entitys detailed data.

1. In the BOR Bank object highlight the GetDetail operation.

2. Click the Create Mapping button.

3. Set the Operation Type to Read.

4. Uncheck the Return and BankDetails structures, your mapping should now look like this:


July 2012 7

5. BANKCOUNTRY and BANKKEY are input attributes that need to be assigned to the data

models key attributes BANK_CTRY and BANK_KEY. Right click on the BANKCOUNTRY

attribute and click the Change Mapping Route button.

6. Select the BANK_CTRY attribute and click enter:

7. Now do the same for the BANKKEY attribute assigning it to the BANK_KEY attribute of your

data model:



July 2012 8

9. Notice in the above image that BANK_NAME and CITY attributes of the BankAddress structure

are mapped to the previously created attributes from the QUERY operation. Lets do the same

with the rest of the attributes of the BankAddress structure that we will expose on the data

model.

10. Right click on the REGION attribute and click the Change Mapping Route button.

11. Select the root node of your object:

12. Click the Enter button. Now do the same thing for the STREET attribute.

13. For the rest of the attributes of the BankAddress structure, starting with the SWIFT_CODE

attribute, uncheck the corresponding checkbox.



July 2012 9

15. Click the Enter button to complete the operation mapping.

16. Your data model should now look like the following:

4.4 Create the CREATE Operation.

The create operation is used to create a new entity.

1. In the BOR Bank object highlight the Create method:


July 2012 10


3. Select the Create operation type radio button.

4. Uncheck the BankAddress1 structure, and the BankFormatting, BankMethod, I_XUPDATE,

BANKCOUNTRY and BANKKEY attributes (note: when unchecking the BANKCOUNTRY and

BANKKEY attributes you will be warned that they are mandatory, just ignore this by clicking the

yes button). Your mapping should now look like the following:

5. In the BankAddress structure uncheck all attribute starting at SWIFT_CODE and ending at

ADDR_NO. Note: you will receive a warning message about deselecting a mandatory

parameter; ignore this by clicking the Yes button. Your mapping should now look like the

following:


July 2012 11

6. The REGION and STREET attributes in the BankAddress structure need to be mapped to the

already existing attributes named REGION and STREET on the data model. Right click on the

REGION attribute and click the Create Mapping Route button.

7. Select the REGION attribute in the data model and click the Enter button:

8. Do the same for the STREET attribute selecting the STREET attribute in the data model. Your

mapping should now look like the following:


July 2012 12

9. Click the Enter button to complete your operation mapping.


4.5 Create the UPDATE Operation.

The UPDATE operation is used to update an existing entitys data.

1. In the BOR Bank object highlight the Change method.



July 2012 13

3. Set the Operation Type to Update.

4. Uncheck the BankAddress1 and BankDetail structures.


6. The primary key needs to be set properly. The Bankcountry and Bankkey attributes make up the

primary key for this method and need to be assigned to the data models primary key fields

BANK_CTRY and BANK_KEY.

7. Right click on the Bankcountry attribute and click the Change Mapping Route button. Select the

data models primary key field BANK_CTRY:

8. Click the Enter button in the Change Mapping Route window.

9. Now do the same thing for the Bankkey attribute mapping it to the data models primary key

attribute BANK_KEY. Your mapping should now look like the following:


July 2012 14

10. In the BankAddress structure deselect all attributes starting a SWIFT_CODE and ending at

ADDR_NO. Note: you will receive a warning message about deselecting a mandatory

parameter; ignore this by clicking the Yes button. Your mapping should now look like the

following:

11. The REGION and STREET attributes of the BankAddress structure need to be flattened

(appear under the root node of the data model). Right click on the REGION attribute and click

the Create Mapping Route button.

12. Select the REGION attribute already defined under the root node of the data model then click

the Enter button:


July 2012 15

13. Do the same for the STREET attribute selecting the STREET attribute already defined under the

root node of the data model. Your mapping should now look like this:

14. Click the Enter button to complete the operation mapping.



July 2012 16

16. Click the Generate button. This will generate all the classes and other configuration files needed

for the service.

17. When generation is complete you will see the following popup window displayed:


July 2012 17

4.6 Simplify the Data Model Name.

The name of your data model is currently Z_BANK_BOR_. This name will by

default be used when calling your service. Lets make it simpler name that describes the data, ie

Bank.

1. Navigate for the Gateway Data Modeler back to the ABAP Workbench by clicking the Object

Navigator button:

2. You should now be back in the ABAP Workbench (SE80) and should see your Gateway Data

Model:


July 2012 18

3. Double click on the Data Model node (first node under the root node):

Double clicking on it will open up the editor for this node. Notice the External Name input field.

4. Go into change mode and change the External Name to be Bank:

5. Save your changes. Now your data model is known as Bank.

Note

If you go back in and change you data model (add a new operation or change some of the mapping) and then regenerate this configuration will be lost! The name will revert to the old data model name.

4.7 Create the Gateway Consumption Model

The Consumption Model is what exposes the Gateway Data Models to the network. It does this by

creating a service in the Internet Communication Framework. In this step you will create a

Consumption Model and then map your Data Model to it.

1. Right click on the GW Data Models Related GW Consumption Models node and in the context

menu select Add Consumpt. Model:


July 2012 19

2. In the input field enter in the name of the consumption model you want created zbankbor:

3. Click the Enter button. You will be asked if you want to create the consumption model, click the

Yes button.

4. Enter a description for your consumption model and click the Enter button:

5. You can see the Gateway service exposed in the ICF transaction SICF follow the ICF tree

path default_host > sap > opu > odata > sap...there you will see a list of all ICF services that

represent Gateway Consumption Models.

4.8 Add an Alias to the Service.

The service needs to be pointed at the appropriate backend system. To do this we must assign an

alias that has already been defined for that backend system to the service that you created in the

preceding steps.

1. Go to the service maintenance transaction /IWFND/MAINT_SERVICE:


July 2012 20

2. Click the search icon to search for your service in the list the search icon is outlined in red

below:

3. In the Find popup window enter in the Technical Service Name (ZBANKBOR) for the search term:

4. Click the enter button, your service should be located in the list:


July 2012 21

Note

Once you find your service in the list you will need to close the Find window by clicking the Cancel button in the bottom right hand corner.

5. Click the Technical Service Name link (highlighted below in red on the top half of the screen),

this will cause the Alias assignment details be displayed at the bottom of the screen:

6. Click the add System Alias button outlined in Red above in the bottom half of the screen. You

should now see the screen to maintain service aliases:

7. Click the New Entries button.


July 2012 22

8. Add your service document (the consumption model)enter in the name of your consumption

model zbankbor* and click the F4 help button:

9. Double click on your service document in the popup window.

10. In the System Alias column enter the alias of the system you want your service to call in this

case we are using the local alias:

11. Save your changes then hit the back button. You should now see that the LOCAL alias is

assigned to your service:

12. Click the Call Browser button to launch a web browser that points to the service document of

your OData service:


July 2012 23

Note

By default all service are protected by basic auth so you will need to logon with username and password.

4.9 Test the REST Operations.

Now for the fun part! You get to test everything you have done up to this point. Testing the QUERY

and READ operations is easyyou just need a browser. Testing the CREATE and UPDATE

operations (as well as the DELETE if we had implemented that), requires the use of a simple HTTP

tool, the one we use here is the RESTClient plugin in for FireFox.

1. In the browser that you launched in the last step, replace the end of the URL ?$format=xml

with $metadata this will bring up the metadata of your service:

Example URL: http://service:http_port/sap/opu/odata/sap/ZBANKBORGEBO/$metadata

2. In the URL replace $metadata with BankCollection this will execute the QUERY operation.

You should now see the following:


July 2012 24

Why the error? Remember we exposed an input parameter for the query operation, we need to

pass the country in. This is done using the $filter query string parameter.

3. Add a $filter query parameter to the URL to get all German banks - $filter=bank_ctry eq DE.

Example URL:

http://server:http_port/sap/opu/odata/sap/ZBANKBORGEBO/BankCollection?$filter=bank_ctry

eq 'DE'

4. To make it easier to test and debug add the query string parameter sap-ds-debug=true to the

URL this will format the content as html allow us to follow links to the READ operation:


July 2012 25

Example URL:

http://server:http_port/sap/opu/odata/sap/ZBANKBORGEBO/BankCollection?$filter=bank_ctry

eq 'DE'&sap-ds-debug=true

Note

You will see an SAP icon in the bottom right hand corner. Click it to see more details about the service call.

5. To execute the READ operation for a specific bank just click the link

BankCollection(bank_ctry=,bank_key=):

6. Clicking this link will bring back the bank details from the READ operation:


July 2012 26

7. Now lets test the update and create functionality.

8. To test the update and create functionality we will need a CSRF token (needed to prevent Cross

Site Request Forgery attacks)to do this we need to request this token during a read by

passing in an http header value requesting the token. To pass in a header value we need to use

the RESTClienthere using the FireFox RESTClient (this is a free plugin for FireFox):

9. Copy the URL used in the test in step 6 above (the URL that executed a READ) and paste it into

the URL input field.

10. Remove the query string attribute sap-ds-debug=true from the URL.

11. Click the Headers menu item and select Custom Header:


July 2012 27

12. Enter the name / value as shown below:

Tip: Check the Save to favorite check box so you can easily add this header for faster testing the next time!

13. Click the Okay button. You should now see the following:

14. Click the SEND button.


July 2012 28

15. In the Response section at the bottom of the RESTClient copy the value returned for the x-csrf-

token, shown here outlined in red (note, these token values are generated by the gateway

server):

The token will be passed back in when testing the create and update functionality.

16. Change the value for header attribute x-csrf-token to be the value you copied above, to do this

just click on the header attribute in the RESTClient you should now see something to the

following:

17. Test the UPDATE_ENTITY / UPDATE operation.

18. Add the content-type header to the Request Headers section. Click the Headers dropdown and

select Custom Header.

19. Enter the name/value content-type/application/atom+xml;type=entry:


July 2012 29

Tip: Save this as a favorite so you can easily add it again when testing.

20. Click the Okay button to add the header request.

21. Switch to the Response Body (Raw) tab and copy the contents there (we will be updating the

data that was sent back when reading the entity):

22. Paste the Response Body you just copied into the Request Body section.

23. Change the Method dropdown to PUT. Your RESTClient should now look similar to the

following:

24. To test the update functionality we need to change some of the values in the request body that

we are sending to the Gateway serverchange the value for street, city and/or bank_name:


July 2012 30

25. Click the SEND button.

26. If the update is successful you will get a status code of 204 as shown below:

27. You can switch the Method back to GET and click the send button again then check the

response body to see if the values you changed for the update are returned by the read.

28. Test the CREATE operation.

29. To test the create functionality we need to change the URL to be the same URL you would use

when testing the QUERY operation. All you need to do is remove the ending portion of the URL

used for the update that starts and ends with parenthesisthe URL should look like the

following example:

http://server_name:8000/sap/opu/odata/sap/ZBANKBORGEBO/BankCollection

30. Set the Method dropdown to POST.

31. In the Request Body change the bank_key value to be something unique in the system (also, for

German banks the key must be 8 characters, for US banks the key is 9 characters):

Note: the important part of this request data is the XML values that you are changingthe rest can be ignored in this

case.

32. Your Request should now look similar to the following:


July 2012 31

33. Click the SEND button. You should receive back a response status code of 201 if successful:

34. When the create is successful a call is done to the URL specified in the Location header which

is the URL used to read the newly created entityyou can see the contents of this call in the

Response Body:


July 2012 32

Congrats! You have successfully created and tested a simple OData service created with the

SAP NetWeaver Gateway BOR generator!

http:// :/sap/opu/sdata/sap/

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

Create Odata Services BOR

Documents

Transcript of Create Odata Services BOR