GW100

SAP NetWeaver Gateway 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

1.00

First official release of this guide

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   13.   Chapter 6.1 – Gateway Service Consumption................................................................105  

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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 0.4.1

Configuring the WTS Environment 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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

6. You will next be asked if this training course requires unique group numbers.

Answer “Yes” to this question. 7. You will next see a screen in which the list of created users is displayed.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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”. 9. You will now see a screen in which each user’s change request is listed.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver 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 selfdescribing. 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!

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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 ⍟ The backend system requirements are identical to those described on the previous slide.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver 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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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 development skills are not available.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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. However, it could be…

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

Slide 19)

…the backend server – as long as the installation of add-ons is permitted.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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. However, is only for development convenience. It is not a requirement.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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. In other words, do not use a name starting with Z or some other technical internal name.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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!

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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. ⍟ The World Wide Web is the best example of a RESTful system.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

⍟ 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” ⍟ HATEOS is generally regarded as the core concept of REST.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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. This is an academic way of describing what happens when a browser requests a JavaScript file etc.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

Slide 12)

The HTTP protocol that drives the World Wide Web is an example of a fully RESTful communication system. The four fundamental operations are described using the acronym CRUD.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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. ⍟ In SP3 and earlier, a Gateway system can only output OData messages in XML format.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

Slide 9)

Students The starting point for consuming an OData service is to issue the URL for the service’s Service Document. The Service Document provides the top-level description of an OData service.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

Slide 10)

The XML received in the OData Service Document is always structured with a element as the root element, under which is a element. Within the element is a single element followed by zero or more elements. Slide 11) This slide is self-explanatory

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

Slide 14)

Lecturer The screen shot shows an Atom element (highlighted in red) that contains a single 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”.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

Slide 15)

Lecturer Point out that a single element within a 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) This slide is self-explanatory

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

Slide 17)

Lecturer The entry contains two elements. The first allows the consumer to reference this entry individually. There is also a 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) This slide is self-explanatory.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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. This is how OData proxy generator tools work.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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) This slide is self-explanatory.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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”

=

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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

Slide 31)

Students The syntax for reading a single entity from a collection is provided with the first element found within an element. This is the entry’s self-reference.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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. Any non-numeric value within a key predicate must be given as a quoted string.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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 element. ⍟ If the QUERY operation locates an entries, these are supplied within elements inside the element.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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 element. If zero entries are found, then the element will be empty.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

Slide 37)

When the Atom protocol was defined, various standard fields were included in the 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).

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

Slide 38)

This slide describes which fields are available as standard Atom elements.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

Slide 39)

If a browser (in this case Firefox) formats an Atom feed, it will present the user with the contents of the element. However, in this case, no explicit mapping exists between an OData field in the Gateway Service and the element; therefore, the Gateway server use the entry’s URL as a substitute value.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

Slide 40)

Now, an explicit mapping has been made from one of the OData properties to the element. More about how this mapping is achieved coming later…

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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) These slides are self-explanatory

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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)

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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) This slide is self-explanatory.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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) These slide are self-explanatory.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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) These slide are self-explanatory.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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) These slides are self-explanatory.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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. Field names are case-sensitive!

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

Slide 52)

Lecturer Refer back to the chapter in which we introduced OData. Within each element in a collection, there is an 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) This slide is self-explanatory.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

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.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

Slide 18)

A Cross-Site Request Forgery (CSRF) presents both Web users and service providers with a potentially serious exploitation possibility. Once a user has provided a website with valid authentication credentials, that server considers to user to be authenticated and trusts all subsequent communication from the authenticated browser session.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

Slide 19)

Lecturer A CSRF attack exploits the trust a server places in an authenticated browser session. If the user can be convinced to click on a web address that directs him to the hacker’s website, the attack can potentially be launched.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

Slide 20)

Lecturer Prevention of a CSRF attack is easy enough to achieve. The server side software must generate a random token that provides additional authentication that, combined with the session cookie, can distinguish the genuinely authenticated user from a user trying to exploit the authentication.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

