Managing an SAP Gateway Service

The SAP Gateway Service Builder and ABAP Development Tools support the development and generation of OData services. With service generation, you can create OData services without writing a single line of code.

The SAP Gateway Service Builder supports all phases in the development of OData services:

Service Definition Phase

In this phase, you create a project to bundle all the artifacts that are needed to develop a service in one central location.

Data Model Definition Phase

In this phase, you define the model (entity types, entity sets, associations, and so on) that your service will be based on.

Service Implementation Phase

In this phase, you implement the operations that will be supported by the service.

Service Maintenance Phase

In this phase, the service is registered and activated in an SAP Gateway hub system.

The SAP Gateway Service Builder (transaction SEGW) is a design-time environment that provides a set of tools for the creation and maintenance of OData services in an application server (AS) ABAP. It supports developers throughout the entire development life cycle of a service.

To use the SAP Gateway Service Builder, you must either install the add-on IW_BEP or use a system based on AS ABAP 7.40 or higher.

The SAP Gateway Service Builder caters for the needs of both experienced and less experienced developers who want to expose data for easy consumption using a variety of platforms, frameworks, and devices.

While experienced developers have maximum flexibility to define a new service from scratch and integrate their own source code, less experienced developers can reduce the time and effort involved in creating services by generating services based on existing business objects.

In the SAP Gateway Service Builder, one SAP Gateway project represents one SAP Gateway service. Every SAP Gateway project consists of four parts visualized as tree branches:

• Data Model
• Service Implementation
• Runtime Artifacts
• Service Maintenance

The entity data model (EDM) of the SAP Gateway service is defined in the Data Model branch. Everything available in OData V2 can be defined here. Entity types define properties, navigation properties build on associations, associations set the cardinality of a navigation and so on.

When building the data model in the SAP Gateway Service Builder, you can create model components manually or import existing data structures:

• Data model from file
• Data Dictionary (DDIC) structure
• Remote Function Call (RFC)/Business Object Repository (BOR) interface
• (Elementary) Search Help

In addition, there are several wizards available to generate parts or even complete models based on ABAP repository elements.

In the Service Implementation branch, theSAP Gateway Service Builder allows you to easily navigate to the ABAP implementation in the ABAP Workbench (SE80) supporting the different OData operations of an entity set. For each entity set, five methods are generated to reflect the C(reate), R(ead), U(pdate), D(elete) operations. For developer convenience, the R in CRUD is split into a read and query method. This eases the development by separating the read operation of a single data set using a key from query operations like sorting or filtering.

For example, for an entity set called "ProductSet", the following methods are created:

• PRODUCTSET_CREATE_ENTITY
• PRODUCTSET_GET_ENTITY
• PRODUCTSET_GET_ENTITYSET
• PRODUCTSET_UPDATE_ENTITY
• PRODUCTSET_DELETE_ENTITY

In the Service Implementation branch, it is also possible to map the implementation of CRUD-methods to an ABAP repository element:

• Business Object Repository (BOR)
• Remote Function Call (RFC)
• Core Data Services (CDS) View
• (Elementary) Search Help

To take a mapping approach means that you manually relate the properties of an entity set to the interface parameters of a data source. The process of mapping data sources is similar for all data source types.

For BOR, RFC, and Search Help, the SAP Gateway Service Builder enables you to map CRUD-methods separately for each entity set. For the CDS views, the whole entity set is mapped to the business object rather than individual methods. Using both approaches, the implementation of the corresponding methods, such as PRODUCTSET_GET_ENTITYSET, is generated based on your mapping.

The Runtime Artifacts branch provides a list of ABAP classes and technical customizing entries generated based on the Data Model and Service Implementation. An SAP Gateway service is based on two types of ABAP classes:

• Model Provider Class (MPC)
• Data Provider Class (DPC)

The MPC defines the model and metadata of the SAP Gateway service. The DPC provides the implementation and functionality. Both class types are each realized in two ABAP classes:

• A base class purely generated based on the settings done in the SAP Gateway Service Builder.
• An extension class inheriting the base class for extending the generated code with manual development.

Both the MPC and DPC are registered as a technical model and service in customizing when the project is generated. In summary, every SAP Gateway project consists of at least the following runtime artifacts:

• Data Provider Base Class (ZCL_<SEGW_Projectname>_DPC)
• Data Provider Extension Class (ZCL_<SEGW_Projectname>_DPC_EXT)
• Model Provider Base Class (ZCL_<SEGW_Projectname>_MPC)
• Model Provider Extension Class (ZCL_<SEGW_Projectname>_MPC_EXT)
• Technical (Registered) Model (<SEGW_Projectname>_MDL)
• Technical (Registered) Service (<SEGW_Projectname>_SRV)

There may be more runtime artifacts like ABAP interfaces or classes generated by certain wizards, but never less.

