GW100 Speaker’s Guide
Speaker's Guide for GW100 "Building
OData Services Using SAP
NetWeaver Gateway"
Applicable Releases:
SAP NetWeaver 7.02 ≥SP7 + SAP NetWeaver Gateway 2.0 SP3 add-on
SAP ERP 6.0 or higher
IT Practice / Topic Area:
SAP NetWeaver Gateway
Version 1.0
May 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
Table of Contents
0.
Prologue for the Lecturer ... 1
0.1
Purpose of this document ... 1
0.2
Animation Events ... 1
0.3
Screen Shots ... 1
0.4
Configuring the WTS Environment ... 1
0.4.1
Browser Behaviour When Displaying Atom Feeds ... 1
0.4.2
RESTClient Behaviour ... 2
0.4.3
Port Numbers Used By Apache Tomcat ... 2
0.5
Dealing with Misconceptions ... 2
0.6
ABAP System Preparation ... 3
1.
Chapter 1.1 – Introduction ... 6
2.
Chapter 1.2 – Introduction to REST ... 28
3.
Chapter 1.3 – Introduction to OData ... 37
3.1
Appendix ... 62
4.
Chapter 2.1 – RFC & BOR Generators (Read Only) ... 63
5.
Chapter 2.3 – RFC & BOR Generators (Update) ... 80
6.
Chapter 3.1 – Monitoring ... 91
7.
Chapter 4.1 – Developing a Model Provider Class – Part 1 ... 92
8.
Chapter 4.3 – Developing a Model Provider Class – Part 2 ... 96
9.
Chapter 4.5 – Developing a Model Provider Class – Part 3 ... 98
10.
Chapter 5.1 – Developing a Read-Only Data Provider Class ... 99
11.
Chapter 5.3 – Developing an Update Data Provider Class ... 103
12.
Chapter 5.5 – Using Associations and Navigation Paths ... 104
0. Prologue for the Lecturer
0.1 Purpose of this document
This document is intended to serve as a guide for someone wishing to teach the SAP training course GW100 “Building OData Services Using SAP NetWeaver Gateway”.
This document is not intended to be a script that should be recited word for word; rather it provides the teacher with a guide firstly, of what the important topic(s) is(are) on a particular slide, and
secondly, what key point(s) should be made in order to make the presentation of topics and concepts flow naturally and coherently.
If this guide is followed, it will help the teacher communicate the subject of SAP NetWeaver Gateway in a clear and coherent manner.
0.2 Animation Events
All through the PowerPoint version of the presentation, there are animation events. These events are almost always simple fade events, rather than anything that involves motion or that would distract the student’s attention away from the content and on to the animation itself.
The reason is simply this: if you present an audience with a slide containing a large amount of text, as soon as that slide becomes visible, at least 50% of your audience will immediately stop listening to what you are saying because they are busy reading the slide.
No matter what a person claims, they cannot give 100% concentration to both reading and listening at the same time. Therefore, the information on busy slides must be presented gradually. This allows you time to build up the complexity of the information slowly, rather than presenting the full picture in a single hit.
To aid your delivery of this course, this speaker’s guide will use a circled star ⍟ to indicate when the animation event should take place. This will ensure that your description of the information and the presentation seen on the screen are coordinated and flow smoothly.
0.3 Screen Shots
Some of the screen shots in the training material contain information that differs slightly from the accompanying text; this particularly true when the names of ABAP classes are seen in screen shots. The screen shots were taken using ABAP class names start “Z_CL_GW100…” when the names “ZCL_GW100…” should have been used instead.
The text in the training material shows the correct ABAP class names, but the screen shots will show names with an underscore as the second character.
Due to development deadlines for finalising this course, it will not be possible to correct the screen shots.
0.4 Configuring the WTS Environment
0.4.1 Browser Behaviour When Displaying Atom Feeds
In SP3 of SAP NetWeaver Gateway 2.0, by default, the server will return XML data using the MIME type of application/atom+xml. For Gateway Service Documents only, this MIME type can be changed to application/xml by adding the URL parameter $format=xml.
If you try to display Gateway generated XML in Firefox, Chrome or Safari, these browsers all
recognise the MIME type and format the display as an Atom Feed – thus hiding the XML the students need to look at.
Therefore for demos, the query string parameter sap-‐ds-‐debug=true should be added to the URL. This will cause the Gateway server to return the XML formatted as an HTML page. There will also be an SAP icon in the bottom right of the screen. If this is clicked on, then a popup display with provide technical information about the most recent server round-trip.
0.4.2 RESTClient Behaviour
As of the writing of this document (early May 2012), versions 2.0.0 and 2.0.1 of the FireFox RESTClient both contain bugs. These bugs prevent the RESTClient from displaying the response after a PUT request has been issued. Even though the PUT request works, it give the impression that the server never responds to the request because the RESTClient has hung.
Therefore, an older version of the Firefox RESTClient must be used – version 1.3.4 to be exact. If a student points out that the latest version of the RESTClient is not being used, please point out the above bug and ask them not to upgrade the RESTClient.
Also, as of version 2.0.2 of the RESTClient, this version does not correctly handle the HTML response created when the sap-‐ds-‐debug=true parameter is added to a Gateway URL. The pop-up
information that would normally be available when clicking on the SAP icon is not rendered correctly by version 2.0.2 of the RESTClient.
The “GW100 WTS Initial Setup Guide” document contains the details of how the RESTClient add-on for Firefox should be installed.
0.4.3 Port Numbers Used By Apache Tomcat
All the participants doing the exercises for GW100 will share the same WTS session. The first consumption exercise is based on Java Server Pages and requires the use of the Apache Tomcat server. This server is configure by default to use ports 8005, 8009 and 8080; however, each participant needs their own independent instance of Tomcat, so it is not possible to use the default port numbers without clashes occurring.
Therefore the students must adjust the Tomcat port numbers before starting the consumption
exercises. The “GW100 WTS Initial Setup Guide” also documents how these port numbers should be configured.
0.5 Dealing with Misconceptions
Whilst you will be spending most of the lecture time in this training course telling people about what SAP NetWeaver Gateway is and does, a large part of successful education is to tell people what SAP NetWeaver Gateway is not.
This is where it is necessary to deal with popularly held misconceptions. The best way to eliminate misconceptions is simply to present the facts in such a way that the misconceptions become self-evident.
However, you will have made a fundamental error as a trainer if you provide the students with a shallow, superficial explanation in the assumption that, because you understand the topic, that therefore the students should automatically understand it also.
Always try to view the subject from the student’s perspective and think about what questions you would ask if you were a student learning this material for the first time.
One topic that seems to be universally misunderstood is Representational State Transfer or REST. Therefore, this topic has been given a specific chapter of its own.
0.6 ABAP System Preparation
Log on to the training system ZME as user GW100_TRAIN with password *gateway*. This user has SAP_ALL authority.
1. Run program SAPBC_DATA_GENERATOR. This will regenerate all the flight data with up to date information.
Due to performance problems in Gateway 2.0 SP03 in handling the OData command $count,
you should only ever create the minimum quantity of flight data!
This is because once the students have created their Gateway service they could easily issue a URL that requests a list of all flight bookings in the system.
Without the use of the $filter or $top commands the response time is likely to be very poor (>30 seconds).
2. Run transaction ZUSR. This will create the users required by the students. 3. Complete the input fields on the first screen of ZUSR as follows:
4. All user details are copied from the template user GW100_USER. The course name is GW100 and set some initial password.
The number of users you need to create will vary according to the number of attendees.
5. After pressing F8 to run the creation process, you will see a pop-up that shows which user ids are available. Press “Create”.
6. You will next be asked if this training course requires unique group numbers.
Answer “Yes” to this question.
8. The next step is to create a change request for each user. Press the truck icon on the toolbar.
You need to create both a change request and a customizing request. For each type of request select “Single req. for each selected user” radio button then press “Create”.
1. Chapter 1.1 – Introduction
Slide 5) Lecturer
The simplest answer you can give to the question “What is Gateway” is to say that it is “The OData API into an SAP system”. This is a definition you will often repeat whilst delivering this training course.
Students
Gateway sits in between an SAP Business Suite or ECC 6.0 system and the outside world. When we say the “outside world”, we mean any software external to the ABAP based SAP systems.
Typically, this will be some client-based application that consumes an OData service and interacts directly with an end user. However, it is also possible for the Gateway interface to supply information to server-based software, which then forwards the information to one or more client devices.
In the case of SAP Workflow events, the Gateway interface can push a workflow event out to some server that consumes the information and then forwards it to however many client devices have subscribed to that event.
The software to consume workflow events coming out of the SAP system is not covered in the GW100 training course. The Sybase Unwired Platform (SUP) software offers a possible solution to event consumption, but is not the only software option a customer could use.
⍟ Open
The OData interface is an open standard that can be consumed by any software or device that can communicate using the HTTP(S) protocol and can parse and construct an XML document ⍟ People
Gateway has been designed to provide a Business to Consumer (B2C) or Business to Employee (B2E) interface. Although it would be technically possible to use Gateway in a B2B style interface, this would be a use case that lies outside SAP’s intended set of use cases for Gateway.
⍟ Timeless
Since the Gateway software has been implemented as a set of ABAP add-ons, these can be deployed to a wide range of SAP Business Systems. Delivery of the Gateway software as ABAP add-ons ensures the minimum level of interference with existing systems.
⍟ Developers
There are two major advantages that come with the use of an OData interface:
1. Information communicated over an OData interface can be encoded either as XML or JSON. Both of these formats are well known, plain text protocols for the transmission of information over the Web.
2. Irrespective of the format used to transmit an OData message, that message is self-describing. Therefore, any Web developer will be able to understand the message content without needing to have any internal knowledge of how an SAP system works. In the past, there has always been the issue that in order to consume SAP functionality from an external program over the RFC interface, developers have needed to have at least a basic knowledge of the internal workings of an SAP system. Now however, when taken together, the above two factors lower the barrier for consuming SAP data and business functionality to the lowest possible level.
A developer no longer needs any knowledge of the internal workings of an SAP system in order to consume a Gateway (OData) service.
⍟ Standards
The Gateway interface implements the OData protocol as described on www.odata.org
Lecturer
The OData interface is a RESTful interface. The term “RESTful” is much misunderstood and much abused. Therefore, an entire chapter of this training course has been dedicated to defining exactly what REST is – and more to the point, what REST is not!
Slide 6)
Lecturer
The first animation event starts automatically when the slide is first presented.
Students
OData is a Microsoft developed standard that is built on the existing Atom Publishing and Atom Syndication protocols.
⍟ OData was developed in response to the fact that the earlier Atom Publishing and Atom
Syndication protocols were only partially RESTful. This topic will be covered in more detail in chapter 3 where we look at the specific details of OData, and how OData improves on the underlying protocols such as Atom.
Lecturer
Try to avoid starting into a detailed discussion of OData at this point because you would be jumping ahead of yourself. This comes in chapter 3.
Students
⍟ The term “ODBC for the Web” is conceptually accurate, but there is no sense in which OData allows you to execute an exact SQL statement over the Web. Nonetheless, the OData interface exposes an API that allows collections of entities to be retrieved using a syntax that provides a similar level of functionality to that offered by SQL.
⍟ There is no cost or license agreement needed for the use of OData. The standard is open and can be used by anyone who cares to implement it.
⍟ The main reason SAP chose to implement OData was that a joint development with Microsoft was being performed based on Duet Enterprise – which requires an OData interface.
Also, another advantage of OData is that it is extensible. This is particularly useful in cases where SAP specific values need to be described in this protocol; for instance, currency fields. A currency field contains two separate values, the currency amount and the currency code. These two values must always be treated as a linked pair, and OData’s extensibility allows for this.
Slide 8) Lecturer
Before starting the description of the various deployment scenarios, its important to emphasise the fact that SAP NetWeaver Gateway is not a new type of SAP system such as CRM or BI or some Industry Solution product. Instead, Gateway is nothing more than a set of ABAP add-ons that can be installed into any suitable NetWeaver system.
The next four slides describe three deployment scenarios for the SAP NetWeaver Gateway add-ons. The purpose of going through the deployment scenarios is to show that each deployment scenario determines which development scenarios are possible.
Based on these three deployment scenarios, you then have four different development options. Don’t get your deployment scenarios confused with your development scenarios. The deployment scenario describes where the various SAP NetWeaver Gateway add-ons are installed, and the development scenarios describe how the Gateway software is developed.
Students
In the first deployment scenario, the Gateway add-ons are deployed to an independent server that acts as the communication end point for all OData communication. This server is known as the “Gateway Hub” and does not hold any business data and usually does not perform any business functionality.
⍟ In this scenario, the backend server needs to have the IW_BEP component installed. IW_BEP is the component that allows an ABAP programmer to develop a Gateway service. This service is then exposed to the outside world through the Gateway Hub server.
The advantage of this development and deployment scenario is that the Gateway Service is developed within the same server within which the actual business data resides. This development scenario offers the ABAP developer a much greater range of business flexibility.
⍟ This deployment scenario relies on the fact that the customer permits the installation of add-ons into their productive system. It cannot be assumed that all customers will allow this. This
consideration is particularly important for partners wishing to develop Gateway services that they want to sell to their own customers.
Slide 9)
⍟ As far as the deployment of SAP NetWeaver Gateway add-ons is concerned, this slide is identical to the previous slide. However, if the customer has no in-house ABAP developers, then it is possible to create Gateway Services using the service generation tool. This tool runs directly in the Gateway Hub and generates a fully functional Gateway service. No ABAP coding is needed (or in SP03, even possible).
The generated service is executed in the Gateway Hub server, and relies on the fact that the required functionality is available from the backend server in the form of BAPIs or RFC Function Modules. Alternatively, if a basic ABAP dynpro screen implements the required functionality, then a Gateway Service can be created using screen scraping. For this to work, the IW_SCS component must be installed in the backend system.
Either way, no ABAP coding needs to be written.
Lecturer
Slide 10)
Lecturer
Here, it is important to point out that some customers will not permit the installation of add-ons into their productive system. This is particularly true for customers in the pharmaceuticals or defence industries where strict system compliance is a top priority.
Students
⍟ There are several situations in which it will not be possible to install the add-ons IW_BEP or IW_SCS into the backend business system. Either:
1. The backend system is too old to support these add-ons, or
2. The installation of add-ons into the customer’s system landscape would necessitate a repeat of some external compliance certification, or
3. The complexity of the customer’s system landscape makes the installation of IW_BEP (and therefore the development of Gateway services directly on the backend server) impractical. Notice that IW_BEP can also be installed in the Gateway Hub.
Custom Gateway services can be developed in any system that contains IW_BEP; the difference here however is that since the custom Gateway Service is running in the Gateway Hub and not directly in the backend, RFC calls will need to be made into the backend system in order to perform the required business functionality.
Lecturer
If you have not already done so, you should now ask which students on the training course are from a partner organisation that plans to develop its own Gateway Services. If there are such people on the course, they need to pay special attention to the above points.
Unless a partner has a specific agreement from their customer to install IW_BEP in their backend system(s), all partners will need to assume that their customers (the third parties to whom they sell their Gateway services) will not agree to install IW_BEP across all the systems in their landscape. This assumption will greatly increase the range of customers to whom they can sell their Gateway
Students
For partner organisations developing their own Gateway Service, it is safe to assume that most customers will not agree to installing IW_BEP in their backend business system simply to accommodate a partner written Gateway Service.
Therefore, partners should write Gateway Services to make RFC calls into the backend system. This is known as the non-invasive approach to Gateway Service development.
A Backend Operation Proxy (BOP) is a wrapper that can be generated in the Gateway Hub in order to call an RFC module in the backend system. Such a wrapper is needed in cases where the Gateway Hub server and the backend business system are running on different SAP system versions, which in turn implies that the ABAP Dictionary objects that define the fields in an RFC interface may well be missing in the Gateway hub. In these cases it is necessary to generate a wrapper that uses simple data types to describe the fields in the RFC module’s interface instead of dictionary data elements. BOPs can be generated by accessing the transaction through the IMG.
⍟ In this case, the backend system could be any at version back to R/3 4.6C.
Lecturer
If students ask why only systems back to 4.6C are supported, it is because at this version, there were significant changes made to the RFC protocol. Older systems cannot support the current RFC protocol.
Students
⍟ Since the backend system cannot have any add-ons installed (either because it is too old, or because the customer does not permit it), the Gateway Service will not be able to use any screen scraping or event push functionality offered by IW_SCS and IW_BEP respectively.
Slide 11)
This deployment scenario is known as the all-in-one option.
⍟ This is where all the Gateway add-ons are installed directly on the backend business system. This scenario is suitable for proof-of-concept development, or the deployment of Gateway Services within an intranet only environment.
⍟ The backend server must conform to the minimum requirements for a Gateway Hub server, since the backend system has now become the Gateway Hub server.
⍟ This scenario is most definitely not recommended for deployment of services to the public internet since this would make the backend server directly accessible from the public internet.
The advantage of having a separate Gateway Hub server is that it sits in your network’s DMZ and communicates with the backend server through a firewall. This ensures that only the Gateway Hub server is visible to the public Internet and not the actual business system.
Slide 13)
The Gateway Service Generator is a tool that will take a BAPI, RFC Module or basic Dynpro as input, and from it create a Gateway service. This option is suitable for prototyping or where ABAP
Slide 14)
Students
The screen shot is taken from the RFC and BAPI Gateway Service Generation Tool. It shows that the individual CRUD operations are mapped to RFC modules.
Lecturer
In this particular, the screen shot shows BAPIs being treated as RFC modules, which although slightly unusual, is perfectly legitimate.
SAP Note 1688265 needs to be applied to a Gateway system in the situation that you are calling a BAPI as an RFC module via a generated Gateway Service. Without the application of this note, an automatic COMMIT is not performed after the BAPI is called.
The logic for this is simple enough: if you generate a Gateway service using a BOR object, you are implicitly stating that a COMMIT should take place once the BAPI implementing the method of the business object has been called.
However, if you generate a Gateway service using an RFC module – irrespective of whether or not it is a BAPI – then the Gateway system cannot be responsible for calling an automatic COMMIT after the RFC module has been invoked. This is because RFC modules are responsible for performing their own COMMITs.
SAP Note 1688265 changes a setting the Gateway Framework that indicates a COMMIT is required after an RFC module has been called via a generated Gateway service.
Slide 15)
This screen shot is taken from the Screen Scraping Gateway Service Generation Tool. It shows much the same information as the previous slide, except that individual CRUD operations are mapped to screens instead of function modules.
Slide 16)
Two of the most frequent use cases for screen scraping are to expose search help functionality and to implement simple button push events for ABAP Dynpros where such functionality has no equivalent over the RFC interface.
Slide 17)
General features provided by the service mapping tool.
Lecturer
One feature mentioned here that will be important later is ability to flatten the fields belonging to a data structure. Whilst this might seem like a tedious manual task to perform at design time, it avoids an awkward consequence of trying to send data structures over the OData interface.
If scalar data structures are present in an RFC or BAPI interface, then when these data structures are transformed to an OData interface, the interface will be built in such a way that a second HTTP request must be made in order to obtain the data in the data structure.
To avoid this inconvenience, the fields in the data structure must be flattened – that is, they must be removed from the structure within which they were originally declared and treated as if each field were independent.
In addition to this, when a READ operation is performed, the typical sequence of events is that the user wishes to update the information. So the values coming out of a READ operation very often will be needed as input into subsequent UPDATE or CREATE operations.
UPDATE and CREATE operations based on the service generator require that their input fields are not part of a data structure.
Slide 18)
From the perspective of developing custom Gateway Services, it is important to understand that this type of development takes place in whichever system component IW_BEP has been installed. ⍟ For partners developing a Gateway Service that is to be sold to a wide range of SAP customers, the development will take place in the Gateway Hub. This is because it is not safe to assume the customer will permit the installation of the IW_BEP add-on in their productive system.
Slide 19)
Slide 20)
⍟ When creating a Gateway Service, two distinct ABAP classes need to be developed
⍟ The metadata provider class defines the service’s interface. The information provided by this class is used when an external application wishes to consume a Gateway Service. This class provides the consumer with a full description of the entities available from this service and how those entities are associated with each other.
⍟ The data provider class provides the actual runtime implementation of the business functionality described by the metadata class.
Slide 21)
Lecturer
Here’s something that usually catches out ABAP developers new to Gateway.
Students
There is no need to have a direct programmatic relationship between the model and data provider classes. This may at first seem strange because most developers assume that if the data provider class is going to output information, then it will need to have a reference to the model provider class in order to understand the structure of its own interface. In fact, this is not the case.
⍟ The relationship between the data and model provider classes is implemented through configuration, not coding. Two different configuration wrappers need to be created. A configuration wrapper is created for the model provider class.
⍟ And a configuration wrapper is created for the data provider class.
In reality, there often is a programmatic association between the data provider class and the model provider class, but this is only so that the data provider class can create objects and data structures of the same type as are used in the model provider class.
Typically, the model provider class will contain a set of public data types that can be referenced by the data provider class.
Slide 22)
When the configuration wrapper for the data provider class (Service Group) is created, you need to supply an internal service name.
⍟ The internal and external service names are important because
⍟ The name you specify for the internal name is copied and becomes external name
The external name is the name seen by the user in the URL when addressing the Gateway Service from outside the SAP system.
It is very important therefore that the external name is relevant and meaningful for the end user. This means that the name used for the internal name must also be relevant and meaningful to the end user.
Slide 23)
Once you have created the two configuration wrappers, these are associated with each other by a further configuration step, and you have a Gateway Service – that is not quite ready to use!
Slide 24)
The final step is to create a Service Catalogue entry. This is done in whichever server acts as the Gateway Hub – which, depending on the deployment scenario you are using, may, or may not, be the same system in which the Gateway Service was developed.
⍟ After the Service Catalogue entry has been created the Gateway Service can be accessed from some external client device or browser.
Slide 26)
Lecturer
At this point, it is worth asking the students to try and answer this question before you show them the answer.
⍟ You will receive a wide variety of answers!
⍟ This is a point where some of the students will look at you as if you have just said something completely crazy. This is particularly true for students from companies that are long time SAP customers.
There is a strong expectation among customers (especially long term ones) that when it comes to how SAP software should be used (E.G. how a Gateway service should be consumed), then SAP will always make some recommendation or define some best practice that should then be religiously followed.
The plain fact of the matter here is that the customer is completely free to use any programming environment with which they are comfortable.
No doubt, some people will object to this and expect SAP to publish some “best practice”. However, you should point out that this expectation misses the fundamental reason why SAP adopted OData! In order for SAP to be able to lower the consumption barrier for its services and data down to the lowest possible level, it is imperative that as many restrictions as possible are removed.
Therefore, SAP imposes no restrictions on how an OData service should be consumed.
At this point however, someone will certainly ask, “Well, what about SUP, aren’t we supposed to use that?” Yes, in the past SAP has recommended that mobile devices connect to an SAP system through Sybase’s Unwired Platform. However, SAP cannot force any customer to buy SUP. Many customers have written perfectly useable, functional and scalable mobile device applications that connect directly to a Gateway Service without using SUP.
IMPORTANT: This training course is not the forum in which to get into a discussion about the morality of using SUP. Instead, point out that from a technical perspective, SUP is not mandatory; however it does offer some benefits especially when applications need to function in an offline scenario.
Slide 27)
Students
SAP offers various tools for OData proxy objects in Java, PHP, C# and Objective C. These proxy objects can then be included in a client device application.
⍟ The use of these tools is not mandatory, but is helpful because it greatly speeds up the
development process. On the www.odata.org website, many different OData libraries and SDKs can be downloaded for a wide variety of languages.
2. Chapter 1.2 – Introduction to REST
Lecturer
This chapter was added because many people simply do not know what REST is and, without questioning their own thought processes, assume that it is some kind of network protocol such as HTTP, RFC or SOAP.
Therefore, this chapter will first inform the students about what REST is not, and then will give a brief overview of what REST actually is.
Slide 5)
Lecturer
Let the opening question sink in for a few seconds, because many people will implicitly be holding this opinion.
Students
⍟ REST is not a network protocol! Nonetheless, there exists a widespread misunderstanding that REST is some kind of network protocol and you will often see boxes or arrows in system block diagrams labelled “REST”. Such diagrams are just plain wrong!
⍟ REST is a set of six architectural constraints, or design principles. Anyone so motivated could build a RESTful software system. As long as the software is designed to follows these 6 constraints, your home-grown software will be genuinely RESTful.
Slide 6)
Students
The example of client and server software being developed independently is demonstrated by the fact that browsers and webservers are developed and released independently of each other.
Slide 7)
Students
When a browser communicates with a proxy server, it does so in exactly the same way as it would if it were communicating directly with the target webserver.
This is an example of the layering principle in REST. The browser should not care whether the server referenced in the URL is the actual server that will answer the request, or some intermediate server that acts as either a proxy server or load balancer.
Slide 8)
Students
Stateless communication is one of the defining features in RESTful communication. However, this constraint is often misunderstood to mean that the server is not permitted to hold any form of state information about the client.
This is not the case: if the server chooses to hold state information about the client, that’s fine. This requirement simply states that the client must always know and be able to identify the session state held by the server.
Therefore, it is the client that indicates which step of business process must be performed next, rather than the server.
This is typically achieved by sending the browser various cookies such as session state and a CSRF token.
Side 9) Lecturer
This is where we now start getting into the core concepts of REST. These are the principles that many people might already know about, but probably not as being part of the REST design paradigm.
Lecturer
When you come to mention the details of the CREATE, READ, UPDATE and DELETE operations, it is important to point out that these are just your “starter set” of basic, general purpose operations. The reason that these operations were chosen as the fundamental set is because their names mean the same thing to all people in all places at all times.
However, it is perfectly possible that you might need some custom operation that has a specific meaning and that exists only within a specific context. In this case, OData (which is a fully RESTful implementation of these design principles) allows for custom operations to be created.
Tell the students that in one of the later exercises, they will implement a custom operation.
Students
⍟ A “uniform interface” is one in which the operations it implements always mean the same thing to the participants at all times.
Firstly the server has to provide the client with some consistent representation of a resource it is holding. In OData, this achieved by the server sending an XML or JSON message to the client that conforms to a known structure.
⍟ Once the client has received a representation of the server side resource, it must also be provided with some means for altering (or manipulating) the state of that resource.
This is where the CREATE, READ, UPDATE, DELETE operations have been defined, since these four operations are the most fundamental that can be performed by a client on a server-side resource. ⍟ In order for a server response to be considered “RESTful”, it must be structured in such a way that the client does not need to make second request to the server in order to obtain further clarification or explanation of the information in the first response. In other words, all REST communication must be self-describing.
⍟ REST defines the hypermedia link is as the only acceptable mechanism by which the client can manipulate a server-side resource.
This single principle has been isolated from the other REST principles and given the acronym HATEOS, or “Hypermedia As The Engine Of Application State”
Slide 10)
In order to improve communication efficiency, servers should define whether or not the information they transmit is cacheable.
In this way, if a client requires the same information again, it can look in its local cache to find it rather than issue duplicate server requests.
Slide 11)
If a client detects that it does not have the correct capability to handle the information it has received (or is about to receive), it can make a request to the server to send some executable coding that will extend its functional capability.
Slide 12)
The HTTP protocol that drives the World Wide Web is an example of a fully RESTful communication system.
3. Chapter 1.3 – Introduction to OData
Lecturer
This chapter is not intended to be a detailed description of all the minute details of the OData protocol. Instead, it is designed to give an overview that covers sufficient concepts and details that a developer will be fully conversant with an OData message coming out of a SAP NetWeaver Gateway server.
Slide 5)
This is a repeat of slide 6 from chapter 1. See notes from that slide.
Slide 6)
Lecturer
At this point, it is worth asking if everyone understands what the word “syndication” means. This is not a commonly used term in modern English and many people (especially non-native English speakers) may well not understand this word.
A “syndicate” is where people have pooled their resources together to achieve some larger task that an individual could not achieve on their own. For instance, a buying consortium could also be described as a “purchasing syndicate”.
In journalism “to syndicate” means to take a document or image and simultaneously publish it through multiple outlets.
Students
⍟ The Atom Syndication protocol does nothing more than provide a read-only, XML description of: • Various documents or “feeds” that are available from a website
• Within a feed, the consumer will find zero or more units of information known as “entities” ⍟ The Atom Publishing protocol extends the Atom Syndication protocol in that it allows the XML data provided by Atom Syndication to be manipulated using HTTP.
The problem with both of these Atom formats is that they do not provide a mechanism for describing the data being transported. Therefore, before you can consume an Atom feed, you must already
understand the structure of the data you are consuming. In other words, the Atom protocols are only partially RESTful because they are not self-describing.
Slide 7)
OData adds the ability to define the metadata of an Atom message. This in turns means that an OData message can now be consumed by an external service without that service first needing to know the message’s structure. In other words, the OData extension of an Atom feed means that the consumer can obtain a description of data in addition to the data itself.
Slide 8)
Lecturer
At the time of writing his document (early May 2012), Gateway 2.0 SP3 is the current release. SP3 only supports OData messages in XML format, but as of SP4 (mid-May, 2012), the SAP NetWeaver Gateway server can send OData messages in JSON format. This capability will require not only a service pack upgrade, but also a kernel patch (patch level 116).
Since this training course has been built on SP3, all the subsequent examples of OData messages will be shown in XML format.
Students
⍟ The Gateway server will be able to output an OData message in JSON format once SP4 is installed and the kernel has been patched.
Slide 9)
Students
The starting point for consuming an OData service is to issue the URL for the service’s Service Document.
Slide 10)
The XML received in the OData Service Document is always structured with a <service> element as the root element, under which is a <workspace> element.
Within the <workspace> element is a single <title> element followed by zero or more <collection> elements.
Slide 11)
Slide 12)
The URL used to derive an OData service’s Service Document is known as the “Base URL”.
When working with an OData message in XML format (as opposed to JSON format), the base URL is always listed as the xml:base parameter of the <service> element.
Within the Service Document, the URLs that point to collections provided by that service are always listed as URLs relative to the base URL.
Slide 13)
Lecturer
The purpose of this slide is to show the correlation between the structure of an OData XML response and the structure of the business data in the underlying SAP system.
Slide 14)
Lecturer
The screen shot shows an Atom <feed> element (highlighted in red) that contains a single <entry> element. This is a simple case that has been edited in order to fit on the screen. Typically an Atom feed will contain any number of entry elements starting from zero.
This example shows a list of film genres available from the Netflix website. A single entry from this collection is shown, the genre “Action – Adventure”.
Slide 15)
Lecturer
Point out that a single <entry> element within a <feed> corresponds to all the data associated with one row of an ABAP table.
This is much more than just the column data itself.
Slide 16)
Slide 17)
Lecturer
The entry contains two <link> elements.
The first allows the consumer to reference this entry individually. There is also a <link> element that allows the consumer to obtain a list of all the film titles within this specific genre. This is known as a navigation link – more about these later.
Slide 19)
Slide 20)
Lecturer
Point out the fact that it is not mandatory for a consumer to retrieve the service’s metadata document. However, it is typical to do so.
Due to the fact that the service’s metadata document provides a complete description of the service’s interface, any tool that can consume this description immediately has a complete understanding of the structure of data supplied by the service.
Slide 21)
Lecturer
Any property or element name that is prefixed with the sap: namespace is an SAP extension to the OData standard.
This is particularly necessary for defining things like currency fields or field labels derived from the ABAP data dictionary.
Slide 24)
Lecturer
This data model will be used throughout this training course. It is not a complex data model, but it contains sufficient functionality to illustrate all the main features of OData.
Slide 25)
Lecturer
Here is the first time where we see the relationship between an HTTP method and an OData
operation. This will be covered in more detail later, but now is good time to ask the students if they all understand what is meant by an HTTP “method”.
Unless people have specific experience with Web Development, then it is likely that they will not have a good understanding of what purpose the HTTP methods GET, PUT, POST, DELETE etc. actually serve.
Before proceeding, you should explain what HTTP methods are, and how they affect the communication between the browser and the web server.
Slide 26)
Lecturer
The same information is shown on this slide as was shown on slide 12, but instead of using the Netflix website, we’re using a Gateway example of the kind that we will see all through the remainder of this course.
Slide 27)
Slide 28)
Lecturer
The $filter command is specified as a query string parameter. Therefore before starting into description of this command’s behaviour, you should first make sure that everyone understands what a “query string” is and how to build one.
? Means “start of query string”
<name>=<value> Any number of ampersand separated name/value pairs
E.G. http://someserver.com/somepage?firstName=Harry&lastName=Hawk
Having described this, you must now contradict yourself and point out that the syntax of an OData $filter command somewhat breaks the above rule!
The value of the $filter command is itself a condition that could consist of multiple clauses. This syntax is very powerful since it allows you to apply complex search parameters to a collection. See http://www.odata.org/developers/protocols/uri-conventions#FilterSystemQueryOption for more details.
Slide 29)
Lecturer
The $top and $skip commands are query string parameters that follow the normal syntax.
For generated Gateway Services, the functionality of the $top command is provided automatically, but $skip is not available.
For customer written Gateway Services, you must explicitly write your service to recognise and respond to these commands, otherwise nothing will happen!
Students
⍟ The $top command specifies how many entries are to be returned. Unless used in conjunction with the $skip command, these entries are always taken from the top of the collection.
⍟ The $skip command omits the specified number of entries starting from the top of the collection ⍟ By using both $top and $skip together, you can implement paging.
⍟ View the first page by showing only the top 10 entries
⍟ View the second page by skipping the first 10 entries and showing only the next 10 ⍟ View the third page by skipping the first 20 entries and showing only the next 10 ⍟ The OData website contains more information on this topic
Slide 31)
Students
The syntax for reading a single entity from a collection is provided with the first <link> element found within an <atom:entry> element. This is the entry’s self-reference.
Slide 32)
Lecturer
Here is where the OData URL syntax can become a little confusing since the syntax for filtering the elements of a collection or paging uses query string syntax. However, the OData server needs to be able to distinguish between a QUERY operation and a READ operation. The way this is achieve is to use a non-conventional query string syntax.
In order to uniquely define a single entry within a collection, you must supply that entry’s “key predicate”.
Students
Notice that the syntax for defining the element to be read is not the normal query string syntax. Instead you must create what is called a “Key Predicate”. This is a comma-separated list of name/value pairs enclosed within parentheses.
The reason different syntax is used in the URL is so that the server can distinguish between a QUERY operation and a READ operation. If the URL references an OData Collection with a normal query string, then a QUERY operation will be performed. However, if the OData collection is referenced with an additional key predicate, then you are attempting to identify a single entry within the collection. Therefore, a READ operation is performed.
Slide 34)
Lecturer
The purpose of this slide is to provide a contrast between the XML returned by QUERY and READ requests.
Students
⍟ A QUERY operation will return zero or more entries. Therefore, the XML will always be enclosed within an <atom:feed> element.
⍟ If the QUERY operation locates an entries, these are supplied within <atom:entry> elements inside the <atom:feed> element.
Slide 35)
If a READ operation is performed, then at most, a single entry will be returned. Therefore, the XML will be supplied as a single <atom:entry> element. If zero entries are found, then the
Slide 37)
When the Atom protocol was defined, various standard fields were included in the <atom:entry> element. Since these fields are recognised by software that parses Atom feeds, it is useful to be able to map OData property values into these standard Atom fields (known as elements).
Slide 38)
Slide 39)
If a browser (in this case Firefox) formats an Atom feed, it will present the user with the contents of the <atom:title> element.
However, in this case, no explicit mapping exists between an OData field in the Gateway Service and the <atom:title> element; therefore, the Gateway server use the entry’s URL as a substitute value.
Slide 40)
Now, an explicit mapping has been made from one of the OData properties to the <atom:title> element.
3.1 Appendix
Slide 44)
The OData and Atom standards use different terminology to describe the same objects.
These terms can be used interchangeably; however, in the XML, the Atom terminology is used, and within the ABAP coding used for creating custom Gateway services, the OData terminology is used.
Slides 46, 48, 49)
4. Chapter 2.1 – RFC & BOR Generators (Read
Only)
Lecturer
When going through these slides, it is a good idea also to follow the instructions they give in the ABAP editor. These slides act very much like a how-to guide; however, you should always be a practical demonstration rather than simply conducting another session of “death by PowerPoint”.
Slides 5, 6, 8)
These slides are self-explanatory.
Slide 10)
Lecturer
Before diving into the details of how the generator tool works, you should explain the fundamental principle that each of the CRUD operations exposed by a Gateway service needs to be implemented by mapping it to existing functionality within the SAP system.
By “existing functionality”, we mean a BAPI or a custom written remote-callable ABAP function module, or a simple Dynpro screen.
In the screen shot, point out the fact that each of the operations, QUERY, READ, UPDATE and CREATE is mapped to a specific BAPI.
Slide 12)
Lecturer
Emphasise the fact that the “OData Channel” check should not be switched off for several reasons: • The Generic Channel object model is being deprecated
• The structure of ABAP objects generated by the OData Channel object model is much simpler than that generated by the Generic Channel
• You cannot use the new debugging facilities with the Generic Channel object model (i.e. the sap-‐ds-‐debug=true query string parameter)
Slide 13)
Lecturer
What might be a little unusual here is the fact that we select “Remote Function Call” yet on the next few slides, we will be using BAPIs. This is not wrong, because all BAPIs are simply RFC modules that have been written to implement the method of a business object.
All BAPIs are RFC modules, but not all RFC modules are BAPIs.
The only implication of this design decision is that if you call a BAPI as if it were a normal RFC module, then the Gateway Framework quite reasonably assumes that the RFC module will take care of its own database COMMITs. All BAPIs however rely on the fact that in the same ABAP session that they have executed, a subsequent call to BAPI_TRANSACTION_COMMIT will be made. If you call a BAPI as if it were an RFC module, then there will be no subsequent call to BAPI_TRANSACTION_COMMIT and any updates made by the BAPI will be rolled back when the invocation finishes.
To avoid this problem, apply SAP note 1688265. The training system has had this note applied.
Slide 15) Lecturer
Screen shot is not shown here due to overlapping animation events.
This slide simply shows how to use the search tool to locate the required function modules.
Slide 16)
Slide 18)
Lecturer
The important point here is that BAPI_BANK_GETLIST has a mandatory input field – BANK_CTRY. MAX_ROWS is also flagged as mandatory, but the coding in the BAPI accepts an initial value in this field.
If we left the field mapping in the state shown in this screen shot, we would create a situation in which the QUERY operation could never run successfully. This is because a mandatory field has not been mapped to the OData interface, neither has it been assigned a constant value; therefore, no matter what parameter values you try to specify in the client, the function module will always issue the error message that “Bank Country has not been specified”.
Remember that the first time we attempt to run this service, we will have deliberately left out the BANK_CTRY field from the OData. This is to illustrate what goes wrong if mandatory input fields are forgotten.
Slide 19)
Lecturer
Describe how to add the mandatory input field to the OData interface (that is, the column on the right labelled “Mapping Route”). This column name is not really that helpful. It should really say something like “Field in OData interface”.
⍟ The BANK_CTRY field needs to have its mapping route changed, so select the filed by right-clicking on it and press “Change Mapping Route”
⍟ A pop-up will be displayed in which you can select the field in the OData interface to which the selected field should be mapped.
⍟ Once the mapping selection is complete, the name of the field to which the BAPI field is mapped is shown in the Mapping Route column.
Slide 20)
Lecturer
Alternatively, you might have a situation in which the mandatory input field does not need to be available in OData interface, because it will only ever have a fixed value.
In this case it is acceptable to omit the field from the OData interface because you have defined a constant value for the field.
IMPORTANT
Even though the constant value is defined within the ABAP system, you must still follow the OData syntax rule that all non-numeric parameter values must be specified in single quotes.
⍟ Select BANK_CTRY and press Set Constant Value
⍟ In the popup window, enter the required static value – do not forget to enclose it in single quotes! ⍟ Press enter and the value is now assigned.
Its important to understand here that the value BANK_CTRY will still not appear in the OData
interface. So no matter how hard you try, you will never be able to override the static value by passing in a value in the URL.
Slide 21)
Lecturer
This slide does not show a configuration step. Instead it highlights the fact that the person generating this Gateway service needs to understand not only how to call each BAPI, but how the data coming out of one BAPI should be used to supply input values to the next BAPI in the sequence of business process steps.
The typical sequence of operations is QUERY, then READ, then UPDATE. Therefore, when creating a Gateway service, you need to determine which fields on the output side of the QUERY operation will be needed to supply information to the input side of the READ operation. Similarly, the data coming out of the READ operation must be mapped to the input values belonging to the UPDATE operation.
Slide 22)
Lecturer
By preparing the students with the comments of the previous slide, you have now laid the foundation of why it is necessary for a Gateway service to have at least one key field.
Once one or more key fields have been defined, they become the fields in which data can be transported out of one operation and into another.
Slide 23)
Lecturer
In the ABAP system, show how the data coming out of the QUERY operation is placed into the key fields, which are then used as input to the READ operation.
Slide 25)
Lecturer
Although the SAP system does not enforce this, a valid OData service should always implement at least the QUERY and READ operations.
Slide 26, 27)
Slide 28)
Lecturer
All the fields that appear in a data structure on the output side of a BAPI or RFC interface will need be flattened. What this means is that the fields have their mapping route changed so that they belong to the root node rather than (in this case) BANK_ADDRESS.
The reason for this is that currently, a generated OData Service cannot supply fields in a data structure without you needing to issue a second HTTP request from the client. By flattening the data structure, all the data is presented to the client in a single HTTP request.
Also, the data coming out of a READ request must typically be supplied into a subsequent UPDATE request. This cannot be done by a generated Gateway service if the fields are part of a data structure.
Slides 29, 30, 32, 34-37)
Slide 39)
Lecturer
The procedure shown here assumes that the Gateway Service has been built in the same system as the Gateway Hub. This will always be true for generated services, but for custom developed OData Channel services, this assumption will not necessarily be true.
If a customer developed OData Channel service is to be exposed, then you will need to click on the “Add Service” button, then specify the system alias of the system in which you developed the service. Only then can the service name be chosen from the list shown in the screen shot.
Slide 40)
Lecturer
As mentioned previously, the service will only appear immediately in this list if it was created in the Gateway Hub – all generated services will therefore appear here immediately.
The easiest way to locate a service is to sort the list by external name.
Slides 41, 42, 44-47)
Slide 48)
Lecturer
Hopefully, you will not have forgotten to leave out the BANK_CTRY field from the OData interface – otherwise, you will not be able to demonstrate this error.
Slide 49)
The BANK_CTRY field that was omitted from the interface is now added and the service is regenerated and rerun.
Slide 50) Lecturer
Screen shot is not shown here due to overlapping animation events.
The important point to emphasise here is that the value of the $filter query string parameter, is itself, a selection clause with it own internal syntax.
There must be a space, or a URL encoded space (%20) on either of the logical operator. All non-numeric values must be enclosed in single quotes.
Slide 51)
Lecturer
Now that the $filter parameter has been used to define a value for the bank_ctry field, the Gateway service works correctly.
Slide 52)
Lecturer
Refer back to the chapter in which we introduced OData.
Within each <atom:entry> element in a collection, there is an <atom:id> element that contains the full URL for accessing that particular collection entry.
Notice the syntax used to access a specific element uses a key predicate, not a $filter command. This is how we can change a QUERY request (that returns a potentially large number or entries) in to READ request that returns at most, a single entry.
Slide 53)
5. Chapter 2.3 – RFC & BOR Generators
(Update)
Slide 3) Lecturer
By now, everyone should have successfully created a Gateway service that can perform the read-only operations QUERY and READ.
Slides 5-13) Lecturer
The process described by these slides is self-explanatory, but the important thing here is that you show the students the steps in the ABAP editor, not just in PowerPoint.
Slide 15)
This slide introduces the concept that trust relationships that exist between browsers and web servers can be exploited.
Simply using a modern browser blocks an XSS attack – it is not SAP’s responsibility to prevent this type of attack since it is an exploitation of the trust a browser (or user) places in a web server. However, a CSRF attack exploits the trust a web server places in a supposedly authenticated user. The vendor of the server-side software must protect against this type of attack. Therefore SAP provides such a protection mechanism.
Slide 16)
Lecturer
An explanation of the Cross-Site Scripting (XSS) attack is presented for completeness.
This type of attack cannot be prevented by any software written by SAP. It is the browser vendor’s responsibility to detect and prevent this type of attack.
Slide 17)
Lecturer
This type of attack cannot be prevented by any software written by SAP. It is the browser vendor’s responsibility to detect and prevent this type of attack.
