Defining OData UI Services

Objectives

After completing this lesson, you will be able to:

Define a CDS projection view.
Enrich a projection view with UI metadata.
Create and preview an OData UI service.

Data Model Projection

The data model projection consists of one CDS projection view for each data definition view of the data model.

Projection views provide means within the service to define service-specific projections including denormalization of the underlying data model. Fine-tuning, which does not belong to the general data model layer, is defined in projection views, for example, UI annotations, value helps, calculations, or defaulting.

For the CDS view projection, a subset of the CDS elements is projected in the projection view. These elements can be aliased, whereas the mapping is done automatically. That means that the elements can be renamed to match the business service context of the respective projection. You cannot add new persistent data elements in the projection views. Only the elements that are defined in the underlying data model can be reused in the projection. However, you can add virtual elements to projection views. These elements must be calculated by ABAP logic.

To create the data definition for a CDS projection view, we recommend using the context menu on the name of the data definition view. By doing so, the name of the data definition view is automatically set as Referenced Object and template define Projection View is preselected by default.

Provider Contract

A CDS provider contract specifies the scenario in which a CDS projection view is used. The scenario determines in which runtime a CDS projection view is executed and which features are available. It is recommended that the provider contract is always specified to ensure that the appropriate, runtime-specific syntax checks are applied.

Note

It is possible, but not recommended, to leave out the provider contract. Projection views without provider contract are handled similarly to transactional projection views, but there are some minor differences in the syntax checks applied. For details, see here.

Currently, the following provider contracts are available:

Transactional_Query: Projection views with this provider contract are intended for modeling the projection layer of a RAP business object. A transactional projection view must always be part of a business object. That means it must either be a root entity itself, or it must be part of a composition tree that contains a root entity. The feature set focuses on specializing the RAP BO operations of the underlying business object.
Transactional_Interface: Projection views with this provider contract are intended for modeling a stable public interface layer in a CDS data model. They are typically used in the context of the ABAP RESTful Application Programming Model to provide the basis for a RAP BO interface. CDS transactional interfaces have a restricted feature set. They only support projecting elements and associations from the projected entity. Adding elements and associations in the interface level is not supported.
Analytical_Query: CDS analytical projection views are not related to RAP. They are intended for modeling analytical queries within a CDS data model. For more information, see here.

UI Metadata

From a design time point of view, the projection layer is the first service-specific layer. All service-specific metadata must be defined in the CDS projection views via CDS annotations.

Element annotations that are not service-specific can be placed in the data model views from where they are propagated into the projection layer.

An example is annotation@semantics.amount.currencycode, which is used to establish the connection between an amount field and its currency code field.

The following service specifics are relevant on the projection layer:

UI annotations defining position, labels, and facets of UI elements
Search enablement
Text elements (language dependent and independent)
Value Help

Note

It is best practice to outsource the UI-annotations of a projection view in a metadata extension. This increases readability and facilitates later adjustments of the UI through more metadata extensions.

Service Definition

A business service definition (or service definition) describes which CDS entities of a data model are to be exposed so that a specific business service can be enabled. A business service is a development object that describes the consumer-specific but protocol-agnostic perspective on a data model. This means that a service definition itself is independent of the version or type of the protocol that is used.

To create the service definition, we recommend using the context menu on the name of the CDS projection view. By doing so, the name of the projection view is automatically set as Exposed Entity.

Note

At present, only one template is available for service definitions.

The source code of the actual service definition is preceded by the optional annotation @EndUserText.label that is also available in other development objects.

The service definition itself begins with the DEFINE SERVICE keyword followed by the name for the service definition.

Note

Because a service definition does not have different types or different specifications, there is (in general) no need for a prefix or suffix to differentiate its purpose. However, if you do not plan to use the same service definition for different service bindings, the name can follow the rules of the service binding, that is, a prefix UI_ if the service is exposed as a UI service and API_ if the service is exposed as Web API.

A pair of curly brackets surrounds a list of EXPOSE statements with the names of the exposed projection views. The alias names after the keyword AS are optional. They define alternative names to be used by the consumer of the service.

Note

At the beginning, our service exposes only one projection view. Later, when we introduce the flight travel items as child entity, we need a second EXPOSE statement to add the child entity to the service definition.

Service Binding

The business service binding (or service binding) is an ABAP Repository object used to bind a service definition to a client/server communication protocol, such as OData.