The base classes contain generated business logic, which is overwritten every time the project is regenerated. For this reason, you should not modify the code in these classes, as the runtime generation overwrites their contents.

An extension class is a subclass of the base class that is created once, only when the project is generated for the first time. An extension class initially contains no logic. The SAP Gateway Service Builder provides the extension class for you to write your own code. Regenerating the project does not overwrite your code in the extension classes. Therefore, the service implementation takes place in the data provider extension class.

The technical model is a representation of the MPCs and the technical service of the DPCs in customizing. The model and service link the MPC and DPC classes to each other and the project wraps all together.

Any OData consumer connects to SAP Gateway using HTTP(S). When this happens, the following actions take place:

To expose an SAP Gateway service to the outside world, you register the service on FES. That is, you create an entry in the SAP Gateway service catalog of the FES. The following system prerequisites must be fulfilled:

• An RFC destination is defined in the FES connecting to the BES. A trusted RFC connection is recommended.
• A system alias is defined in the FES for the RFC destination to the BES.

To create an entry in the SAP Gateway service catalog, the technical service of the SAP Gateway service project is registered in the FES using the system alias. The technical service references the DPCs and is linked to the technical model, which references the MPCs. Therefore, it is possible to reach every part of the SAP Gateway service via the technical service.

The name of the technical service defines the external service name in the service catalog entry. Every OData request calls this external service name.

While the system alias in the FES connects the FES with the BES, the SAP Gateway alias in the BES connects the BES to the FES. This SAP Gateway alias is not needed to process any OData request, but it enables maintenance of an SAP Gateway service out of the SAP Gateway Service Builder. It is defined in the SAP Reference Implementation Guide (SPRO) of the BES using an RFC destination to the FES.

An SAP Gateway alias automatically appears in every SAP Gateway project in the Service Maintenance branch. Via this alias, you can register and maintain the service catalog entry (/IWFND/MAINT_SERIVCE), access the front-end error log (/IWFND/ERROR_LOG), and test the service (/IWFND/GW_CLIENT) in the FES. In a popup, you confirm to be redirected from the BES to the FES.

The SAP Gateway Service Maintenance (/IWFND/MAINT_SERVICE) provides a list of all the OData V2 services registered in the system. Complete management of the SAP Gateway services is carried out here. The transaction is divided into three areas:

• Service Catalog (service name, description, and many other settings)
• ICF Nodes (maintenance of the ICF services and testing of the service)
• System Aliases (maintenance of the connection to the back-end)

In the Service Catalog area, you can choose the Add Service button to search a technical service in a BES following the system alias and create a service catalog entry on the FES.

In the ICF Nodes area, you can choose the SAP Gateway Client button to open the /IWFND/GW_CLIENT to test the selected service on the FES.

The ICF Node button can be used to activate, deactivate, or delete the ICF node or you can jump directly in the HTTP Service Hierarchy Maintenance (SICF).

In the System Aliases area, you can choose the Add System Alias button to assign additional system aliases to a service catalog entry to enable routing of OData request to multiple BES.

OData V4 services are not published as single services, but rather service groups. Thus, OData V4 services must first be assigned to a service group in the BES, which is then published on the FES. The reason behind this concept is the cross-service navigation feature of OData V4 between services of the same group. This makes it possible to register and reuse smaller services with smaller metadata documents in multiple service groups.

A service group is registered and thereby created in the SAP Backend Service Administration (/IWBEP/V4_ADMIN) . The developer also registers and thereby adds services to service groups here. A service group including the registered services are part of the development process and therefore assigned to workbench requests. The service group is part of the URI for calling a services:

/sap/opu/odata4/sap/<service group>/<repository id>/sap/<service>/<version</

If a service group is published, a service of the group can be tested in the SAP Gateway Client (/IWFND/GW_CLIENT) by choosing the Service Test button after selecting a service from the list. A popup then asks if the service group is published locally or in a remote system.

The SAP Gateway Backend Error Log (/IWBEP/ERROR_LOG) can be accessed unfiltered by using the Error Log button at the top or filtered by the selected service with the Error Log button above the list of services.

The SAP Gateway Service Administration (/IWFND/V4_ADMIN) is used to publish service groups so that the services inside can be tested or consumed in applications. The Service Test button opens the SAP Gateway Client for the selected service.

The SAP Gateway Error Log (/IWFND/ERROR_LOG) can be accessed unfiltered by using the Error Log button at the top or filtered by the selected service with the Error Log button above the list of services.

The available system aliases can be accessed by choosing Routing Configuration at the top. This opens the /IWFND/ROUTING transaction.

To jump back to the SAP Backend Service Administration, choose Service Implementation above the list of services. The /IWBEP/V4_ADMIN opens in a new window for the selected service.

Using the SAP Gateway Client (/IWFND/GW_CLIENT), all functions of an OData service can be tested. To test a service, perform the following steps:

1. Select the HTTP method, such as GET, POST, PUT, or DELETE via the appropriate radio button.
2. Enter the request URI in the Request URI field. Some frequently-used URI options can be added to the URI by pressing the Add URI Option button. The EntitySets button provides a list of valid entity sets for a service, if the ICF-path of the service is already entered in the Request URI field.
   Hint

   Starting the SAP Gateway Client via the SAP Gateway Service Maintenance after first selecting a service there, fills the Request URI field with the correct ICF-path of this service.
3. In the HTTP Request frame on the left, you can enter the desired request data. Alternatively, you can upload the request data from a local file by choosing the Add File button in this frame.
4. To send the request, choose the Execute button. The SAP Gateway Client displays the corresponding HTTP Response on the right.

For better usability, the SAP Gateway Client enables you to create test cases by storing the HTTP request data in an XML format. This feature saves time and effort if you want to execute test cases more than once like in a test-driven development. The test cases are organized in groups and you can upload and download the test data for reuse.

It is possible to jump from the SAP Gateway Client to other SAP Gateway transactions. The Service Administration button at the top brings you back to the service catalog in the SAP Gateway Service Maintenance(/IWFND/MAINT_SERVICE). The Error Log button opens the SAP Gateway Error Log (/IWFND/ERROR_LOG) filtered for the error you may encounter in the HTTP Response.

There are two error logs in SAP Gateway:

SAP Gateway Error Log (/IWFND/ERROR_LOG)

This error log shows errors occurred during analysis of an OData request. Some part of a request may not meet the definition of the service's data model like a wrong key format or even the OData standard itself like unsupported query options. An error caught here also means that the implementation of the service was not called at all because the request was wrong in the first place.

SAP Gateway Backend Error Log (/IWBEP/ERROR_LOG)

This error log shows errors occurred during processing of the request in the service implementation. The request itself was perfectly fine but some data provided may be wrong like a key value, which just does not exist on the database. Of course there could also happen some programming error including a short dump. An error caught here means that something has gone wrong in the ABAP code.

In a hub deployment, the /IWFND/ERROR_LOG is used in the hub or FES and the /IWBEP/ERROR_LOG in the BES. In an embedded deployment, both error logs reside in the same system but still show different kinds of errors. So it is important to always check both error logs if you encounter a problem with a service.

Both error logs enable you to do the following:

• Identify the precise time and location of errors in the source code.
• Determine how often an error has occurred.
• Perform root-cause analysis.
• Reproduce and correct errors.

An error log comprises the following two screen areas:

Overview

The Overview area lists all error IDs and their attributes, together with the date and time at which the particular errors occurred. By default, errors are displayed chronologically with the newest error at the top of the list. You can display the error information and descriptive error texts to obtain more detailed information about a particular error and also see how often and where the error has occurred.

Error Context

The Error Context shows the details of an error selected in the Overview. It provides several features to get a deeper look in certain parts of the error like the call stack or the full request and response data. To check whether or not a certain error still occurs after you have changed your service implementation or customizing, you can reproduce errors using either of the following replay options offered by the Replay button:

• SAP Gateway Client (/IWFND/GW_CLIENT)
• Web Browser.

Via the Backend Monitor button in the /IWFND/ERROR_LOG, you access the /IWBEP/ERROR_LOG in the BES.

Like for the error log, there are also two tracing tools available in SAP Gateway:

SAP Gateway Tracing Tools (/IWFND/TRACES)

These tracing tools allow tracing the processing of the actual OData request in the SAP Gateway runtime. If this is done in an embedded deployment, the trace digs down to the ABAP implementation.

SAP Gateway Backend Tracing Tools (/IWBEP/TRACES)

These tracing tools allow tracing the processing of the request in the service implementation. If this is done in an embedded deployment, the trace includes the handling of the OData request in the SAP Gateway runtime.

With the both tools, you can start a trace for a certain service or user. The performance trace includes application times down to single method calls. It is even possible to trace the payload of single requests if required.

The SAP Gateway Statistics (/IWFND/STATS) help to get an overview of the processing time statistics for requests in SAP Gateway.

The Hub Overhead and the Backend Overhead contain the processing time of a request in the SAP Gateway framework on the hub (FES) and back-end (BES).

The RFC Overhead contains the processing time needed for communication between the FES and BES. Finally, the Application Time contains the processing time of the business logic.

For more details, see the following blog post:

https://blogs.sap.com/2016/01/28/understanding-sap-performance-statistics-for-sap-netweaver-gateway-service/

The SAP Gateway Global Configuration (/IWFND/GLOBAL_CONFIG) is the central place for logging, tracing, and statistics settings in the server the services are registered. Changing these settings require a suitable authorization.

The SAP Gateway Backend Global Configuration (/IWBEP/GLOBAL_CONFIG) is the central place for logging and tracing settings in the server the services are implemented. Changing these settings require a suitable authorization.