Slide 21)

Lecturer Both XSS and CSRF attacks are real threats to the security of Web based business applications, but both can be defeated by a combination of modern browsers together with the X-CSRF-Token protection mechanism provided by the SAP NetWeaver Gateway server. The SAP NetWeaver Gateway system prevents CSRF attacks by issuing a token value to the browser that must be returned whenever an operation is performed that alters a server-side resource (e.g. UPDATE, CREATE or DELETE etc). The token value itself is simply a string of random characters, but the important point is that such a string cannot be guessed by a third party attacker, since the attacker’s fraudulent URL is generated on a server that knows nothing of the token value. Slides 23-27) These slides are self-explanatory.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

Slide 28)

Lecturer In SP3, the OData software that underlies the Gateway software layer was completely replaced with a fully compliant layer that implemented the full OData standard. The only problem here is that now all XML elements for properties of data type Edm.String are no longer allowed to be null. In other words, an element such as is no longer valid. Instead, the parameter m:null='true' must be added. If you do not use the m:null='true' parameter, and SAP Note 1690310 has not been applied to a Gateway 2.0 SP3 system, you will get a “Malformed URI syntax” error.   The problem here is that when you perform a READ operation, the XML you receive will contain null XML elements for any properties that have no value. Therefore, in order for this XML to form the valid input to a subsequent UPDATE or CREATE operation, it must be checked and adjusted to ensure that no properties of type Edm.String are left implicitly null. The problem for OData SDKs here is that the actual XML needs to be edited before it becomes valid. SAP Note 1690310 implements a relaxation of this requirement for fields of type Edm.String. SAP strongly recommends that this note be applied in all Gateway 2.0 SP3 systems. This relaxation is standard in SP4. Fields of data types other than Edm.String, may not be left null. Instead, a suitable initial value must be supplied. SAP Note 1690310 has been applied to the GW100 training system, so the use of this extra parameter is not needed during the exercises. Slide 29) This slide is self-explanatory

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

Slide 30)

Lecturer For the initial READ operation, the HTTP header field X-­‐CSRF-­‐Token must be set to Fetch. Once the CSRF token has been returned to the client, this value must be returned to the SAP NetWeaver Gateway server on all subsequent requests that could change the state of a server-side resource. The RESTClient does not allow copy and paste from its display areas, so in order to access this value, a query string parameter must be added to the request. Alternatively, if you have performed the READ operation with Firebug running, then you will be able to copy the value from the Header response section of the Net tab.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

Slide 31)

Lecturer There are several important points you should emphasise concerning the sap-­‐ds-­‐debug=true query string parameter: 1. It will have no effect if added to the URL of a Gateway service built using either: a. Gateway 2.0 SP2 b. Generic Channel runtime framework 2. It should only be used on READ operations 3. Using this query string parameter on UPDATE or CREATE operations will result in an error. Slides 32 & 33) These slides are self-explanatory.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

Slide 34)

Lecturer It is very important that the students do not interpret an “HTTP 200” status code (seen after a successful GET request) to mean that the PUT request (UPDATE operation) was successful. Somewhat counter-intuitively, for an OData UPDATE or CREATE operation, an HTTP status code of 200 means “Nope, something went wrong”. The correct response to look for is HTTP 204 “No Content”. Slides 35, 37-41) These slides are self-explanatory.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

6. Chapter 3.1 – Monitoring Lecturer These slides are self-explanatory.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

7. Chapter 4.1 – Developing a Model Provider Class – Part 1 Slides 5-9) Lecturer Give a recap of the general development procedure for creating a custom written Gateway service. Slide 6) It is helpful to point out that the Model and Data Provider classes are not required to have any programmatic relationship to each other. For those people who are new to Gateway, this goes against their expectation because most programmers will assume that if the Data Provider class is going to supply information to the client, and that the Model Provider class defines the interface for that data, then it seems only natural that the Data Provider class would make direct reference to the Model Provider class in order to understand the shape of its own interface. This however, is not the case. In spite of the fact that the Model and Data Provider classes are associated only by configuration, for convenience, it is useful to have the data types within the Model provider classes defined as public, so that the Data Provider class can reference them. Typically however, the model provider will have public data types that can be referenced by the data provider class. This ensures that data structures and objects used by both classes are identical. Slides 11-17)