A service binding relies directly on a service definition derived from the underlying CDS-based data model. Based on an individual service definition, several service bindings can be created. The separation between the service definition and the service binding enables a service to integrate various service protocols without any kind of reimplementation. The services implemented in this way are based on a separation of the service protocol from the actual business logic.

To create a business service binding, we recommend that you use the context menu on the name of the service definition. By doing so, the name of the service definition is automatically set as Service Definition in the Create dialog.

The binding type specifies the protocol and the application scenario. Currently, the following binding types are available:

OData V2 - UI: Defines a UI service based on version 2 of the OData Protocol. The naming convention is: Prefix: UI_, Suffix: _O2.
OData V2 - Web API: Defines a Web API service based on version 2 of the OData Protocol. The naming convention is: Prefix: API_, Suffix: _O2.
OData V4 - UI: Defines a UI service based on version 4 of the OData Protocol. The naming convention is: Prefix: UI_, Suffix: _O4.
OData V4 - Web API: Defines a Web API service based on version 4 of the OData Protocol. The naming convention is: Prefix: API_, Suffix: _O4.
InA - UI (Information Access): The InA protocol is used to expose analytical data models for live data access. This protocol only supports UI services.
SQL - Web API: This binding type is used to access published ABAP-managed database API objects with open SQL. SQL services only support Web APIs.

Note

When developing OData services, we recommend using Version 4 wherever possible for transactional services. In this course, however, we begin with an OData V2 service, because SAP Fiori does not support OData V4 without draft capabilities, which we cover later in this course.

Steps to Publishing and Testing a Business Service

After creating the Service Binding, the local service endpoint of an OData service must be published using the Publish button in the service binding editor. This triggers several task lists to enable the service for consumption. By publishing the service binding, the service is only enabled for the current system. It is not consumable from other systems.

Note

The service binding must be active to be published. To activate the service binding, use the activation button in the tool bar or press Ctrl + F3.

After publishing, the derived URL (as a part of the service URL) is used to access the OData service starting from the current ABAP system. It specifies the virtual directory of the service by following the syntax: /sap/opu/odata/<service_binding_name>

For UI services, you can start a Fiori Elements Preview directly from the service binding. With this preview, you can test UI-related features directly from your ABAP system.

If you want, you can directly start developing an SAP Fiori app based on this UI service. For this to work, you must configure the SAP Fiori development environment (IDE) that you want to work with. In the Project Explorer, right-click your ABAP Cloud project and choose Properties. Then search for External IDE Configuration.

Note

This feature is currently only supported in ABAP Cloud Projects.

Define and Preview an OData UI Service

In this exercise, you create a projection of your CDS-based data model and enrich it with search metadata and UI metadata. Based on this projection, you define and bind an OData V2 UI Service and preview the result.

Caution

This exercise uses version 2 of the OData protocol, as SAP Fiori does not currently support non-draft scenarios with the newer OData version 4.

Please note that SAP generally recommends implementing draft-enabled applications based on OData version 4. However, as the draft concept has not yet been covered in the course, OData version 2 is used here for didactic reasons.

Note

In this exercise, replace ## with your group number.

Solution

Repository Object Type	Repository Object ID
Data Definition (Projection)	/LRN/437A_C_TRAVEL
Metadata Extension	/LRN/437A_C_TRAVEL
Service Definition	/LRN/437A_TRAVEL
Service Binding	/LRN/437A_UI_TRAVEL_O2

Task 1: Create a CDS Projection View

