E2E: BOPF-SADL-GW-SAPUI5 – Mapping an Entity Set
This is the second step of the series.You’ll find an overview in the document Introduction.
In this step we are going to create the first entity set; the one for the categories page of the application. It will be tested in the Gateway client and used to build the first page of the application. So let’s start.
Entity Sets, CDS Views and BOPF Nodes
The video visualizes the tasks.
To create the Gateway service we need to know how the targeted service data model relates to the BOPF data model. For the first entity set we cannot directly use BOPF because of the categories being attributes of the product root node. There is no BOPF_EPM category business object which could be used. So we need a query which selects all different categories out of the product root database table. That is why we need a Core Data Service (CDS) view. So the model mapping looks like this:
The CDS view is a SELECT DISTINCT query on the product root node of the product category.
You need some background informations about Core Data Services (CDS) – go here.
The Gateway Project
Now we can define the OData service in the transaction SEGW – the Gateway Service Builder. Creating an OData service consists of two steps. First you have to define the data model either manually or by importing it from a file, an ABAP data structure or a RFC interface. Then you have to implement the service, normally in implementing the gateway extension classes.
Start with creating the Gateway project: press the new button and follow the wizard.
Definition of the Data Model
The data model consists of four definition types: the entity type which is comparable to a flat ABAP structure and the related entity set which is comparable to the related ABAP table type. You can link entity types by associations, comparable to BOPF or CDS associations. For associations, you have also to define the related association set – which is a table of associations. Associations will only be used in part 4.
In this example I need an entity type and the related set. The elements of an entity type are called properties. This is somehow confusing in the BOPF context, where properties are attributes of structure elements. The entity type for the categories consists of one property – the category name. The category name should be read only, filter- and sortable. Mark the corresponding check boxes.
You do not have to define the related entity set manually. Creating an entity type, you can just flag a checkbox and the related entity set is created. But you should go through the attributes of the set.
The data model definition is not BOPF specific it is needed for any kind of implementation.
Now to the more interesting part in the BOPF context: the service implementation. Gateway provides generic services in two classes: one for the provisioning of the data model – the class with the suffix MPC (Model Provider Class) – and one for the operations on the data – the class with the suffix DPC Data Provider Class). Normally you have to redefine the methods in the extension classes – classes with the additional suffix EXT.
Using the service adaptation engine, you do not have to implement the two extension classes. You just have to define a mapping between the entity set and the CDS view.
Note that you could make use of the extension classes for special purposes in addition to the service adaptation mapping. But here it is not necessary.
In the Service Implementation Folder we find the new entity set. The right mouse menu offers the function ‘Map to Data Source’. Selecting it will open the mapping editor.
Before it opens there are some popups requesting source node specific details. First we have to define which mapping engine to use. Currently only the service adaption engine is supported mapping Business Entities like CDS views, vanilla ABAP views and tables or BOPF nodes.
The name is composed by the source type (CDS, ABAP view or BOPF node) and the source name. Use the value help – it composes the name.
Finally the tool opens the mapping editor. On the left hand side we see the OData data model, hence the entity set for the categories, on the right hand side, the source model, hence the CDS view.
Drag and drop the properties from right to left – and we are done for the service implementation.
Just save and activate the definition. The activation creates the provider classes for the model and the data. The service is ready to use, including the capabilities according to the OData specification, like paging for example.
Testing the Service
Back to a Gateway standard feature: You can test the activated service in the Gateway Client. If you want to test a new service for the first time, you have to register it. The function is in the right mouse menu of the Service Maintenance folder.
After the registration (a configuration step) you can switch to the Gateway Client also using the right mouse menu in the Service Maintenance folder.
If you are not used to the Gateway Client you may be overwhelmed. But it is a very powerful tool. You can test the complete service, requests and responses, data selection and update functions. Right hand side contains the response data, left hand side you can specify the request data. For data selection it is sufficient to use the URI, which you can compose in the upper part. In the tool you can execute Gateway services using the OData specification for the URL.
For your convenience there are buttons to assist you composing the URI. The root URI is already proposed. To get the category list, just use the menu button Entity Sets and select the only one which we created. The GET request (data selection request) is already marked by default, so you just have to execute the request to get the list.
Learn more about SAP NetWeaver Gateway here.
It is possible to assign authorizations to CDS views. If this is the case, the service adaptation engine uses the definition to enrich the select on the database. This means, that it provides only records which the user is authorized to see. This is not only interesting from a security point of view but also form an implementation one: first authority checks cannot be forgotten, they are modeled and the engine executes them in any circumstances. Second as they are integrated into the select statement, the checks are extremely fast and it is very easy for example to provide the list of the top ten selling products the user is authorized to see.
Executing the URI shows that the service provides the expected list and we are ready to use it in an UI application.
Creating the SAPUI5 application
The video illustrates the creation of the first page of our target UI.
When I first tried to create my own SAPUI5 application beyond the tutorials, it drove me round the bend. First of all it is nothing for people like me with slight signs of dyslexia. A typo can make the whole application not working. And if you do not have the sharp eyes of a proofreader, you can get mad. Without the support of my dear colleague Pascal I do not know where I would have ended.
Having said this and if you are a hard core ABAP developer curious to see how the service is used in an SAPUI5 application the following paragraphs my be of interest for you. It’s more or less a step by step description. If you want to learn more go to the SAPUI5 space SAPUI5 Developer Center or visit the training page UI5’s Cool Version 2. Experienced UI programmers should rather skip this section.
Creating the project
I suppose that you have already installed the SAPUI5 plugin for Eclipse. If not, you can find it here.
Then you can start creating your project. Select Project in the New menu button and SAPUI5 application Development Project to launch the creation wizard.
Enter a project name and select the sap.m library. This is the SAP standard. For your convenience mark the flag Create an Initial View. This creates not only the project but the files for the first page: the index.html file, the first view XML and controller file. And the best is that they are already correctly linked.
Enter the view name on the following screen and select XML view. This is the SAP standard view type
Finish the wizard and you will see the created files in the Project Explorer.
The interesting files are in the folder WebContent. You can see the file containing the XML view, the one for the related controller and the file for the index.html containing the bootstrap information.
Implementing the Categories page
Our UI design requires a split application with 2 master pages, on the left hand side and a detail page on the right hand side. We start with the first master page containing the categories.
The index.html File of the Application
First we create a variable for the data model and bind it to our gateway service. For ABAP developers used to a more procedural programming language, this may be puzzling. The binding of the data model to a service URI does not mean, that the http request is executed immediately. It is just a registration. The call is executed, when the view requires the data.
Second we need variables for the splitter application and the categories page. We attach the page to the application as master page and configure the splitter application (transition mode, etc.). This is currently not so exiting as we have only one page, but later on, we want to be sure that we always start the application with the categories page. Finally we register the application in the content division of the HTML body.
This is the frame of the UI application.
The Categories View Definition
Now we care for the details of the page. The view contains a simple list which is bound to the CategoryHeaderSet object of the data model of the view – which has to be defined in the controller. The list items are bound to the Category attribute.
Later on we want to select a category and use this selected item for the navigation to the product page. We prepare this step in registering a callback function for the selection event: listItemTriggered.
That’s it for the view definition.
The Categories Controller Object
We continue defining the data model of the view. This is done in the categories controller. In the index.html we have already created a data model and bound it to our gateway service. We just need to use this data model in our view.
The onInit function is called when a controller is instantiated and its view controls are already created. It can be used to do one time initializations, for example to bind event handlers or the model. Every function has a context object called this. From this object you can get references to further objects like e.g. to the view. sap.ui.get.Core is a very helpful function providing access to the Core.
In this controller we have later on to implement the callback function listItemTriggerd which we registered in the view. We will do this in the next blog.
So far for the implementation.
Testing the Categories Page
To run a first test, select the index file
and select Web App Preview in the Run menu button. You will see the page working but without displaying any data.
The reason is that up to now we have been working only with local files. There is no connection to a backend and the application runs on localhost. To work with data we have to deploy the project on a Web server. I want to keep it simple and will use the ABAP server. Therefore we must share the project.
Sharing the Project
Select the project and open the right mouse menu. Go to Team/Share Project… to launch the wizard connecting the project to an ABAP system and a BSP application.
Select SAPUI5 ABAP Repository.
On the following pages you have to enter the ABAP system name form the logon pad and the logon data. Then you can create the BSP Application. On this screen it is also possible to connect to a already existing application which allows you to retrieve the sources from the BSP application of your colleagues. But here we need a new application.
Finish the wizard and you have related the local project to an empty BSP application. You have to copy the source files to the BSP application on the ABAP server. Select the Submit function in the Team menu. This triggers the copy function. A popup shows all the files which are copied to the ABAP server.
If you now open the Run menu for the index.html file, you discover a new option. You can run the application on the ABAP server.
And here we are with the data:
We will see that the URL has changed: it runs on a server.
Last but not least I want to draw your attention to a button on the right hand side. This button opens the application in an external browser. You can configure your preferred one. I like to use Chrome. The F12 key is magic: it opens the debugger. Combined with an external break point in the ABAP backend code, you can run through your application.
For the present we are done with the Categories – end to end. We created an CDS view using the BOPF persistency of the Product business object, then we created an OData service in a gateway project with an entity set mapped to the CDS view using SADL. And finally we used it in an SAPUI5 application.
In the next step we go ahead with the Projects page: Implicit View Building where we will explore further capabilities of SADL and how to relate the entity sets in the UI application.