Defining a Data Model

Once you have created a project in the SAP Gateway Service Builder, you can start the data modeling process. Depending on your requirements, you can define a data model in the following ways:

Define Data Model Declaratively

You can manually define a new data model within your project — that is, you create the individual data model elements, such as entity types, entity sets, and associations, from scratch.

Import Data Model (EDMX)

You can reuse an existing data model by importing an XML-file formatted as EDMX (Entity Data Model Extension). This file can be created by external model editors like Microsoft Visual Studio or you can download the metadata of an existing OData service.

Import DDIC Structure

You can import a database view, a transparent table, or any other structure type from the ABAP Data Dictionary (DDIC) to create a new complex or entity type with ease.

We skip the declarative way for now and focus on the other two ways.

Without any service implementation, it is already possible to generate the runtime artifacts and register the service. The only function then provided by the service is to provide the metadata of the data model.

The first development step is to create an SAP Gateway project in the SAP Gateway Service Builder. You open the SAP Gateway Service Builder by using the transaction code SEGW.

A project bundles all artifacts of a service in one central location, helping you to organize the modeling process and service development. Since projects consolidate all related data, you can easily work on multiple projects in parallel and reuse data between projects before generating and activating the actual service. In addition, you can use projects to organize the movement of objects from one system environment to another ensuring that all artifacts remain together at all times.

When creating a project, you must define a name and description and set the project type. The latest and only valid project type today is the Service with SAP Annotations. All other project types are deprecated.

As repository object, a project must be assigned to a package and transport request or saved as local object. As responsible person, the creator of the project is automatically set, but can also be changed later.

The second development step is to define the data model of the service. All actions in the Data Model branch of the project result in ABAP code generated in the Model Provider Class (MPC).

To import OData models that have been designed by OData modeling tools, you right-click the Data Model node and choose Import → Data Model from File. You can also import OData models by importing the metadata file of an existing OData service.

When performing changes to such a model after it has been imported, you can perform a re-import. A wizard will support you when adding and removing elements that have changed in the model.

Models imported in that way are not linked to any ABAP components and therefore miss semantic information like translatable texts or value helps. There are also no DDIC types ready to be used in the ABAP source code. Only local types are generated.

To reduce the time required to create entity types and complex types in your data model, you can import an existing DDIC structure. Although it is only a part of a complete model, in this way semantic information is included. In addition, the DDIC structures can be used in the ABAP source code.

You can import the following structure types into the SAP Gateway project:

• Structures
• Transparent tables
• Views

You can use the wizard to create entity types based on DDIC structures in an inside-out approach as follows:

1. In the first screen, you enter a name and select if you want to create an entity or complex type.
2. Using the value help, you select the DDIC structure to be imported.
3. When the option Create Default Entity Set is selected, the wizard creates an entity set called <Name of entity type>Set, for example, ProductSet.
4. In the next screen, you select the fields of the DDIC structure, which should become properties of the entity type.
5. Finally you choose the key field(s). Every entity type in OData must have at least one key field. It is also possible to rename the properties of the entity type since the proposed values are generated based on the ABAP field names: The underscores in the field names are removed and the name segments are merged in a camel case notation.

After the wizard is finished, you can find the entity type under Data Model → Entity Types. Beside the properties generated based on the field names of the structure type, the structure itself is bound to the entity type. This structure binding limits the possible parameters of the entity type to the fields available in the structure. That means new properties can only be added to the entity type, after they are created as fields in the bound structure.

A structure binding prevents changes in the data model that would cause errors in the source code by adding properties not part of the data types used in the implementation. In addition, when reusable units are called during runtime, the interfaces of these units must match the data types used for passing data.

The third development step is to generate the runtime artifacts. Now everything done so far somewhere in the SAP Gateway project will be interpreted and generated as source code and technical customizing.

The first time you choose the Generate Runtime Objects for an SAP Gateway project, the Model and Service Definition popup appears. Here the names for the runtime artifacts can be set. The proposed names are based on the project name:

Model Provider Class

• ZCL_<project name>_MPC_EXT
• ZCL_<project name>_MPC

Data Provider Class

• ZCL_<project name>_DPC_EXT
• ZCL_<project name>_DPC

Service Registration

• <project name>_MDL
• <project name>_SRV

Project names, which would create too long runtime artifacts names, will just be cut replacing the now missing characters by a number. It is recommended to limit the project name to 18 characters. This makes it easier to map artifacts to a project.

From the runtime artifacts in the SAP Gateway project, you can jump directly to the ABAP Workbench (SE80).

The model provider extension class inherits from the base class. The base class then inherits from abstract model classes of the SAP Gateway framework. These abstract classes provide basic implementation for every model provider class.

