Skip to Content
Technical Articles

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')
5 Comments
You must be Logged on to comment or reply to a post.
  • Dear Eileen,

    Great blog, thank you.

    May i ask for some examples how to work with CBO with 2 level structure? (I.e root and subnode):

     

    • is it possible to create root and subnode in one odata call?
    • How to add subnode to root? Apparently POST method is not possible for subnode (The specified HTTP method is not allowed for the resource identified by the Data Service Request URI) and PUT/MERGE is not working either (Change not possible; object does not exist)

    Best regards,
    Tomasz

  • Hello There,

    Great blog, it helped me to understand the how to use the Odata Service for a CBO created in SAP Marketing Cloud.

    However, could you please let us know, if we can PUT, PATCH and MERGE using the Key Field defined in CBO rather than the GUID of CBO. If it is possible, the interfacing systems can make a direct call to perform the update operation.

    I am not sure if ODTA as a standard allow this. But, i feel this could be one of the basic requirement as it avoid two calls [one to retrieve the guid and the other to perform the update using guid]

    So i guess, the URL should be something like this

    PUT https://my&lt;…>-api.s4hana.ondemand.com/sap/opu/odata/sap/YY1_HCI_ID_ID_ORIGIN_CDS/YY1_HCI_ID_ID_ORIGIN(UUID = ‘ABC123’)

    Here, UUID is the CBO field that is defined as a Key.

    If anyone has any input on this, please let us know.

    Many Thanks,

    Shaju Mathew