Lecturer These slides are self-explanatory in terms of the content, but the origin of the data model diagram requires some explanation. This diagram is created using the data modeller in Microsoft’s Visual Studio 10. This is a standard tool that comes with Visual Studio and will create an .edmx file. This file can then be imported into the Gateway system and used to generate a Model Provider class.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

At the moment, this tool is not covered in detail in this training course because before people use a tool to generate coding, they should first be able to write the code manually. A later version of GW100 will cover the model provider generator tool. Slides 19-22) Lecturer These slides are self-explanatory. Slides 24-26) Lecturer These slides are self-explanatory, but before diving into the coding, it would be a good idea to familiarise people with the interface of the model provider class. This interface is inherited from class /IWBEP/CL_MGW_ABS_MODEL. Slide 28)

Lecturer The next 4 slides are very important! In chapter 1 section 3, we introduced the idea that OData properties could be mapped to standard Atom elements. These slides now explain how the coding for this functionality works. For each Atom element that can be using as a mapping target, there is a method on the OData property object: set_as_title()   set_as_author()   set_as_updated()   set_as_published()   Calling any one of these methods will cause the value of associated OData property to be mapped to the Atom element named in the method name.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

Slide 29)

Lecturer Here’s the important part! Calling this method does two things. The value of the Boolean parameter determines whether the OData property will appear in the element. Excluding an OData property from the element could potentially cause problems during a CREATE or UPDATE operation because even if this value is supplied in the incoming XML, the fact that you have explicitly excluded this value means that the supplied property value will never be supplied to the data provider class, and your operation will always fail will a “Malformed URI syntax” error message. Unfortunately, the SAP system provides is no further information about why the URI’s syntax is malformed… So this error may as well read “An error has occurred and I’m not going to tell you which one – good luck”. Slides 33 & 31) The slides show the difference in the resulting XML if the iv_keep_in_content parameter is set either to true or false.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

Slide 33)

Lecturer No matter how many times you warn the students, someone will always forget to update the class and structure reference string given in the bind_structure(  ) method call. Or they will complain that they have changed a data type in their model provider class but can’t see the change in the metadata. In this case, they have copied the sample solution and the class reference points not to their own model provider object, but the model provider object of the sample solution. At design time, the character string passed to bind_structure(  ) is just that – a character string. Its validity is not checked until runtime. This means that when you are writing the coding, you could enter any character string there you like (E.G. the recipe for chicken soup) and it would successfully compile. You will not discover whether the character string was valid until runtime. Therefore, tell the students to check the value carefully if they want to avoid runtime errors. Slide 34) Lecturer If there is an invalid class reference in the bind_structure() method call, then you will see an HTTP 500 error in the browser and a rather cryptic looking error in the error log. Slides 35 & 37) These slides are self-explanatory.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

8. Chapter 4.3 – Developing a Model Provider Class – Part 2 Slides 5-7) Lecturer These slides are self-explanatory. Slides 9-18) Lecturer These slides are largely self-explanatory, but the following point should be emphasised: • •

•

The Model and Data provider classes are independent ABAP classes that are not required to have any programmatic relationship with each other. In practice, it is helpful to create public types in the Model provider class and then use these as type definitions when declaring objects in the Data provider class. However, this is just for coding convenience, rather than a requirement. The name used for the “Technical Service Name” (also known as the “Internal Service Name”) will automatically become the External Service Name. Therefore, it is very important that the Technical Service Name is chosen to be meaning to the end user – I.E. it does not start with Z and does not use some internal object name.

