API operations for Custom Business Objects in S/4HANA Cloud
In SAP S/4HANA Cloud, there are three fundamental possibilities available for the extensibility of the standard functionality that is available out-of-the-box. These possibilities are:
- In-App/Key User Extensibility
- Side-by-Side Extensibility
- Developer Extensibility/Embedded Steampunk
For a high-level understanding of these different options, please refer to the following blog which offers a great overview on this topic.
In this blog post, we’ll be looking at a specific extensibility scenario available with In-app/Key user extensibility, namely the use of so-called Custom Business Objects (CBO’s). With CBO’s, it is possible to create custom variations of standard business objects (for eg. Sales Orders or Purchase Orders) and enhance these objects with custom logic to fit the needs a specific customer requirement. Given this background, I would like to demonstrate in this blog how you can create a CBO and execute the standard API operations (GET, POST, DELETE) on this CBO. You can also enhance CBO’S with custom fields and custom logic using ABAP BADI’s, however in this blog, I’ll only be covering the execution of API operations.
Create the new CBO
The first step in the process is to create a new custom business object, on which we can test the API calls. For this, use the Fiori app “Custom Business Objects” and create a new CBO.
Add Nodes and Fields
Once inside the CBO, activate the checkbox “User Interface” under the General Information tab. This will automatically generate a UI and back end service associated with your CBO.
Next, under the Fields tab, add some fields that you want to use in your CBO and define at least one of these as a key field. In this demo, I’ll use a fictional scenario where I want my CBO to display a list of arbitrarily selected Sales Orders along with their respective delivery dates.
Once this is done, click Publish. After publishing, go back to the “General Information” tab and click on the Go To Generated UI link, which will have now been activated. Create a test entry on the UI, so that we have some test data for our GET request later on.
Create a custom comm. Scenario and a communication arrangement for the CBO
Once the CBO has been created and published, the next step is to create a communication arrangement for it. To do this, use the Fiori app “Custom communication scenarios”. After creating a new custom comm. scenario, click on Add in the “Inbound Services” tab. Here, search for the identifier of the CBO created in the first step and add it as an inbound service. We can ignore the outbound services for now, as these are not pertinent for testing out API operations on our CBO. Save and publish the custom comm. Scenario.
The last step is to now create a communication arrangement for our custom comm. Scenario. Go to the “Communication Arrangements” app and create a new arrangement by selected the ID of the scenario created in the previous step. Select an appropriate comm. System and user for inbound communication and save the arrangement.
With this, all the setup for running API operations on our CBO is complete. Let’s now get into the actual doing. We’ll be using Postman as a tool to test the API calls.
GET data from our CBO
- Copy the inbound service URL from the comm. Arrangement and use this as request URL in Postman.
- In the Authorization tab, select “Basic Auth” and enter the username and password of your communication user.
- Execute the request and you should see the following result
- In the response, we see that the CDS View of the communication arrangement shows our CBO as an existing entity. Append this value to the request URL and execute the result to see the actual results of the data from our CBO, which will look like this:
- We see the test entry we added on the UI being retrieved via the API call to the inbound service of the CBO. In the case that there are multiple data records in the CBO, we can also execute a request to fetch the data of a single Sales Order. This is a bit more tricky, as using the usual filter parameter one uses for standard API endpoints doesn’t produce the desired result. As you can see in the screenshot below, the GET request returns all data records despite filtering only for a particular SalesOrder.
- The solution for this is to use the GUID of the data record, as highlighted by the green box. Append this GUID to the request URL as follows to produce the desired result.
POST data into CBO
Now let’s look at how to post data into our CBO from an external source.
- For POST requests, we require a CSRF token to validate our request. You can fetch a token by setting a header with the key “x-csrf-token” and the value “Fetch” (request method is GET).
- Now change the request method to POST and replace the header value “Fetch” with the token value from the response. In the body tab, you can set the structure of the data you want to post in JSON format and send the request.
- You can see the end result of the operation on the CBO UI.
For POST operations as batch requests (creating multiple Deliveries in a single request), refer to the blog by Marty McCormick, which offers a step-by-step walkthrough for this.
DELETE data from our CBO
Finally, let’s look at how to delete an entry in our CBO via an API call
- Similar to the request for getting a single entry, we need to use the GUID of the data record in order to delete it. Over here as well, we need to provide a valid x-csrf-token in the request header.
- Using the same GUID from the get request earlier (identifying the SalesOrder 342179), we set the request method to DELETE and execute the request.
There is no response visible in Postman after the request, but you can see the change being reflected on the UI, with the SalesOrder 324179 not being shown anymore.
For deleting multiple entries, refer to the blog by Eileen Koehler, which offers a step-by-step walkthrough for this.
The use of CBO’s as part of the key-user extensibility offered within S/4HANA Cloud is a lightweight solution to adapt and enhance standard business objects with custom logic to meet specific customer needs. It is possible to configure inbound and outbound services for your CBO’s and execute the standard API operations on the CBO using the inbound service. Hopefully, this blog post shed some light on how to setup a CBO and handle the fundamental API operations associated with it. Since this post covered the inbound service use cases for the CBO, please refer to the blog post by Taranam Dhindsa to explore how to configure outbound services with Custom business objects. If you’re interested in exploring some more complex scenarios involving the usage of custom logic with CBO’s, make sure to check out my next blog post on the topic.