The model provider base class consists of generated code based on the settings done in the SAP Gateway Service Builder on project level. Today, most of the data model is defined in the project directly and therefore generated as ABAP code in the base class:

• The DEFINE method is the central method called by the SAP Gateway framework when the data model is created. The method calls private methods of the base class generated based on artifacts defined in the project.
• For every artifact like entity type, complex type, association, or function import, a specific method is generated following the naming rule DEFINE_<artifact>. The model attribute of the MPC provides methods to create all details of the artifact like creating entity types, properties, and entity sets.

By redefining the DEFINE method in the extension class, you can extend the data model with features not supported by the SAP Gateway Service Builder.

You can access the code of the data provider extension class from within the SAP Gateway Service Builder via the context menu of a class listed in the Runtime Artifacts branch.

The data provider extension class inherits from the base class. The base class then inherits from abstract data classes of the SAP Gateway framework. These abstract classes provide basic implementation for every data provider class.

For each entity set in the data model, methods are generated in the base class to reflect the entity set’s CRUD and query operations. One set of central generic CRUD and query methods are delegating the requests to these generated methods.

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 base class, all these generated methods raise an exception indicating that the respective OData operation is not yet implemented. This only changes if some wizard is used in the SAP Gateway Service Builder calling some reuse unit.

The data provider extension class inherits these methods. Here, you can redefine them to develop the data provisioning for the different request types. That is, to implement the service, you have to overwrite the appropriate methods from the base class in the extension class.

The fourth development step is to register the service. This step must only be done once per system. Any changes to the data model or to the implementation afterward are automatically available in the registered service. The first thing done after the service registration is testing the metadata.

To register a service means to create a service catalog entry based on the technical service of an SAP Gateway project. The name of the technical service acts as external service name used for calling OData requests. For services created in the customer name space, the name of the service catalog entry is also equal to the technical service name.

For services delivered by SAP, the external service name belongs to the SAP name space. But for most of these services, the SAP does not ship the service catalog entry. The reason is that the customer should decide, in which system these services should be registered. Because of this flexibility, the customers register the services delivered by SAP by themselves and, therefore, create the service catalog entry in the customer name space. The same applies to service provided by partners having an own name space.

The purpose of a service catalog entry is to forward the OData request coming in from the ICF to the implementation of the service. If this implementation resides in another system, a system alias is assigned to the service catalog entry and used as a placeholder for an RFC destination to the other system. This allows transporting the service catalog entry from a development system to a test or productive system reusing the same alias in every system. But for each system another RFC destination is assigned to the system alias to always call the suitable target system.

In an embedded deployment, the implementation resides in the same system as the service catalog entry. In this scenario, there are two possible ways to register a service:

1. The system alias LOCAL can be used as the place holder for the RFC destination NONE, which just means that no other system is called but the current one.
2. Since SAP_GWFND 7.50 SP04, the processing mode Co-deployed only can be set for the service catalog entry and no system alias is assigned. This means that the SAP Gateway runtime is called directly.

Since SAP_GWFND 7.51 SP05, the SAP Gateway Routing Configuration (/IWFND/ROUTING) allows the maintenance of SAP Gateway system aliases. System aliases are used for OData V2 and V4 services alike. By choosing a system alias in the list at the top, the OData V2 and V4 services registered using this alias are listed underneath. It is not possible to change these service catalog entries here. This can only be done in the /IWFND/MAINT_SERVICE and /IWFND/V4_ADMIN transactions.

The SAP Gateway Service Builder enables you to register and maintain services in the SAP Gateway Service Maintenance. For this, you must expand the Service Maintenance node, select the SAP Gateway alias, and choose Register.

The Select System Alias popup is provided by the system connected via the SAP Gateway alias. The value help of the System Alias field provides a list of suitable system aliases maintained in the FES targeting the BES.

In the Add Service popup, the technical service and model names are already set. The External Service Name field is not changeable because it is defined based on the technical service. A service catalog entry must be assigned to a package or as local object. When the Continue button is chosen, one or more popups asking for a transport request will appear if a package was entered.

The latest and only valid mode today of the ICF node is Standard Mode. OAuth is an authentication option provided by the OData standard. Ask you system administrator if your system supports this.

In the SAP Gateway Service Maintenance, you can register one or more SAP Gateway services at once. Choosing the Add Service button leads to a first empty list of available services. The System Alias field or selecting the Co-Deployed checkbox is mandatory to get a list of not yet registered services of the target system.

To register a service, you just need to choose the technical service name and the Add Service popup appears. You can also select multiple services via the checkbox in each line and choose the Add Selected Services button. The Add Services popup works in the same way as described before.