Introduction

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

Prerequisites

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.

{
	"entity": "custom.SalesOrderDetails",
	"version": "1.0.0",	
	"label": "Custom SalesOrderDetails",
	"sourceEntities": [
		{
			"name": "sap.s4.A_SalesOrder"
		},
		{
			"name": "sap.s4.A_BusinessPartner",
			"join": [
				[
					"SoldToParty",
					"BusinessPartner"
				]
			]
		}
	],
	"attributes": [
		{
			"name": "salesOrder",
			"type": "String",
			"key": false,
			"source": [
				"SalesOrder"
			],
			"sourceEntity": "sap.s4.A_SalesOrder"
		},
		{
			"name": "businessPartnerFullName",
			"type": "String",
			"key": false,			
			"source": [
				"BusinessPartnerFullName"
			],
			"sourceEntity": "sap.s4.A_BusinessPartner"
		}
	]
}

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

• BusinessPartner
• BusinessPartnerCategory
• BusinessPartnerFullName
• FirstName
• LastName

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

• BusinessPartner
• BusinessPartnerCategory
• BusinessPartnerFullName
• FirstName
• LastName

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.

Final Thoughts

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!

References and Further Reading

• teched2023-IN267
• What is Graph
• Custom Entities