Slide 15) Lecturer It is very important that the external name specified here is relevant and meaningful for the end user. The only unusual thing about this configuration is that the name you enter for the Technical Service name (formerly known as the Internal Service name), is automatically copied to the External Service name and becomes the name seen in the URL – and therefore probably by the end user. Slides 20-24) Lecturer These slides are largely self-explanatory, but the following points should be emphasised. Slide 20) Lecturer Point out to the students that they will need to log on to the Gateway Hub server in order to perform this configuration. Within the context of the SAP training environment, the backend server on which they are performing their ABAP development, and the Gateway Hub are one and the same server (i.e., an all-in-one installation). However, this deployment scenario for the Gateway add-ons is only to be used for training or intranet only service development. In a “real life” scenario, the customer or partner should have a separate Gateway Hub server. When the students are back in their own development environments, it is the Gateway Hub server they should log on to in order to perform the following Service Catalogue configuration. Slide 23) Lecturer When adding a new service, two things are important: 1. For consistency and ease of transport management, the package name used for development of the Gateway Service in the backend system should also exist in the Gateway Hub server. 2. When you press the “Add Service” button, if you get the rather cryptic error message “Not all mandatory fields maintained”, then this is due not to any information missing from the visible

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

fields on the screen, but rather to the fact that in definition of the System Alias, one or more fields has been left blank. In the System Alias definition, ensure that the “System Version” column is set to DEFAULT. Slide 24) Lecturer Depending on which browser you use to display the Gateway Service, you may see either the raw XML or a formatted Atom feed. Internet Explorer version 8 usually presents the raw XML. However, other browsers such as Chrome, Firefox or Safari detect that the MIME type application/atom+xml indicates an Atom feed, and will format the response accordingly. For the purposes of understanding the OData XML, the raw XML needs to be displayed. If a version of Internet Explorer that will present only the XML is not available, then you can view the indented XML in the Firefox RESTClient or by adding the query string parameter sap-­‐ds-­‐debug=true. Slides 26-28) Lecturer These slides are self-explanatory. Slide 31)

Lecturer It is important to point out that the $metadata command is not a query string parameter. It is simply appended to the end of the Gateway Service’s base URL. The terminating slash at the end of the base URL is important and should always be used. Slides 32-40) Lecturer Here it is very important to ensure that the students have a clear understanding of what XML is generated as a result of the various ABAP statements in the Model Provider class. Upon completing these exercises, the students will have a basic Model Provider class whose metadata can be displayed in a browser. As yet, this Gateway Service cannot deliver any business functionality.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

9. Chapter 4.5 – Developing a Model Provider Class – Part 3 Slides 4-10) Lecturer These slides are self-explanatory. Slides 14-17) Lecturer If you have time, then a demonstration of the Model Import tool in the ABAP system would be helpful. However, this is not essential. Slides 19, 21) Lecturer These slides are for reference only and do not need to be taught specifically.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

10. Chapter 5.1 – Developing a Read-Only Data Provider Class Lecturer This chapter covers the implementation of the QUERY and READ operations with our previously empty data provider class. Slide 5) Lecturer This slide is self-explanatory Slide 6)

Lecturer The typical architecture for the ABAP classes used by a Data Provider (DP) class is to have a top level DP class, below which there is one ABAP class per entity type. The top level DP class must always implement /IWBEP/CL_MGW_ABS_DATA as its superclass, but the ABAP classes used to implement the functionality of a specific entity type need only implement interface /IWBEP/IF_MGW_APPL_SRV_RUNTIME (as a starting minimum).

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

Slide 7) Lecturer This slide is self-explanatory Slide 9)

Lecturer This slide will become a key reference slide for people learning Gateway, as they need to understand how the different HTTP method and parameter combinations relate to the different OData operations. These OData operations are then implemented by the methods in /IWBEP/CL_MGW_ABS_DATA. Slide 10) Lecturer This slide is self-explanatory

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

Slide 11)

