We have looked at Mirrored Entities in our previous posts Graph on SAP Integration Suite – A Beginners Guide and Unified Entities in Graph on SAP Integration Suite – A Beginners Guide -Part 2 – Building Unified Entities. In both these Graphs exposed on SAP Integration Suite, you would have noticed that we expose the entire ODATA Entities of your Backend APIs to SAP Graph.
Imagine a scenario where you want to expose a ODATA API to your consumers.
ODATA APIs as you know can have lots of fields / entities. What if you want to restrict the fields that are exposed? What if you want to restrict the Entities that are exposed? What if you want to build a ODATA API that does a lookup from 2 Backend APIs ( Unified Entities ) with restricted fields?
Welcome to the world of Custom Entities on SAP Graph on Integration Suite. As the name implies, you can define Custom entities on SAP Graph and expose them to your API consumers. In this post, we look at 2 scenarios for Custom Entities and how you can develop Custom Entities on SAP Graph on Integration Suite.
A ODATA API on your backend system can have lots of fields. What if you wanted to expose only a subset of these fields? Prior to having SAP Graph on Integration Suite in my arsenal, ideally we would have built a ODATA API on Cloud Integration or built a REST API that handles all ODATA Operations. That was not ideal and came with tons of development work. In the world of SAP Graph, Welcome – Custom Entities! Custom Entities as the name implies allows you to define Custom Entities in your Graph and map them to fields from your Source. While this might sound complex, its quite straight forward. In this post we will explore how to use Custom Entities on SAP Graph.
Scenario in Scope
We will extend the scenario from Graph on SAP Integration Suite – A Beginners Guide where we used a Mirrored Entity to get Sales Order Details along with the associated Business Partner details. In this Mirrored API , we exposed all fields of the ODATA API. We will now create a new Custom Entity on SAP Graph that only exposes the below 2 fields
|Graph Field Name
|Source ODATA API & Entity
|API Field Name
|API_SALES_ORDER_SRV : A_SalesOrder
Ensure you have a working scenario from Graph on SAP Integration Suite – A Beginners Guide. We will use the same destinations as in this post.
Create a Model Extension
Using Model Extension UI from SAP vs JSON File
SAP Integration Suite Graph has a Modeler to define the Custom Extensions. Unfortunately at the time of writing this post ( Dec 2023) this is not always very stable and does not work for all ODATA Entities. In our case when we tried this for the A_SalesOrder ODATA Entity , this did not work. Hence we chose to create the Model Extension using a JSON File. In an example later in this post we will look at using a Model Extension using the Modeler from SAP.
Create a Model Extension using JSON File
Navigate to Graph on Integration Suite and click on Model Extensions -> Create -> From File
Provide a name for the extension : extension_SalesOrderDetails in our case and provide the JSON file below as the input file. Click on Create. We will look at this JSON in details in the next section.
"label": "Custom SalesOrderDetails",
Create a Business Data Graph referring to Custom Model Extension
Like we did in previous posts, we will create a new Business Data Graph on SAP Integration Suite that will use the Custom Model Extension from our previous section.
Select the Data Sources (S4_BP and S4_SalesOrder) in our case.
Select the Model Extension as the Model Extension from our previous section: extension_SalesOrderDetails
Click on Create. If you look at the JSON, you will notice that the custom.SalesOrderDetails is also now present in the rules section.
Test Your BDG for Custom Entities
Test your Business Data Graph with the namespace custom and you will see that the data returned is the 2 fields you have defined in the Model Extension.
What have we done so far?
- Created a Model Extension as a reference to a external JSON file.
- Created a BDG that uses this extension
- Tested the BDG.
Understanding the Custom Model Extension JSON
You can see the definition of the custom model extension in the below JSON. Some of the key factors to note –
- Entity should always start with custom.
- sourceEntities maps to the ODATA Entities.
- Define join conditions to map the SoldToParty to BusinessPartner
- Define the fields and the source.
Using Modeler for the Custom Model Extension
Instead of creating the JSON directly, SAP Integration Suite Graph has a Modeler to define the Custom Extensions. Unfortunately at the time of writing this post ( Dec 2023) this is not always very stable and does not work for all ODATA Entities. In our case it did not work for A_SalesOrder.
Lets try to use this for a scenario ( that works) . Lets assume you want to expose the Business Partner API from S/4HC but you only want to expose the below 5 fields of the Business Partner
Create Model Extensions
Click on Create -> New Model Extension.
Provide name as : extension_BusinessPartnerDetails and in the option use metadata from business data graph select your BDG (s4hc-orderdetails) from Part 1 and click create.
Click on Create a Custom Entity
Provide a name: custom.businesspartnedetails ( Note: name always has to start with custom.)
Select sap.s4_A_BusinessPartner in your Main Source Entity
Select below fields in your BusinessPartner and click on create
Click on save
Create a BDG for the Custom Model Extension
Like previously create a new BDG for this Custom Model Extension. Provide id: s4hc-bpdetails
Select Data source as S4_BP
Select extension_BusinessPartnerDetails from the previous section
Click on Create
Test Your Custom Model Extension / Custom Entity
Test your Graph using Graph Navigator / Postman.
Exposing a Custom Entity in SAP Graph on Integration Suite using the Modeler is very easy. In our tests ( Dec 2023), we have noticed that SAP provides a Modeler that works for some ODATA APIs and does not work for other ODATA APIs. This possibly is being fixed by SAP and at some point, defining Custom Entities using the Modeler should work for all ODATA Entities.
If you plan to expose your Graph to external consumers and want to ensure only your custom entity can be accessed, you should ideally expose your Graph over a SAP API Management API Proxy so only the /custom API is exposed. This is described in this post : teched2023-IN267
A critical use case for Custom Entities on Graph is that it allows you to restrict the number of fields exposed in your ODATA APIs. Previously you had no such option without building custom Integrations or ODATA APIs in Cloud Integration but with Graph and Custom Entities on Graph you can now easily filter and expose only restricted fields of your backend ODATA APIs to external consumers.
In our next posts, we will look at Mutations for Mirrored Entities, Unified Entities and Custom Entities. Stay Tuned!