Usage of OData Service of Custom Business Object

For each custom business object you can generate an OData service by selecting “Service Generation”:

The service generated has the technical name of the custom business object with _CDS as suffix. To access the service from an integration tool like SAP Cloud Platform Integration you need to setup a communication scenario in the app “Custom Communication Scenario”. Afterwards you have to create a communication arrangement for this scenario. You will see the URL of your OData service in the inbound section:

Custom Business Object OData Service Overview

The OData Service of a custom business object is an OData service of version 2.0. You find the official OData Version 2.0 documentation at http://www.odata.org/documentation/odata-version-2-0.

The service has a technical key and a semantic key. The semantic key is the key that was defined in the custom business object as key fields. When creating entries through HTTP method POST the semantic key is taken into account. The technical key is the field SAP_UUID. For all changes or deletions of entries through HTTP methods PUT,MERGE or DELETE the technical key must be provided to the URI. To read entries OData version 2.0 provides two options. You can read a specific entry with HTTP method GET by providing the technical key in the URI. Otherwise you can read multiple entries also through HTTP method GET by using the paging and filter functionality. With this possibility you can also read a specific entry by providing the semantic key to the filter.

The OData service supports batch processing. For performance reasons you should always use batch processing. When interacting with the OData service you should take care of the session handling (see blog post How to Call OData Services in SAP Hybris Marketing Cloud).

As of release 1905 the custom business object OData Service also provides an upsert function. But this only works on root node items.

Sample Requests for root node

The following sample requests are built for a custom business object named YY1_HCI_ID_ID_ORIGIN. The custom business object has 4 fields whereas field IDOrigin and ContactID are marked as keys.

1. Retrieve the metadata of the OData service:

   GET https://my<...>-api.s4hana.ondemand.com/sap/opu/odata/sap/YY1_HCI_ID_ID_ORIGIN_CDS/$metadata​

2. Create an entry (Semantic Key Fields: IDOrigin, ContactID):

   POST https://my<...>-api.s4hana.ondemand.com/sap/opu/odata/sap/YY1_HCI_ID_ID_ORIGIN_CDS/YY1_HCI_ID_ID_ORIGIN
   
   {
    "IDOrigin":"EXTERNAL",
    "ContactID": "1",
    "Field1" : "Max",
    "Field2" : "Mustermann"
   }

3. Retrieve the technical key SAP_UUID for a specific entry:

   GET https://my<...>-api.s4hana.ondemand.com/sap/opu/odata/sap/YY1_HCI_ID_ID_ORIGIN_CDS/YY1_HCI_ID_ID_ORIGIN?$select=SAP_UUID&$filter=IDOrigin eq 'EXTERNAL' and ContactID eq '1'

4. Update specific properties of an entry:

   MERGE https://my<...>-api.s4hana.ondemand.com/sap/opu/odata/sap/YY1_HCI_ID_ID_ORIGIN_CDS/YY1_HCI_ID_ID_ORIGIN(guid'00163e0c-0f31-1ee7-8ddd-7e166e5da27f')
   
   {
   
    "Field2" : "Musterfrau"
   
   }

5. Update all properties of an entry:

   PUT https://my<...>-api.s4hana.ondemand.com/sap/opu/odata/sap/YY1_HCI_ID_ID_ORIGIN_CDS/YY1_HCI_ID_ID_ORIGIN(guid'00163e0c-0f31-1ee7-8ddd-7e166e5da27f') 
   { 
     "SAP_UUID":"00163e0c-0f31-1ee7-8ddd-7e166e5da27f",
     "IDOrigin":"EXTERNAL", 
     "ContactID": "1", 
     "Field1" : "Max",
     "Field2" : "Musterfrau" 
   }

6. Upsert an entry (only for root node items):

   POST https://my<...>-api.s4hana.ondemand.com/sap/opu/odata/sap/YY1_HCI_ID_ID_ORIGIN_CDS/YY1_HCI_ID_ID_ORIGINSap_upsert?IDOrigin='EXTERNAL'&ContactID='1'&Field1='Max'&Field2='Mustermann'

7. Delete an entry:

   DELETE https://my<...>-api.s4hana.ondemand.com/sap/opu/odata/sap/YY1_HCI_ID_ID_ORIGIN_CDS/YY1_HCI_ID_ID_ORIGIN(guid'00163e0c-0f31-1ee7-8ddd-7e166e5da27f')
   

8. Call a function import, that is created for each CBO action (only for root node items):

   POST https://my<...>-api.s4hana.ondemand.com/sap/opu/odata/sap/YY1_HCI_ID_ID_ORIGIN_CDS/YY1_HCI_ID_ID_ORIGIN<ActionName>?SAP_UUID=guid'00163e0c-0f31-1ee7-8ddd-7e166e5da27f'

Sample Requests for subnodes

The custom business object is enhanced with a subnode called Subnode. The subnode has 3 fields – SubnodeKey, SubnodeField1 and SubnodeField2. It is not possible to mark a key in a subnode, that’s why an upsert or function import is not possible.

1. Create an entry (There is a navigation property from the root node to the subnode called to_<Subnode ID> which has to be used for this operation.):

   POST https://my<...>-api.s4hana.ondemand.com/sap/opu/odata/sap/YY1_HCI_ID_ID_ORIGIN(guid'00163e0c-0f31-1ee7-8ddd-7e166e5da27f')/to_Subnode
     
   {
     "SubnodeKey":"Child 1",
     "SubnodeField1":"Junior",
     "SubnodeField2":"Mustermann"
   }

2. Retrieve the technical key SAP_UUID for a specific entry:

   GET https://my<...>-api.s4hana.ondemand.com/sap/opu/odata/sap/YY1_HCI_ID_ID_ORIGIN_CDS/YY1_SUBNODE_HCI_ID_ID_ORIGIN?$select=SAP_UUID&$filter=SubnodeKey eq 'Child 1'

3. Update specific properties of an entry:

   MERGE https://my<...>-api.s4hana.ondemand.com/sap/opu/odata/sap/YY1_HCI_ID_ID_ORIGIN_CDS/YY1_SUBNODE_HCI_ID_ID_ORIGIN(guid'fa163e0b-249b-1ee9-9dc3-f31e070e6be2')
   {
       "SubnodeField1":"Max Junior"
   }

4. Update all properties of an entry:

   PUT https://my<...>-api.s4hana.ondemand.com/sap/opu/odata/sap/YY1_HCI_ID_ID_ORIGIN_CDS/YY1_SUBNODE_HCI_ID_ID_ORIGIN(guid'fa163e0b-249b-1ee9-9dc3-f31e070e6be2')
   {
     "SAP_UUID":" fa163e0b-249b-1ee9-9dc3-f31e070e6be2",
     "SubnodeKey":"Child 1",
     "SubnodeField1":"Junior",
     "SubnodeField2":"Mustermann"
   }

5. Delete an entry:

   DELETE https://my<...>-api.s4hana.ondemand.com/sap/opu/odata/sap/YY1_HCI_ID_ID_ORIGIN_CDS/YY1_SUBNODE_HCI_ID_ID_ORIGIN(guid'fa163e0b-249b-1ee9-9dc3-f31e070e6be2')