Lecturer The OData specification states that every OData service should implement both the QUERY and READ operations at a minimum. However, in the SAP implementation, this requirement is not strictly enforced. In class /IWBEP/CL_MGW_ABS_DATA, the default implementation of each of the method provided by interface /IWBEP/IF_MGW_APPL_SRV_RUNTIME simply raises a “Method not implemented” exception. So at worst, any attempt to invoke the unimplemented READ or QUERY operation will raise an exception that can easily be understood. As with the model provider class, before diving into the coding of the data provider class, it would be a good idea to familiarise people with the interface of the various methods such as GET_ENTITYSET and GET_ENTITY. This is necessary because all the values received from the client are parsed by the OData framework and supplied automatically to these methods. All the developer needs to know is in which parameter to look to find things like the query string parameter list, or the list or navigation paths or what the clauses are in a $filter command.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

Slide 12)

Lecturer The important point here is to emphasise the fact that the top-level DP class will always act as the point of entry to the entire Gateway Service. This class should not contain any functionality related to the specific entity types supplied by the Gateway Service. Instead, it should contain only that functionality necessary to interpret the incoming request and call the appropriate DP class for the required entity set. This principle applies no matter which OData operation has been requested. Slides 13-15) Lecturer These slides are self-explanatory Slide 16) Lecturer After completing these exercises, the students will have a Gateway Service that implements the QUERY and READ operations.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

11. Chapter 5.3 – Developing an Update Data Provider Class Lecturer This chapter covers the implementation of the CREATE operation and creating custom service operations. The UPDATE operation is not dealt with here as it is, in principle, very similar to the CREATE operation. What is dealt with however is the ability to implement a custom operation (known in OData terminology as a Service Operation). A custom operation is needed in a situation where, if you implemented the required functionality in a standard operation such as UPDATE, then you would violate the RESTful principle of a uniform interface. At this point you should refer back to the REST introduction chapter 2 (slide 9). Slides 5-7) Lecturer These slides are self-explanatory. Slide 9)

Lecturer The point here might seem to some people like an academic detail, but it can mean the difference between creating an OData service that is easy to consume, and just creating an OData service… In the case of our exercise, we need to implement functionality that allows a passenger to cancel their flight booking. Some developers might consider it a “clever” optimisation to have multiple parameters passed to the Booking’s UPDATE operation and then depending on which combination of parameters is received, to perform different actions. Well this is all very clever from a coding perspective, but not only does this make the interface much harder to consume, it violates the REST principle of having a uniform interface. It is much better practice to create a specific custom operation for each different variation of the UPDATE operation so

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

that the consumer can easily distinguish between cancelling a booking and updating the customer’s name (for instance). It could be argued that both of these actions fall under the general heading of UPDATE, but the point here is that a truly uniform interface means the same thing to all people in all places at all times. So and UPDATE performed to cancel a booking must be easily distinguishable from an UPDATE needed to alter the passenger name on a booking. Slides 10-16) These slides are self-explanatory Slide 17) Lecturer When the students have completed these exercises, they will have a Gateway Service that can create and cancel flight bookings.

12. Chapter 5.5 – Using Associations and Navigation Paths Lecturer The final step to implementing a fully functional Gateway Service is to provide the functionality behind Navigation Paths. OData allows for any number of associations to exist between the entity types in your data model. In fact, in large data models, it is perfectly possible to have chains of associations that connect seemingly unrelated entity types to each other. In this case, multiple navigation paths can be chained together and specified in a single URL. The problem here is that depending on the depth of Navigation Path being traversed, the logic in the top-level data provider class may well need to be rewritten. In our case the navigation paths are very simple, but even in this simple case, our top-level data provider class will need some alteration. The general principle here is that when examining a navigation path URL, in order to determine which entity type should be returned, you should always look at the last step in the navigation path, not the first. Here, we will implement a simplistic solution, but in real life, the top level data provider might well need to perform some complex logic to work out exactly what entity type should be returned to the client. IMPORTANT You should point out that in the coding of the Airport, Flight and Booking sample solutions used in the previous exercises, the coding necessary to distinguish the presence of a Navigation Path is already present, and therefore, only the top-level data provider coding needs to be altered. All the slides in this chapter are self-explanatory.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

