Introduction
SAP announced Graph On Integration Suite as GA in Summer of 202 -. Graph: new in SAP Integration Suite. I recently spent some time tinkering around Graph on Integration Suite and this post is the beginners guide to SAP Graph on Integration Suite.
Enabling Graph on Integration Suite
Check Availability on your Data Center
While SAP Graph on Integration Suite is GA, it is also important to know that it is not available on all Hyperscalers yet. SAP Note: 3338820 provides the details on the regions where Graph on Integration Suite is supported. In my case, I spent a few weeks on my Free Tier running on EU20 Azure figuring out why I do not see Graph and how do I enable Graph only to realise after random checks that I missed looking at SAP Note: 3338820. At the moment of writing this post, be aware this is not available on Azure Data Centers and only on AWS ( not all ) and GCP ( not all ) Data Centers.
It is easy to over look this note as you would assume that SAP is consistent across all hyperscalers. Atleast for Cloud Integration and other Integration Suite functionalities, SAP had had a very consistent feature set released. Lesson Learnt and one I keep learning every other day – Never Assume!
Enabling Graph on your Integration Suite
Ensure you have the Integration Suite Provisioner role. Go to “Manage Capabilities” -> “Add Capabilities” on your Integration Suite home . Enable API Managements if not already done using “Manage APIs” section and enable API Hub Enterprise and “Graph” ( API Hub Enterprise is mandatory for Graph ) . If you do not see Graph it means you did not read SAP Note: 3338820 and Graph is not supported in your region. Select “Enable API Business Hub Enterprise” and “Graph“
Note: Graph requires SAP API Management to be activated mandatorily.
Assign Roles for Graph
Once Graph is enabled, on the BTP Cockpit you will now see additional 2 Role Collections for Graph –
- Graph.KeyUser – Role for a Graph Developer to define Business Data Graphs ( BDGs)
- GraphNavigator.Viewer – Role to view Graphs defined in Graph Navigator
Go to your BTP Cockpit and assign these Role collections to you.
Note the term : Business Data Graphs. SAP refers to Graphs as BDGs or Business Data Graphs in their documentation.
All Set for Configuring BDGs
Thats it, you are all set for Configuring BDGs or Business Data Graphs! Logout and Log back on Integration Suite and you will now see Graphs Enabled in Integration Suite under Design Tab.
Enable SAP Graph Entitlement on BTP SubAccount
To be able to connect to SAP Graph API on Integration Suite using OAUTH Client Credentials, you need to enable SAP Graph Entitlement on your SAP BTP Sub Account and generate a Service Instance and Key for it.
Enable Entitlement for SAP Graph
Go to your BTP Sub Account -> Entitlements -> Configure Entitlements -> Add Service Plans and Select SAP Graph -> api
Create a Service Instance
Create a Service Instance. Create a Service Instance of Service SAP Graph , Plan api
Create a Service Key
Create a Service Key for the Service Instance from previous step. Take a note of the Service key as we will use that when we want to explore our Graphs using Postman.
Note the below details of your Service Key
- uaa – clientid
- uaa – clientsecret
- uaa- url ( this will be our token url)
- uri – note the hostname. This will contain our GraphQL Endpoint hostname.
Scenario in Scope
There are 2 ways to understand SAP Integration Suite – Graph. You start with a working example / exercise or you read through SAP’s documentation and theory on Business Data Graph. In my case I read through this documentation from SAP and that was a eye opener on what Graph can do but if you like to do stuff first and then figure out the theory later, then read on.
Both approaches work but in this post I will start with a practical example and then try to tie it back to SAPs excellent documentation on Business Data Graph.
Fetch Sales Order Details with Customer Details
Imagine a S/4Hana System, where you have a BusinessPartner API and SalesOrder API exposed. This could be a S/4Hana On-Premise System or a S/4Hana Public Cloud Edition System. These are classic ODATA APIs from SAP – Business Partner ODATA API and Sales Order ODATA API.
You have a requirement to Query Sales Orders from S/4Hana and while Querying the Sales Orders, you also want to get the Customer Details ( SoldToParty of the Sales Order) . In a typical Integration Context, you will do a ODATA GET on Sales Order API to Get Sales Orders Details and then a enricher or ODATA GET on Business Partner for the SoldToParty. In other words as SAP provides this data in 2 separate APIs, you will make 2 API calls and enrich the data using Cloud Integration.
Do we really need to perform multiple lookup / enrichers?
As you can imagine, this is a typical scenario in Cloud Integration when you are Integrating SaaS Applications. If you have worked on S/4Hana Cloud Systems, and Integrated them with other SAP and non SAP SaaS Systems, you will know, Content Enrichers are you lifeline and lookups are the realities of such systems.
But what if you can get the data exposed in these 2 APIs in one single API call with no Custom Development? Yes, you heard that right . It is possible and it is possible at the click of a button with Graph on Integration Suite ( or BusinessDataGraphs!).
If you have read the theory on SAPs documentation, we will be looking at what SAP calls Mirrored Entities on SAP Graph. There are other more complex Entities like Unified Entities and Custom Entities but we will keep it simple for now and focus on Mirrored Entities and this problem statement of fetching Sales Order Details and its associated Customer Details from a single S/4Hana Cloud system all in a single call.
Create Destinations on BTP
In my case, I have my backend APIs for Sales Order and Business Partner running on a S/4Hana Cloud System. This can also be running on a SAP S/4Hana On Premise System. We will not go into the details of setting up these APIs on S/4Hana Cloud or On Premise Systems as there are multitude of references available elsewhere for this. But we will start with the assumption that you have your ODATA API endpoint and a Technical Communication User set up to access these APIs. We will create 2 Destinations on BTP Subaccount where Integration Suite / Graph is running.
Destination S4_SalesOrder
Create a Destination called S4_SalesOrder or any related name on your BTP Subaccount. In this case, we have chosen to use the Authentication Type as Basic Authentication with a Technical Communication User and Password. You can choose to use OAUTH Client Credentials as well.
Note: We demo this exercise for a System to System Integration for Graph. In a real world, if you want to use Identity Propagation you can also use OAUTH2SAMLBearerAssertion but thats for a follow-up post.
URL of our ODATA API: https://S4APIHOST/sap/opu/odata/sap/API_SALES_ORDER_SRV
Destination S4_BP
Similar to Sales Order Destination create a Destination for Business Partner called S4_BP with ODATA API for URL : https://S4APIHOST/sap/opu/odata/sap/API_BUSINESS_PARTNER
Create a Business Data Graph on Integration Suite
We will now create a Business Data Graph on Integration Suite. Navigate to Integration Suite -> Design -> Graph.
Click on Create ->New Business Data Graph
Provide a ID for this Business Data Graph – Lets call it s4hc-orderdetails and click on next
In the Data Sources screen, select the 2 destinations (S4_BP and S4_SalesOrder) we created in the previous section and click on Next
Leave the Model Extension None and click on Next
Click on Create. The Business Data Graph Configuration JSON you see is what the UI has generated automatically. We will not go into the details of this JSON but if you look at it closely you will notice sap has identified the leading system to be of type s4.The beauty of this will be visible in our next steps!
The BDG status will go into Processing and after a few minutes, it will go into Status Available
Test Your Graph on Graph Navigator
To begin with lets test this Graph using Graph Navigator that is a part of your Integration Suite. Click on the Explore our Ecosystem icon on your Integration Suite on top right and select Graph Navigator
Click on the BDG we just created s4hc-orderdetails
Expand the namespaces sap.graph and sap.s4 to see all the Entities that are auto generated using SAP’s One Domain Model.
Click on A_SalesOrder to test the SalesOrder Entity – Yes all of this is generated automatically using SAPs One Domain Model, but wait there is more. SAP’s One Domain Model generates all documentation and Schema for your Graph / Business Data Graph
Click on Try Out and Run your Graph. You will notice that the data is fetched from your SAP system and displayed here. You will also notice that the query Parameters $top=1, $expand etc. Indeed, your Graphs published using SAP Integration Suite are ODATA V4 APIs that can be queried and handled like any other ODATA V4 APIs.
Navigate around and try it a little more! Click on Navigate to _SoldToParty in the response . Graphs on SAP Integration Suite allow association using One Domain Model.
You will now be able to Navigate to the SoldToParty ( BusinessPartner) from your Sales Order. Also have a look at the URL, and you will notice that you have navigated from SalesOrder to _SoldToParty ( /sap.s4/A_SalesOrder/1/_SoldToParty)
In other words, you have now been able to with just a few clicks get the details of your Sales Order and Customer ( mash up of 2 APIs). All in 1 single API call. And All using ODATA V4 API.
Test your Graph ODATA API
As mentioned in previous section all BDGS exposed on Graph on Integration Suite are available as ODATA V4 APIs. This is documented here on SAP Documentation. We will now use the Service Key we generated in previous section to get our OAUTH token and then use this token to test our Graph as a ODATA API.
Note the URI in your Service Key has the format
https://<<subdomain>>.a.integration.cloud.sap/graph/api
List all BDGs
URL to list all Business Data Graphs exposed in your system
https://<subdomain>.a.integration.cloud.sap/graph/api
List all Services of a BDG (namespace)
List all namespaces of a Specific BDG. Namespaces can be sap.s4, sap.graph, sap.hcm and so on.
https://<<subdomain>>.a.integration.cloud.sap/graph/api/<bdg>
List all Entities in a namespace in a BDG
Entities of a Graph can be displayed using below
https://<<subdomain>>.a.integration.cloud.sap/graph/api/<bdg>/<namespace>
Get Metadata of a Service (Namespace)
https://<<subdomain>>.a.integration.cloud.sap/graph/api/<bdg>/<namespace>/$metadata
Test our Service to get Sales Order Details with SoldToParty
In our example this will be in below format
- Use _SoldToParty for expanding SoldToParty ( note the “underscore”). Thats the standard Graph Notation when you have automatic associations built ( from Sales Order to Business Partner API in our case )
https://<<subdomain>>.a.integration.cloud.sap/graph/api/s4hc-orderdetails/sap.s4/A_SalesOrder?$filter=SalesOrder eq '1'&$expand=_SoldToParty&$select=SalesOrder,SoldToParty
Thats it, you have now invoked your Graph as a ODATA V4 API and you got your Sales Order enriched with a Business Partner Data. Ideally in Cloud Integration what would have been a 2 step process as a Content Enricher, is now a Single Step API call using Graph on Integration Suite
What about GraphQL
Isn’t using Graph all about using GraphQL? Well, do not worry or panic, SAP Graph on Integration Suite supports GraphQL as well. Lets look at how to access the Business Data Graph using Graph QL on Postman. Your Graph BDG is protected using OAUTH2 Client Credentials Grant ( similar to ODATA V4) . So your Authentication on Postman will use OAUTH 2 Client Credentials.
SAP Graph has the below GraphQL endpoint :
https://<subdomain>.a.integration.cloud.sap/graph/api/<bdg>/graphql
Using GraphQL in Postman for Integration Suite Graph (BDG)
Create a new Graph QL Request in Postman
Provide the Endpoint of your GraphQL BDG . In our case this will be
https://{{url}}/graph/api/s4hc-orderdetails/graphql
Ensure you provide your Bearer Token or OAUTH Client Credentials in Authorization Tab and click on Introspection in Postman to get the GraphQL Schema from Integration Suite.
Once the Introspection is completed, Query using GraphQL in Postman to get totalCount (equivalent of $count in ODATA)
Fetch Sales Order Details with Customer Details using Graph QL
As per our use case we will fetch our Sales Order Details with Customer Details ( Business Partner ) using GraphQL similar to what we have done using ODATA. See below screenshot(s). You will see you can navigate from A_SalesOrder directly to the _SoldToParty and get your Business Partner Details.
Recap of what we have done and what it means
- Enabled Graph on Integration Suite
- Configured Graph API access on BTP Subaccount ( Service Instance / Service Key)
- Created Destinations to APIs in S/4Hana Cloud on BTP Subaccount
- Used these 2 APIs / Destinations as a Business Data Graph Source on Integration Suite.
- Tested these Graphs using Graph Navigator
- Tested these Graphs using ODATA V4 in Postman
- Tested these Graphs using GraphQL in Postman
- Navigated to the Business Partner API from a Sales Order API using Graph
Mirrored Entities
If you read through the documentation on SAP Integration Suite Graph what you will realise is that we have so far set up Mirrored Entities on Graph. A Mirrored Entity is a Graph built on APIs from the same SAP System. Use One Domain Model, SAP smartly identifies navigations from one Entity to another ( Sales Order to Business Partner and so on) without us writing a single line of code. For scenarios where you need to navigate to multiple data sets and avoid multiple lookups / content enrichers in SAP Cloud Integration, using Graph seems to be a compelling case.
Additional Topics
Unified and Custom Entities
You can use Graphs to have Associations between multiple Entities in the same System called Mirrored Entities. Additionally Graph also supports Unified Entities and Custom Entities to navigate across multiple Systems which we will look at in follow up posts.
Mutations – Create Update Delete
You can also use Graph and GraphQL Mutations to create update and delete data in your backend systems. Something that needs more detailing in a subsequent post
OAUTH Client Credentials vs OAUTH2SAMLBearer Assertion
In our use case, we have looked at a System to System Integration case for a Business Data Graph. Hence, our destination used was with Basic Authentication. You can also use Graphs with Identity Propagation and we will look at setting up Identity Propagation for Graphs using OAUTH2SAML Bearer Assertion token in a subsequent post.
Use GraphQL Judiciously
SAP Graph on Integration Suite provides both ODATA and GraphQL based access to the Mirrored Entities / Business Data Graphs. A Note of caution : SAP on its documentation on GraphQL provided a disclaimer here that GraphQL based access is still a experimental feature and ODATA Based access is recommended. So while GraphQL based Queries work, use it with caution.
Protect Graph API using SAP APIM
While in this post, we look at Graph API being invoked directly using Graph API Client Credentials, you should also consider using SAP APIM if you plan to expose this to non System to System Integration Use cases. Such a use case is described in this SAP Teched 2023 Hands On Training
Lack of Monitoring and Logs
Unfortunately, there is no logging or monitoring available : Monitoring and Troubleshooting at the time of writing this post. So if this Graph stops working you are at the mercy of SAP and SAPs incident management process. This is a very new feature from SAP and hence before going full blown into using this, I would like any “new product” take this for a spin on a low risk case.
Final Thoughts
Future of APIs at a Customer using a SAP ecosystem of products will probably use Graphs extensively. We have only scratched the surface of SAP Graphs in this post but this could be a good start to someone new to the world of Graphs in the SAP world.