How to model an OData Service with SAP Business ByDesign OData Service Modeler?

What is the SAP Business ByDesign OData Service Modeler?

The SAP Business ByDesign OData Service Modeler allows quick creation of OData services based on Business Objects (BO) with a simple ‘Point and Click’ based modelling approach.

The OData Modeler respects the Public Solution Model (PSM) and presents only released fields. The PSM defines a release stability condition and guarantees that the released entities are stable after the next release upgrade of the SAP Business ByDesign solution.

OData services can also use extensions build with the SAP Cloud Applications Studio (CAS).

Notes:

• Transient fields are not supported. They are not presented in OData modeler.
• Extension fields are shown in the modeler and can be added to custom services.
• CAS actions and CAS queries are not yet supported.
• An OData service can be based on CAS developed custom object.
• CAS extension fields on a standard BO can be added to a custom service.

How to access the OData Modeler?

The modeler is located as Work Center View OData Services within Application and User Management.

Assign the work center view to the user:

• Open work center view Application and User Management / Business Users.
• Search for the user name.
• Select the user in the list and click Edit > Access Rights.
• Switch to Tab Work Center and View Assignment. In the list, expand the branch ITS_APPLICATIONUSERMANAGEMENT.
• Mark the check boxes to assign the work center and the work center view ODATA_BYD_WOC_VIEW to the user.
• Save the assignment

How to start the OData Modeler?

• Open work center view Application and User Management / OData Services.
• Use the drop down box at the top to switch between delivered SAP OData Service and Custom OData Services.
• You can view Standard Service and view, create and edit Custom OData Services.

How to create a new OData Service?

• Go to Custom OData Services.
• Click New.
• Enter the service name and click Save and Close to return to the list. Refresh the list to see the added service. Select the service and click Edit. Alternatively, you can use Save and Open to open the OData Modeler after save.
• The OData Modeler presents the involved business object on the left side, and the exposed data structure on the right side.

How to edit an OData Service?

To edit a Custom OData service:

• Go to Custom OData Services.
• Select the OData service.
• Click Edit.
• The OData Modeler presents the involved business object on the left side, and the data the service exposes, on the right side.

How to save an OData Service?

During modeling:

• Click Save to store a draft version.
• Click Activate to activate the service. Notice that an OData service metadata URL appears:
  https://YOUR_SYSTEM/sap/byd/odata/cust/v1/your_service/$metadata
  The response on this request describes structure, used data types and properties of the service. It can be used to understand what the service exposes and how.

How to handle authorizations?

The access to a service is restricted based on a work center view. The consumer of a service needs to login to the SAP Business ByDesign system and can see and access exactly the same instances the consumer could see and access in Business ByDesign in the selected work center view.

How to maintain the Fields of an OData Service?

An OData service can expose fields from several Business Objects and several Business Object Nodes.

You can use any persisted, PSM released node and field.

How to add a field?

Select the Business Object Node that provides the field and click the select checkbox of the field.

If the Business Object Node is already part of the OData service, select the according Node entry on the right side. The BO node structure appears on the left.

Otherwise click Select Business Object to choose the BO and BO node to use. You can use value help for selection support. The BO node structure appears on the left. Mark the select checkbox of the node to add this node to the OData service.

Select the field you wish to include in your service. Click the select checkbox of the field.

• An atomic field will be added to the right.
• 1:n associations are added as new collections. Add any subset of fields to this new collection.
• 1:n associations can be added multiple times, each with its separate set of fields to expose.
• For Dependent Objects (DO) Attachment, Text Collection and Address all fields are added.
• 1:1 associations can be added as new collection, or directly exposed (merged) with the parent.

Added fields and collections can be renamed for easier or more semantic recognition.

The metadata will display what can be done with the field. They properties are:

• Key: This is the primary key field. ObjectID is technically the NODE_ID.
• Create: This field is create-enabled and can be created.
• Update: This field is update-enabled and can be modified.

How to add Code Values?

You can add code values just like any other field.

If you enable checkbox Include Code Descriptions for your service, the OData Framework

• automatically adds also the description for the code values, e.g. for direct display.
• adds an according collection of all possible values and descriptions, e.g. for Value Helps.

How to remove a field?

The right side shows, what the OData service exposes. Select the field and click Remove.

Removal needs to be bottom up, based on associations. All added navigation targets need to be removed first.

Assume your service started at node Root of some Business Object and you added its Item as well.

There is a parent/child-relationship between Root and Item that is e.g. used to navigate from Root to Item. In that case, delete the Item first, then the Root. It is not possible to remove only the Root but keep the Item.

If you do not need the Root to be included, create your service starting directly on (BO, Item). You can even add (BO, Root) later as well. In that case, no navigation association from Root to Item was added. Therefore you are free to remove in any sequence.

How to maintain a Function Import of an OData Service?

Function Imports provide access to Business Object Queries and Business Object Actions.

Edit your service and switch tabs from Entity Types to Function Imports. You can add any number of Function Imports based on any Entity Type used in your OData service.

You can use any PSM released BO Query, BO Action and parameter.

BO Queries can be used multiple times. Every created Function Import can have its own subset of query parameters. You can rename the query parameters.

BO Actions can be used once. All action parameters are added automatically.

How to add a Function Import to an OData Service?

Switch to tab Function Imports.

• Add a row to the table by clicking Add Row.
• Select Function Import Type. Use QUERY and ACTION to use BO query and action resp.
• Enter the name you want to use for access, for example yourfunctionimport.
• Select the Entity Type with the value help, or enter it.
• The HTTP Method defines how the Function Import is triggered by the application. It is always GET for queries, and can be either DELETE or GET or POST or PUT for actions.
• Use the value help to select the BO Query or BO action to execute.

How to maintain Function Import Parameters?

For actions all Action Parameters are added automatically.

For queries the standard parameters NumberOfRows, StartRow, and (returning) InstanceData are added automatically and appear in a parameter list. You can chose any subset of additional parameters.

1. With Manage Parameter multiple parameters can be selected and deselected from the list of possible parameters.
2. With Add Row a new row is created. Select a single parameter with the value help.
3. With Remove a parameter is removed.
4. Parameters can be freely renamed and are bound/mapped to the BO query parameter.

How to remove a Function Import?

Switch to tab Function Imports.

Select the Function Import and click Remove.

How to Transport or Backup an OData Service?

You can download and upload OData services. This makes it easy to e.g. create and test an OData service in your test system and then re-create it in production system without manually redoing it. In addition, you can easily backup OData services by downloading them.

• Start the OData Modeler in the source system.
• Go to Custom OData Services.
• Select the OData service.
• Click
• An XML file is saved on your local computer.
• Start the OData Modeler in the target system.
• Go to Custom OData Services.
• Click Upload and provide the stored XML.