Learn how to create a data model in the Common Schema Definition Language (CSDL) using SAP Web IDE

You will learn

In most cases, a live OData service will be available when building an application. For times when a service is not available, it is still possible to build apps with SAP Web IDE with a file-based data model and then run on simulated data (referred to as “mock data” in SAP Web IDE). Once the data service is available, the app can then be configured to run against the service rather than the mock data with no other changes. The mock data approach is also useful if you want to prototype an app and have realistic data appear in the UI.

Details

In this tutorial, you will create an OData model with a Sales Order related data fields in two parts:- Part 1: Create the minimum data model needed to build a basic app based on one OData collection- Part 2: The second part adds an additional collection as a NavigationProperty to your primary collection similar to what you used in the earlier Mobile Guides.

Both versions of the metadata document will allow you to use the Web IDE template wizard to create an app in the next tutorial (and then switch it to a live service).

Additionally, the full data model is provided at the bottom of this document if you want to refer to it later for use in your projects.

Background:

A metadata document is defined in the Common Schema Definition Language (CSDL). There is an exhaustive description of CSDL here, but this tutorial will focus on a subset of the full language to build the metadata needed for this tutorial.

The metadata document you will build for part 1 (one OData collection) will have the following structure:

Component

Description

XML declaration

Not necessary for .edmx files, but useful to include if you want to view the file in an editor that supports XML syntax highlighting

Edmx and DataServices elements

The “wrapper” for your data model

Schema

Container for the EntityTypes, Associations and EntityContainer elements

EntityType

Defines the data model for the OData collection

EntityContainer

Exposes the OData collection

Part two of this tutorial adds in a second EntityType and the required elements to set up the NavigationProperty. In the Web IDE template you have been using the data from the NavigationProperty (Suppliers) has been displayed in the Info or Suppliers tab.

Step 1: Open Web IDE and create new folder

Open Web IDE, select the Local folder and create a new folder called Metadata.

Right-click on the Metadata folder, and create a new file named m104metadata_no_nav.edmx.

Step 2: Create entity model wrapper

To start with, paste in the text below as the entity model wrapper of the metadata file. The wrapper consists of the following:

Item

Description

<?xml ...?>

XML encoding declaration. Here you specify the XML version, the encoding used in the file, and that it is stand-alone (does not rely on information from an external source)

edmx:DataServices

A CSDL formatted document requires edmx:Edmx as the root element, and that it contains a single edmx:DataServices element

Next, paste the Schema element text inside of the DataServices element. After you paste in the text, select Beautify from the Edit menu (**Edit > Beautify**) to clean up the indents (you will want to select Beautify each time you paste in text during this tutorial). It is suggested you then add some blank lines before the </Schema> tag to make it easier to insert text in later steps (as shown in the image below).

Item

Description

<Schema...

A CSDL document requires that each edmx:DataServices element contain one or more Schema elements. Here, you will also specify the namespace (Sales) for the service.

</Schema>

This is the closing tag for the Schema element. The closing tag is used in all multi-line XML elements (there are two in the previous step).

Before continuing, with the EntityType, it will be useful to understand the data items that the service will expose. Imagine that you have completed your Design Thinking sessions with the users and have determined that the app should display the sales order relevant fields below (and their data types):

Field Name

Data Type

SalesOrderID

String

CreatedAt

Date and Time

CreatedByCustomerName

String

CreatedByEmployeeFirstName

String

CreatedByEmployeeLastName

String

CreatedByEmployeeUserID

String

NetSum

Decimal

Tax

Decimal

TotalSum

Decimal

Currency

String

CurrencyCodeDescription

String

BillingStatus

String

BillingStatusDescription

String

ChangedAt

Date and Time

ChangedByCustomerName

String

ChangedByEmployeeFirstName

String

ChangedByEmployeeLastName

String

ChangedByEmployeeUserID

String

CustomerID

String

CustomerName

String

DeliveryStatus

String

DeliveryStatusDescription

String

Status

String

Note

String

StatusDescription

String

Additionally, the Data Architects involved in the project require two additional fields for linking the tables in the back-end:

The next step is to add the EntityType element into your document which defines the fields in your data model. Within the EntityType element you will include a Name attribute which is a simple identifier for the element.

Copy and paste the text below within the Schema element in your document.

<EntityType Name="SalesOrder">
</EntityType>

Step 6: Populate entity type element

With the field names and data types known, it is simple to populate the EntityName element. When doing this on your own, you will need to make two decisions:

Which field to use as a Key

The field length for the strings