13. Chapter 6.1 – Gateway Service Consumption Lecturer This final chapter is one in which only 2 of many development options have been taken. Since an OData service can be consumed by software written in pretty much any programming language, it is not possible to cover all the different options here. The following general points must be emphasised: • •

•

SAP does not impose any restrictions on how a Gateway service is to be consumed The Sybase Unwired Platform (SUP) software is a valid option for any customer wishing to connect mobile devices to an SAP backend system through SAP NetWeaver Gateway; however, customers are perfectly free to use any software they deem suitable. If a customer decides not to use SUP, this will not affect the support provided by SAP. Any programming language may be used to write an OData interface layer. The only criteria here are that the language must be able to: o Communicate using the HTTP/S protocols o Parse and construct XML or JSON documents

It is often the case that customers will feel uncomfortable with such a wide range of choice. Many of our customers (particularly the long-standing customers) expect SAP to sell them some toolset and provide a long list of best practices that are to be followed religiously. However, in order for SAP to meet its target of 1 billion users by 2015, we need to make data and functionality as accessible as possible. This mean that any barriers to consumption must to either completely removed, or lowered to the lowest possible level – hence the statement that we (SAP) will not impose any restrictions on how Gateway services are to be consumed. Slides 5-7) These slides are self-explanatory Slide 9) This slide shows the different OData proxy generation tools that are available. The Adobe Flash Builder tool is written by Adobe, but all the other tools are written by SAP. The main difference between the SAPUI5 libraries and the other SAP supplied proxy generation tools is that the SAPUI5 library does not create a static proxy object at runtime. Instead, it communicates with the Gateway server at runtime, adapting dynamically to whatever interface the OData Service currently has. This stands in direct contrast to all the other proxy tools because they create a static object at design time. If the OData server were to change after the proxy object has been generated, then the proxy object will need to be regenerated. Slides 10-14) These slides are largely self-explanatory in that they show screen shots from the use of each of the different proxy generation tools. The OData proxy generation tool for Eclipse contains both the Java and PHP code generators. Slides 16-12)) These slides are largely self-explanatory in that they show screen shots from the use of iOS proxy generation tool. This tool not only builds an OData proxy object, but can also wrap that proxy object in a basic application. These slides step through the process of creating an iPhone application to consume our flight example.

Speaker's Guide for GW100 "Building OData Services Using SAP NetWeaver Gateway"

14. Chapter 6.2 – Gateway Service Consumption Using Java Server Pages 14.1 Bank Service OData Interface Lecturer Before letting the students start this exercise, you should point out that their generated Bank service must not only work correctly, but also have no extra data structures in the interface. If there are any extra data structures (such as BANK_ADDRESS or BANK_DETAIL) present in the OData interface of their Bank service, then these structures will appear as unwanted Java classes when they run the Gateway proxy generator tool in Eclipse. The generator tool has no idea that these structures are not needed. The presence of extra data structures will not cause the exercise to fail, but it will complicate the process of creating a working application. Since there are a wide variety of mistakes that students could make, it is not possible for the instructions in the exercise to handle any situation other than the one that is currently documented – i.e. where the OData interface for the Bank service contains no data structures. Therefore, everyone should check that the OData interface of the Bank service is correct (i.e. has no data structures in its interface) before proceeding with this JSP exercise.

14.2 Potential Tomcat Context Error Lecturer It can happen that students will get a Tomcat error message saying that there is a duplicate context entry for the JSP exercise they are performing. This happens when a duplicate entry appears at the end of the servers.xml file. (How this duplicate entry appears is not entirely clear). As you can see from the highlighted text below, the path for the GW100_Bank_JSP_Exercise points to the solution, not the exercise. Simply replace the highlighted text with Ex and the problem is corrected.