Create a CDS projection view (suggested name: Z##_C_Travel), that reads all fields from your data model view Z##_R_Travel. Make sure that the projection view is classified as root view and that it specifies the provider contract for a transactional query.

Steps

Create a new data definition (suggested name: Z##_C_Travel) that defines a CDS view entity that is a projection on your data model view Z##_R_Travel. Assign it to your own package and use the same transport request as before.
1. In the Project Explorer view on the left, open the context menu for the data definition of your data model view.
2. From the context menu, select New Data Definition.
3. Enter the name of the new data definition and a description and choose Next.
4. Select the same transport request as before and choose Next.
5. From the list of templates, select Projection View (creation)→defineProjectionView and choose Finish.
Adjust the definition of the projection view. Add keyword root, which is needed because the projection view reads from a data model view that is a root view.
1. Add keyword root between keywords define and view.
Use a quick fix to add a provider contract transactional_query clause.
1. In the code row starting with define root view entity, place the cursor on the name of your projection view and press Ctrl + 1. Alternatively, choose the warning icon with light bulb left from that code row.
2. From the list of available quick fixes, choose Add PROVIDER CONTRACT TRANSACTIONAL_QUERY clause.
Activate and test the CDS projection view.
1. Press Ctrl + F3 to activate the repository object.
2. Press F8 to open the Data Preview tool.

Task 2: Enrich the CDS Projection View with Metadata

Enrich your projection view with search metadata and UI metadata. For the UI metadata, create a metadata extension (suggested name: Z##_C_TRAVEL) and copy the annotations from the template metadata extension /LRN/437T_C_TRAVEL.

Steps

Edit the data definition of your Z##_C_Travel projection view and enable the search functionality with Description and CustomerID as the default search elements.
1. In the data definition of your projection view, insert the @Search.searchable: true view annotation before the define root view entity statement.
2. Insert the element annotation @Search.defaultSearchElement: true in front of the Description and the CustomerID view elements.
For your projection view, allow extensions with metadata extensions.
1. In the data definition of your projection view, add the @Metadata.allowExtensions: true view annotation.
Activate the data source.
1. Press Ctrl + F3 to activate the development object.
Create a new metadata extension (suggested name: Z##_C_TRAVEL). Assign it to your own package and use the same transport request as before.
1. In the Project Explorer, right-click the data definition Z##_C_Travel and select New Metadata Extension.
2. Enter the name of the new development object and a description and choose Next.
3. Select the same transport request as before and choose Finish.
In the new metadata extension, set the metadata layer to #CORE.
1. Change the value of the @Metadata.layer annotation from layer to #CORE.
Open the template metadata extension /LRN/437T_C_TRAVEL and copy the UI element annotations to your own metadata extension.
1. Choose Ctrl + Shift + A.
2. Enter /LRN/437T in the Search field.
3. From the list of matching items, choose /LRN/437T_C_TRAVEL (Metadata Extension) and choose OK.
4. Select the entire code that follows the with addition (including the curly brackets) and press Ctrl + C to copy it to the clipboard.
5. Return to your own metadata extension, select the pair of curly brackets after the with addition and press Ctrl + V to replace it with the content of the clipboard.
Similarly, copy the view annotation group starting with @UI from the template metadata extension to your own metadata extension.
1. Return to metadata extension /LRN/437T_C_TRAVEL.
2. Select the code between the @Metadata.layer annotation and the annotate view statement and press Ctrl + C.
3. Return to your own metadata extension, place the cursor above the annotate view statement, and press Ctrl + V.
Activate the metadata extension.
1. Press Ctrl + F3 to activate the development object.

Task 3: Create an OData UI Service

Create a service definition (suggested name: Z##_TRAVEL) and a service binding (suggested name: Z##_UI_TRAVEL_O2), that exposes your Z##_C_Travel projection view as an OData V2 UI Service.

Steps

Create a service definition (suggested name: Z##_TRAVEL) for your Z##_C_Travel projection view. Assign it to your package ZS4D437_## and use the same transport request as before.
1. In the Project Explorer view on the left, open the context menu for the data definition of your projection view.
2. From the context menu, select New Service Definition.
3. Enter the name of the service definition and a description and choose Next.
4. Select the same transport request as before and choose Next.
5. From the list of templates, select defineService and choose Finish.
Activate the service definition.
1. Press Ctrl + F3 to activate the development object.
Create a service binding (suggested name: Z##_UI_TRAVEL_O2) that binds your service Z##_TRAVEL as an OData V2 UI Service.
1. In the Project Explorer view on the left, open the context menu for your service definition.
2. From the context menu, select New Service Binding.
3. Enter the name of the service binding and a description.
4. Set the Binding Type to OData V2 - UI and choose Next.
5. Select the same transport request as before and choose Finish.
Activate the service binding.
1. Press Ctrl + F3 to activate the development object.

Task 4: Publish and Test the OData UI Service

Publish the local service endpoint and preview the service as an SAP Fiori elements app.

Steps

In your service binding, publish the local service endpoint.
1. Open your service binding.
2. On the right, under Service Versions Detail, choose Publish.
Preview the service as an SAP Fiori elements app.
1. Under Entity Set and Association, choose the name of your projection view.
2. Choose Preview....
  The Preview for Fiori Elements App opens in a new browser window or browser tab.
  Note
  You might need to enter your user and password for the ABAP application server, when you open the preview for the first time.

Continue to quiz