The Key is used as the default sorting key the service will use when returning the data, and the field length for strings is the maximum number of characters allowed. For this tutorial, these items have been taken care of for you (SalesOrderKey and the string lengths vary by field).

Copy and paste the following within the SalesOrderEntityType elements.

Your basic OData model is now complete and you could use it to build a basic app with the SAP Web IDE template wizard. If you would like to do this before continuing, you can jump to the next tutorial now.

Step 8: Review requirements for linking second collection

Most OData services you will use will have collections that are linked to one or more other related collections through a NavigationProperty element. In this section, you will add a second collection and the elements to enable the navigation. The table and graphic below describe the changes you make and provide a graphical view of the part 2 OData model.

Component

Description

XML declaration, Edmx and DataServices elements

Same as part 1

EntityType #1

Same as in part 1, but with a NavigationProperty element added

EntityType #2

Similar to part 1, but defines the data for the second collection

Association

Defines the nature of the connection between the two collections

EntityContainer

Similar to part 1, but adds the second collection as well as the AssociationSet to expose the connection between the two collections

Step 9: Copy existing file

To begin, right-click on the m104metadata_no_nav.edmx file and select Copy.

Right-click on the Metadata folder and select Paste (to duplicate the file). You will see a naming conflict dialog box open – name the new file m104metadata_nav.edmx and click OK.

Step 10: Add navigation property element

The first edit to make is to add a NavigationProperty element to the SalesOrder entity. Copy and paste the following text just below the Currency property in m104metadata_nav.edmx. The attributes you specify here are:

Attribute

Purpose

Name

BusinessPartner – Label for the NavigationProperty

FromRole

SalesOrder – refers to a destination of the NavigationProperty and matches the name specified in the Association element

ToRole

BusinessPartner - refers to a destination of the NavigationProperty and matches the name specified in the Association element

Relationship

SalesModel.FK\_SalesOrder_BusinessPartner – This string’s format is <Schema Namespace>.<Association Name>. The Association will be added later.

The next addition is the Association element which (as the name implies) represents an association in an entity model. The Association element must contain a Name and two End elements – and can also contain referential constraints. The attributes you will use are explained below.

Attribute

Purpose

Name

FK\_SalesOrder_BusinessPartner – must match the Association Name in the NavigationProperty element

End #1

Multiplicity: “0..1” – indicates that when a SalesOrder exists, it can have zero or one BusinessPartner entities associated

Role: Allows the association to be bound to a NavigationProperty

Type: Must point to an entity type in the entity model

End #2

Multiplicity: * – indicates that when a BusinessPartner exists, it can have zero or more SalesOrder entities associated

Role: Allows the association to be bound to a NavigationProperty

Type: Must point to an entity type in the entity model

ReferentialConstraint

This element asserts that the entity identified in the Principal Role must exist in order for the entity in the Dependent Role to exist. In this case, a BusinessPartner must exist in order to create a SalesOrder. Also specified here are the unique identifiers (BusinessPartnerKey and SalesOrderID).

Copy and paste the following text immediately after the BusinessPartner</EntityType> closing tag.

Your model is now complete. When working on your own OData model, you can take advantage of the OData Model Editor (which is a plug-in to SAP Web IDE). To enable it, select Tools > Preferences in Web IDE, click on Plugins, locate the OData Model Editor plugin, click the slider to “on”, then Save and Web IDE will reload.

Step 15: Load graphical view

With the m104metadata_nav.edmx file open, you will see the Source and Design tabs at the bottom of your editor pane. These show up when you are working on an .edmx file. Click on the Design tab to switch to the graphical view.

The graphical view will open. If the model appears very small (as shown below), click the Fit to Screen button to zoom in.

Step 16: View the full entity model

In this view you can see the full entity model, associations, multiplicity and clicking on one of the members of the model will show the attributes for that member.

Step 17: View the console

Click on the Source tab, and then select View > Console (if the console is not currently displayed). SAP Web IDE also has a CSDL validator that is activated when you edit an .edmx file. Since your model is complete – it will show this is a valid OData model file.

Step 18: View changes in real time

The validation happens during editing, so you can see the effect of changes right away. To test this out, simulate a typographic error by inserting a character into the first EntitySet line (change SalesModel to SalesModels). The validator points out the error right away.

Remove the extra character to remove the error.

Step 19: Future modifications

If you want to modify the entity model used in this tutorial for your own projects, the full entity model text is provided below. Just copy and paste it into an .edmx file in Web IDE and modify the Name, Type fields and others as needed.