SAP Community - SAP Graph

Information Map – Introduction Series: Graph in SAP Integration Suite

2024-02-21T15:10:07.961000+01:00

Graph is a powerful enhancement to API Management, capability of SAP Integration Suite , which supports in transforming APIs. You can easily and securely, provide your integration and application developers with selective, abstracted access to your enterprise data via a single, easy-to-use API. The enterprise data is semantically connected in the form of a business data graph.

This series is designed to support SAP customers and partners through building a first end-to-end implementation of Graph. To keep things straightforward, there are two personas in an end-to-end Graph implementation, which have the following responsibilities:

Administrator
- Configures the SAP Integration Suite service plan in SAP BTP, as well as SAP BTP users and their roles
- Enables connectivity to business systems in the form of SAP BTP destinations
- Creates a business data graph (including model extensions, as required)
- Explores the resulting business data graph in the Graph Navigator tool
- Prepares the credentials file to the business data graph for the developer

Developer
- Uses the Graph Navigator tool to explore the connected entities and try out OData queries on the real data included in the business data graph
- Creates and deploys an application which uses the Graph API (and the credentials file for the business data graph)

Available introduction series parts

________________________________________________________________

Palak Garg, Product Manager – SAP Integration Suite

Learn more about Graph in the SAP Community

Graph intro series, part 1: Introduction to Graph in SAP Integration Suite

2024-02-22T15:40:46.459000+01:00

Hello, and welcome to the first in a tutorials series about the Graph functionality of API Management, a main capability of the SAP Integration Suite. In this series, we will take you from learning about what Graph is, to creating your own business data graphs with custom model extensions, all the way to becoming a developer who is proficient in using Graph as an access point to your business data, regardless of where this data resides.

For an overview of other parts of this series, check out the Information Map.

With Graph, you create an abstraction of business objects (aka entities) available in your landscape of business systems, in the form of a business data graph. The business data graph exposes the data of these business objects through a single, unified API. Application developers use powerful OData v4 or GraphQL commands to access only the data required to build the application and do not need to concern themselves with the complexities of the underlying data source systems.

SAP is famous for its ERP software, but today SAP customers have increasingly more complex requirements and are managing intricate and hybrid on-premise and cloud solutions. Customers want to become Intelligent Enterprises. To support their journey, SAP has augmented its ERP-centric business suite with substantial additional functions through the acquisition of cloud solutions like SAP SuccessFactors, SAP Concur and SAP Ariba. SAP’s Intelligent Suite portfolio now supports all key business processes and span all enterprise functions, but this expanded role and diversity of solutions has introduced some complexity. Many of SAP suite’s products have their own stack: overlapping data models, different APIs and heterogenous infrastructures, and this complexity is not always well hidden from SAP’s customers.

From the perspective of a software developer, this means that accessing SAP-managed data has become more complex. Data may be federated across hybrid networks of on-premise and cloud systems with different security protocols, replication processes and multiple master data copies. You don’t only have to worry about the data you are interested in, you have to know which copy you need, where that data exactly is located, and how to deal with connecting to these different customer systems. Different products have different connection protocols, security requirements and APIs, and those APIs expose data using different and inconsistent data models. Developing SAP extension apps requires mastering a broad set of skills for even the simplest data queries, and the applications you develop are sensitive to the smallest product and landscape configuration changes.

This is the problem that Graph addresses.

Graph is a new unified API for SAP. It addresses this run-away API complexity and integration challenge by providing developers a single connected and unified view of all their business data, consolidating the data models of data sources like SAP S/4HANA, SAP Sales Cloud and SAP SuccessFactors into one, unified and connected, data model, representing all the data in a landscape. We call this the Business Data Graph.

A data graph is a connected graph, with data entities serving as the nodes of the graph and edges that represent relationships (which we call associations) between those entities. The nodes of the Business Data Graph are the common enterprise business objects, like Customer, Supplier, Product, Sales and Purchase Order, General Ledger, etc.

As a developer, you face a dilemma. The concept of a Product or a Customer is common to many of the business systems that make up a landscape. Which of these definitions should you use? Where in the landscape is this data managed? Graph addresses this dilemma by introducing unified entities that provide the most common attributes of a business model for easy consumption and connect to the corresponding system-specific business objects for a full 360° view of the business object. You get to have your cake and eat it too: use the unified entities for simple use-cases, and easily access over 1,500 additional system-specific entities for advanced usage.

To illustrate these aspects of the business data graph, it is best if we start with a simple example taken from the enterprise world of sales. A salesperson entered a quote on behalf of a customer.

This quote is represented by a unified SalesQuote entity. The quote has an association to a Customer entity. The quote also has multiple items, each of which refer to a Product entity, which in turn has multiple associations to other entities, like Division. This is illustrated below:

Each entity has many additional attributes, such as a key (called id in unified entities), and various other attributes, which can be flat, arrays, or more complex structured compositions of other attributes. For instance, items is an array of a structured type.

With Graph you navigate to and access the data you need, regardless of where this data resides. Graph abstracts the physical landscape and the details of the different product stacks and offers you a simple view of the SAP-managed data, which you can access through a single API, spanning all key use cases. Graph accesses the data in the customer-configured landscape on your users’ behalf, technically acting as middleware. Graph itself doesn’t store or cache any data.

The above illustration shows your app accessing quote, product, customer and supplier data – but the app cannot tell if this is data is accessed from an on-premise SAP S/4 HANA system, SAP Sales Cloud or another system, like SAP Ariba. This will be determined by the specific landscape configuration that Graph accesses on behalf of the app user. As a developer, you are exempted from knowing these system details, or how to access data in these heterogenous systems. More importantly, your application will be portable across multiple and diverse landscapes without changes to your code.

But what if your app requires detailed attribute information that is not modeled in the unified entity? For instance, your app may be interested in Product inventory information, that is unique to data sources of type S/4HANA. No problem! Simply navigate over the _s4 association to access the required information, like the CountryOfOrigin of the product, or navigate further via the to_ProductStorage association.

The unified entities introduced here are actually examples of a much more powerful capability of Graph: the ability to create your own custom entities and model extensions, effectively allowing you to create your own landscape and data abstraction. We will discuss how to create your own custom entities and model extensions in a subsequent blog in this series.

Graph currently supports the OData v4 and GraphQL protocol to access the business data graph. OData (Open Data) is a widely used OASIS standard that defines a set of best practices for using RESTful data APIs.

As we shall see, OData and GraphQL APIs are easy and powerful to consume. OData requests operate on resources, the data, and extends this with query options, that let you shape the response to queries. The resources of Graph are the entities of the business data graph. GrphQL offer a similar experience, with a more intuitive syntax.

Exploring Graph using the Graph Navigator

The Graph of SAP systems is documented by the Graph Navigator on SAP Business Accelerator Hub. Go ahead and follow the link to the Graph Navigator to explore the the full graph of SAP systems. The index, on the left of the application, shows you over 1,500 entities grouped by data source. The first group of entities, in the sap.graph namespace, are the unified entities. Here is an example of a unified entity, the sap.graph/WorkAssignment.

Unified entities have a key, called id. You can see other attributes, like workforcePerson, the identifier of the person whose assignment this is. You can also see an association (a link) to the details of this person, another entity unsurprisingly called sap.graph/WorkforcePerson. Another interesting attribute is jobInfo. This is a composition, in this case of composition of many”, which you can think of as an array of this structure. Click on the little > arrow to see what it looks like, or study the example on the right, where you can see an array of one instance.
Finally, it is worth pointing out two more interesting associations, _cxsales and _hcm. These are links to the respective system-specific entities, sap.cxsales/EmployeeCollection and sap.hcm/EmpEmployment. They enable developers to augment the information available in the unified entity with system-specific attributes, and make the business data graph a connected and navigable graph of the entire enterprise landscape. Go ahead, click around the Graph Navigator to get a sense of what the full SAP-based business data graph looks like.

With this quick introduction out of the way, follow us to the next part of the blog series where we set up Graph in SAP Integration Suite.

________________________________________________________________
Chaim Bendelac, Chief Product Manager – API Management and Graph
Visit Graph on the SAP Community

Graph intro series, part 2: Set up Graph in SAP Integration Suite

2024-02-23T09:37:46.550000+01:00

In this part we address you, a person with an IT administrative role and responsibilities for enterprise data. Please refer to Part 1 for an introduction to Graph, and to the Information Map for an overview of the entire tutorial series.

As always, you can find all the details for what we are going to discuss here in the Graph documentation on the SAP Help Portal.

The SAP Business Technology Platform (SAP BTP)

Enterprises and other companies deploy a variety of business software solutions to manage their major business processes. We refer to these software systems as data sources, and to the collection of data sources as the landscape. As we shall see, the business data graph is a connected graph of the business data in your landscape.

Enabling access to a landscape involves a great many concerns, related to connectivity, user management, trust, and other security topics. Establishing these aspects is exactly the role of SAP’s Business Technology Platform (SAP BTP), available on multiple cloud infrastructure providers. As an owner of data sources, you use the SAP BTP cockpit as the central point of entry, where you can access your accounts manage all activities associated with them.

Graph is a powerful addition to the API Management capability in SAP Integration Suite. Graph can be used in any SAP Integration Suite plan where API Management is available (including SAP BTP trial accounts), but not necessarily in every region where API Management is available. For more details about the regional availability of Graph, be sure to check out SAP Note 3338820.

Configuring Graph

If you are not familiar with the SAP BTP cockpit, there are many blogs, videos and tutorials (like this one) to make you feel at home. Here we will assume some familiarity with the SAP BTP Cockpit to apply the following process:

Create a subaccount, which represents your landscape
Create the SAP Integration Suite service
Add Graph to SAP Integration Suite
Assign yourself Graph roles in SAP BTP
Set up destinations to the data sources of your landscape
Generate credentials, by creating a service binding

Step 1: Create a subaccount

Use the SAP BTP cockpit to login to your “global” account. Create a subaccount:

Enter the subaccount display name, for instance Graph Sandbox (this will also fill the subdomain field with a unique string)
Set Region, for example to Europe (Frankfurt) under Amazon Web Services (CF-EU10).

Click Create; wait until the subaccount is created.

Next, enter the subaccount by clicking on its tile, select Entitlements from the left-side menu, click Configure Entitlements and then Add Service Plans, search for SAP Integration Suite, check the plan you wish to use, and confirm by clicking the Add 1 Service Plan button. Don’t forget to click Save.

Note: The SAP Integration Suite trial plan is automatically entitled for the default SAP BTP Trial subaccount, and Graph can also be seamlessly deployed there.

Step 2: Create the SAP Integration Suite service

In the SAP BTP cockpit, select Instances and Subscriptions from the left-side menu, click Create and then configure the SAP Integration Suite service with your desired plan.

Then select Security > Users from the left-side menu and assign your user the Integration_Provisioner role collection. You can do this by clicking the user name, and then selecting ‘…’ under the Role Collections table. Find the Integration_Provisioner role collection and assign it.

Step 3: Add Graph to SAP Integration Suite

At this point, you should have an SAP Integration Suite application that you can access and add capabilities to. Go to Instances and Subscriptions in the left-side menu, and open the SAP Integration Suite application.

Select Add Capabilities to open a menu where you can select Manage APIs.

By clicking Next, you are taken to the API Management setup step where you must enable both API Business Hub Enterprise and Graph.

Finally, select Activate and wait for the newly configured capability to show ‘Active’ for all selected features.

Step 4: Assign yourself Graph roles in SAP BTP

Graph has two dedicated SAP BTP role collections: Graph.KeyUser and GraphNavigator.Viewer. The role collection GraphNavigator.Viewer provides access to explore the entities and try out OData queries on the real data reflected in the business data graphs in the SAP BTP subaccount in the Graph Navigator tool in SAP API Business Hub Enterprise. This role collection is relevant for developer persona.

The role collection Graph.KeyUser is required to configure business data graphs in the SAP Integration Suite application. The Graph.KeyUser role collection also includes navigator viewer role to access Graph navigator.

Select Security > Users from the left-side menu and assign your user the Graph.KeyUser role collection. You can do this by clicking the username, and then selecting ‘…’ under the Role Collections table. Find the role collection and assign it.

At this point, you should be able to navigate to the Graph user interface in the SAP Integration Suite application. You can open the Graph user interface from the SAP Integration Suite application left-side menu under Design Artifacts. We will come back to the Graph user interface in the next part of the blog tutorial series. The rest of the blog focuses on the remaining setup in the SAP BTP cockpit.

Step 5: Create destinations

In this tutorial, we will use the SAP Business Accelerator Hub sandbox systems as data sources. Note that creating destinations to other data sources is often more complex, due to trust establishment. Refer to the Graph documentation for more information.

Within the same subaccount, select Connectivity / Destinations from the left-side menu and click New Destination, as follows:

Fill in the form as follows to create a destination to the SAP CX Sales Cloud sandbox system:

Use cxsalescloud as the name and https://sandbox.api.sap.com/sap/c4c/odata/v1/c4codataapi/ as the URL.

Since the sandbox APIs require an API key in HTTP headers, we will add this header. Click New Property, then enter URL.headers.apiKey as property name and enter your unique API key from the SAP Business Accelerator Hub as the value. Then Save.

You can easily repeat this process to create additional destinations, by cloning this destination, and changing the Name and URL fields. Go ahead, and add another destination named s4_product, with the following URL: https://sandbox.api.sap.com/s4hanacloud/sap/opu/odata/sap/API_PRODUCT_SRV

Here are additional useful API services to consider:

SAP SuccessFactors: https://sandbox.api.sap.com/successfactors/odata/v2
SAP S/4HANA Business Partner: https://sandbox.api.sap.com/s4hanacloud/sap/opu/odata/sap/API_BUSINESS_PARTNER
SAP S/4HANA Sales Order: https://sandbox.api.sap.com/s4hanacloud/sap/opu/odata/sap/API_SALES_ORDER_SRV

Step 6: Create a Graph service instance

To consume your Business Data Graph OData endpoint, you need to have service credentials to get a valid token. To do so within the same subaccount, select Services / Instances and Subscriptions from the left-side menu, and then click Create in the top-right corner.

In the wizard:

Select Process Integration Runtime from the drop-down service menu.
Select the integration-flow service plan.
Select Cloud Foundry as runtime environment and select the space.
Enter an instance name. For example, sapgraph1. Choose Create.
Click the three dots to the right of the created instance and select Create Service Key (for more info check Graph documentation here).
Download and save the created credentials as a text file:

In summary

The steps above complete the configuration of the landscape and the preparations for creating a business data graph for your developers. The final step is to create the business data graph itself – this will be the topic of the next part of this tutorial series.

________________________________________________________________
Hamid Reza Laleh, Product Owner – Graph
Visit Graph on the SAP Community

Graph intro series, part 3: Construct and explore a Business Data Graph

2024-02-23T09:38:54.537000+01:00

In this part of the series on Graph – the new API for connecting to your business data – we will discuss the concepts and configuration of the Business Data Graph. Please refer to the Information Map to see all parts of this series. The Graph documentation on the Help Portal provides an in-depth look at many of the concepts featured in this part. 

The “data graph” concept is central to the Graph capability. The business data graph is essentially the artifact that connects the business data together. The administrator is responsible for creating and shaping how the data in the business systems is reflected in the business data graph.

A data graph consists of mirrored entities, which are projections of the business objects that Graph automatically discovered in the business systems. They are mirrored one-to-one in the data graph and grouped in namespaces that correspond to each business system. Then the mirrored entities are connected through additional semantic connections.

Additional projections, called unified entities, are created on top of the mirrored entities. They connect semantically common business concepts from multiple data sources and are created in the namespace sap.graph. It is also possible for customers to extend the data graph by creating custom entities. We will address model extensions in a separate blog post.

Finally, the data graph is activated to create a business data graph, which is a runtime artifact based on the configured data graph, and accessible as a unified API.

The official documentation set provides goes more in-depth of what is described in this section and can be accessed here: SAP Help Portal: Graph - Business Data Graph

We pick up from where we left off at the end of the previous blog. You previously set up Graph in SAP Integration Suite, created destinations to data source endpoints, and assigned yourself the dedicated Graph role collections. Also, you created a service binding for Graph and generated and downloaded the credentials text file.

In the following steps, you will construct a business data graph from the data sources you previously configured as SAP BTP destinations and explore the business data graph in the Graph Navigator tool.

Construct the Business Data Graph 

1. In the SAP Integration Suite application, select Graph under Design Artifacts in the left-side menu.

2. Select Create new business data graph in the center panel.

3. Provide an ID for the business data Graph. Use lowercase letters, numbers, and hyphens.

4. Select the data sources you would like to include in your business data graph. These are the destinations you previously configured in the SAP BTP cockpit. Select Next.

5. Skip the optional Model Extension step for now, by selecting Next. Your draft business data graph gets generated.

6. Review the configuration file and select Create to activate the business data graph.

7. Wait for the Status to update to be Available. Eventually, the status goes from Processing to Available.

Note: You can navigate to more information about individual business data graphs by selecting >. You can edit or delete the business data graph, or view the logs.

Explore the business data graph in the Graph Navigator

You just created your business data graph. Wouldn’t it be cool to explore the semantic connections between the data entities and even try out a few OData queries on the real data in the business systems? You can do exactly that using the Graph Navigator within API Business Hub Enterprise! This section takes you through exploring the business data graph you created in the previous section, using the Graph Navigator tool.

1. Open the Graph Navigator tool in API Business Hub Enterprise by selecting the menu icon in the top panel and then Graph Navigator.

2. The Graph Navigator automatically lists all the business data graphs in your SAP BTP subaccount. Select the business data graph you previously created.

3. On the left, in the Entities index, you see a search window, and collections of the available entities, grouped per namespace.

4. Depending on the data sources you included in your business data graph, you may have three namespaces containing the business objects from SAP SuccessFactors (sap.hcm), SAP S/4 HANA (sap.s4) and SAP Sales and Service Cloud (sap.c4c). Open one of these three namespaces. For instance, pick the sap.c4c namespace, and then select SalesQuoteCollection under Sales Quote.

5. You can easily see which operations are allowed (create, read, update, and delete), review the list of attributes, and see an actual data example. Take the time to explore the root entities (potentially representing 4,500+ entities and sub-entities in SAP systems), in the different namespaces, within the Graph Navigator context.

6. Explore one of the unified entities in the sap.graph namespace, the top namespace in the list on the left. Unified entities are simplified projections on some of the most complex business objects in SAP systems. They are useful in particular for apps that only require basic, essential information.

For instance, you can search for sales quote (or SalesQuote) in the search box on the left and pick the first search result: sap.graph/SalesQuote.

This too is a synthetic entity, a projection, of the actual sales information in your systems.

7. Now switch to the Try Out tab at the top.

8. You can see an OData request, for one record of sap.graph/SalesQuote ($top=1). Click Run. You will see your Sales Quote appear on the screen.

9. Now let's have some fun. Use the $expand button to check _salesOrganization and _distributionChannel. Did you see how this automatically changed the OData request?

10. Click run to see the result of this query. Scroll down to see the expanded sales organization and distribution channel information. As you can see, this is a (mock) quote from one of BestRun's direct sales customers in the US.

11. We could try out different variations of "$expand", to get of sense of all the data. Here is another fun query we can try:

/sap.graph/SalesQuote?$top=1&$expand=items($expand=_product)

and learn that the customer was quoted a single calculator which is of product type 3.

12. When dealing with a specific single record, we can also navigate across the data to access other pertinent information. First, let's expand the customer (a business partner) on our order to find out the type:

/sap.graph/SalesQuote/c4c~1?$expand=_soldToParty

13. This is a corporation, so we can navigate to:

/sap.graph/SalesQuote/c4c~1/_soldToParty/_corporateAccount

Let's also add some options to the query before we run it:

/sap.graph/SalesQuote/c4c~1/_soldToParty/_corporateAccount?$expand=addresses,contacts

14. Expanding and navigating are two powerful capabilities. But what makes data graphs even more useful are queries that combine these capabilities with other features, such as:

$select: return only the attributes you need

$filter: use data selection criteria

$orderby: return results in sort-order.

For instance, the following query lists ten sorted (ascending order) quotes by netAmount greater than 2000, with customer names and sales organization:

/sap.graph/SalesQuote?$top=10&$expand=_soldToParty($select=name)&$filter=netAmount ge 2000&$select=id,netAmount,salesOrganization&$orderby=netAmount

In summary

This part of the series concludes the basic introduction to Graph. In the previous part, we learned how to set up a landscape for Graph, which we used in this part to create a business data graph and explore it in the Graph Navigator tool.

––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––

Marc Vornetran, Product Owner – Graph in SAP Integration Suite

Learn more about Graph in the SAP Community

Graph intro series, part 4: Hello Graph! Write your first Graph application

2024-02-28T10:16:21.965000+01:00

This is the first of the end-to-end implementation blog series for Graph that focuses on a developer writing an extension application that uses the single, unified API of Graph in SAP Integration Suite. Please refer to Part 1 of this series for an introduction to Graph and to the Information Map for an introduction to the entire series.

The initial developer parts in this series will lead you through building the rudimentary basics of a classical enterprise extension web app: a list-details-navigate application in the next part. This is what it will look like:

Here, in this part, our goal is to establish the basic hello world programming essentials. This implementation requires no prior knowledge – we will teach you everything you need to know to become a proficient Graph developer. To test that everything works, we will re-use the Graph server that was configured as an SAP Business Accelerator Hub sandbox, and that we used in Part 1.

Getting Started: Node.js and NPM

We will use node.js (v20.11.1) and npm (version 10.2.4) to build this application and to keep it extremely simple, we will use the express web framework. Not familiar with node.js and express? I recommend this article on the Mozilla Developer Network (MDN) website. This article also explains how to easily set up a Node development environment, whether you use Windows, MacOS, or Linux.

If you prefer to develop applications in the cloud directly from your browser, SAP offers a great cloud-based development experience alternative in the form of the SAP Build. Follow this link for more details on getting your instance. The rest of this blog assumes that you installed node.js and npm on your computer.

package.json

Select a folder (directory) where you want to develop your application. In this folder, create a small file called package.json, with the following content:

{
    "name": "hello-graph",
    "version": "0.0.0",
    "private": true,
    "type": "module",
    "scripts" : {
        "start": "node src/hellograph.js"
    },
    "dependencies": {
        "express": "4.18.1",
        "node-fetch": "3.3.2",
        "universal-cookie": "7.1.0"
    }
}

Note: For the latest version of these libraries please refer to https://www.npmjs.com/

After saving the file, run the following command on your console:

npm install

If your node.js environment was properly set up, then this command will install a few standard library packages in a new sub-folder called node_modules.
Now, create another sub-folder, next to node_modules, called src. This is where we will develop our code.

graph.js

First, we will create a boilerplate file in the src folder, called graph.js. This file will serve as a foundational template that you'll reuse, with a few small changes, across all future Graph implementation blogs and your projects. This file will contain a class called Graph, which provides a nice wrapper for using Graph. At this time, we will show how to read data, using a get() function.

Copy and paste the code below into the file, then save it. This straightforward snippet utilizes the node-fetch package for simplicity.

import fetch from "node-fetch";
export default class Graph {
    async get(entity, params) {
        const url = `https://sandbox.api.sap.com/sapgraph/${entity}${params ? `?${params}` : ""}`;
        console.log(url) //for debugging 
        const options = {
            method: "get",
            headers:{
                "Accept": "application/json",
                "apiKey": "<your-api-key>" // TODO: Enter the actual key
            }
        };
        const response = await fetch(url, options);
        console.log(`${response.status} (${response.statusText})`) // for debugging
        return await response.json();
    }
}

Please note that we hard-coded the Graph server that uses the SAP Business Accelerator Hub sandbox. This allows us to focus here on the data access API, without requiring you to configure a new Business Data Graph(BDG) and deal with all the complex aspects of security and authentication, which will be the subject of future blog series.
Since we are accessing the sandbox landscape data via SAP Business Accelerator Hub, you will need to insert your API Key (a short string) into the code above. Where do you get this key? Simply log in to https://api.sap.com/settings and click on Show API Key to see and save it.

hellograph.js

Now we are ready to write our first, simple server-side application that uses Graph. Paste the following into a new file, called hellograph.js, in the src folder:

import express from 'express';
import Graph from './graph.js';

const app = express();
const port = 3004;
const graph = new Graph();

app.get('/sap*', async (req, res) => {
    const response = await graph.get(`${req.url}`, "");
    res.setHeader('Content-Type', 'application/json');
    res.json(response);

app.listen(port, () => { 
    console.log(`Explore Graph at http://localhost:${port}`) 
});

As previously mentioned, our code uses a popular node.js package called express. On line 8, we define the action taken when our server-side app is called from a browser. Here, we simply take the URL that we received (req.url) and pass it through to Graph. We then show the returned data from Graph as a raw result on the browser screen.

Our server-side app is ready. To run it, use your terminal console to enter:

npm run start

The console will show:

$ Explore Graph at http://localhost:3004

Now the fun begins. The application expects a well-formed query URL to function properly. Open a browser window or tab, and enter the following query URL:

http://localhost:3004/sap.graph/SalesQuote?$top=2

The browser will invoke your application code, which will call Graph to fetch the data, and if all goes well, you will see the following output on your screen.

Note: if you get an unformatted result, you can install a JSON formatter in your browser.
Our Hello Graph app is already pretty useful; we can use it to explore the business data graph, by trying out different OData queries. Note: to stop your app from running, simply kill it (e.g. press CTRL-C on your Linux terminal or Windows console).
We will re-use this app as a skeleton in the next part of this series, where we will introduce authentication.

Shardul Sonar, Developer – Graph in SAP Integration Suite

Learn more about Graph in the SAP Community

Graph intro series, part 5: Use Graph Securely with Real Data – Authentication

2024-02-28T15:12:59.976000+01:00

Here, in this part of this tutorial, we are going to build the rudimentary basics of a classical enterprise extension web app: a list-details-navigate application. Please refer to Part 1 of this tutorial for an introduction to Graph in SAP Integration Suite, to the previous tutorial part for an introduction to the programming interface of Graph, and to the Information Map for an introduction to the entire tutorial series.

Business Data Graphs

In the previous part, we accessed data from a preconfigured Graph sandbox server via SAP Business Accelerator Hub. We even embedded this server URL into our code. Anybody with an API key can access the sandbox data, without any further authentication or authorization.

Of course, this is not a secure way of accessing confidential business data. Therefore, in this part of the tutorial, we will access Graph securely, via the oAuth protocol. OAuth doesn’t share password data but instead uses authorization tokens to prove an identity between clients and services like Graph and supports Single Sign On. With oAuth, you effectively approve your browser to interact with Graph on your behalf without giving away your password.

Graph is a multitenant service. Customer administrators use the SAP Business Technology Platform (BTP) to subscribe to Graph in SAP Integration Suite, by configuring one or more business data graphs. We discuss this topic in more detail in a separate part of this tutorial, but for this tutorial part it is important to understand that the business data graph is the key to a specific landscape of customer systems. Most customers will configure multiple landscapes, for instance for development, staging and productive usage.

Each Graph business data graph is unique with unique credentials, such as its URL, its business data graph identifier and various secrets/tokens.

credentials.js

To programmatically access the data from a Graph business data graph, an application requires these credentials. How do you get them? A file containing them, credentials.json, is created during the process of setting up and configuring the business data graph. You receive this file and the business data graph identifier from the BTP administrator or key user who configured the specific business data graph you want to access.

Save the credentials file in the src folder of your project (you can use the existing src folder in which we developed our very first hello Graph server-side application, or create a new source folder in your project, up to you).

auth.js

In the same src folder, create a file called auth.js, paste in the following boilerplate (standard) code, and save:

import credentials from "./credentials.json" assert { type: "json" };
import fetch from "node-fetch"; 
import Cookies from "universal-cookie"; 
const CALLBACK_URI = "/myCallbackURI"; 
const CookieName = "SAPGraphHelloQuotesCookie"; 

export default class Auth { 
    constructor() { 
        this.clientId = credentials.uaa.clientid; 
        this.clientSecret = credentials.uaa.clientsecret; 
        this.authUrl = credentials.uaa.url; 
    } 
    getToken(req) { 
        const cookies = new Cookies(req.headers.cookie); 
        return cookies.get(CookieName); 
    } 
    async fetchToken(code, redirectUri) { 
        const params = new URLSearchParams(); 
        params.set('client_id', this.clientId); 
        params.set('client_secret', this.clientSecret); 
        params.set('code', code); 
        params.set('redirect_uri', redirectUri); 
        params.set('grant_type', 'authorization_code'); 
        const response = await fetch(`${this.authUrl}/oauth/token`, { 
            method: 'post', 
            headers: { 
                'Content-Type': 'application/x-www-form-urlencoded', 
                'Accept': 'application/json' 
            }, 
            body: params 
        }); 
        const json = await response.json(); 
        return json.access_token; 
    } 
    getMiddleware() { 
        return async (req, res, next) => { 
            const redirectUri = `${req.protocol}://${req.get("host")}${CALLBACK_URI}`; 
            if (req.url.startsWith(CALLBACK_URI)) { 
                const code = req.query.code; 
                if (code) { 
                    const token = await this.fetchToken(code, redirectUri); 
                    res.cookie(CookieName, token, { maxAge: 1000 * 60 * 120, httpOnly: true,  path: "/", }); 
                } 
                res.redirect("/"); 
            } else if (!this.getToken(req)) { 
                res.redirect(`${this.authUrl}/oauth/authorize?client_id=${encodeURIComponent(this.clientId)}&redirect_uri=${encodeURIComponent(redirectUri)}&response_type=code`); 
            } else { 
                next(); 
            } 
        }; 
    } 
}

As you can see, this boilerplate authentication code refers to several pieces of information which are extracted from the credentials.json file, and are used to log the user of your application in, using single sign on, according to the specifics of the business data graph. For the user’s convenience, it also saves the obtained access token as a cookie, so that it can be used until it expires.

graph.js

We will re-use the Graph class that we saw in the previous part of this tutorial, but now that we are required to authenticate the user before we can use the business data graph, we need to make a few small changes. Copy the following text into graph.js and save.

import credentials from "./credentials.json" assert { type: "json" };
import fetch from "node-fetch";
const apiUrl = credentials.uri;
const dataGraphId = "v1"; // example, modify accordingly 

export default class Graph {
    constructor(auth) {
        this.auth = auth;
        this.apiUrl = apiUrl;
        this.dataGraphId = dataGraphId;
    }

    async get(req, entity, params) {
        const token = this.auth.getToken(req);
        const url = `${this.apiUrl}/${this.dataGraphId}/${entity}${params ? `?${params}` : ""}`;
        console.log(url) //for debugging 
        const options = {
            method: "get",
            headers: {
                "Authorization": `Bearer ${token}`,
                "Accept": "application/json"
            }
        };
        const response = await fetch(url, options);
        console.log(`${response.status} (${response.statusText})`) // for debugging 
        const json = await response.json();
        return json;
    }
}

You can see that we made two small changes. The Graph URL is now determined from the credentials of the specific business data graph, and the authorization token, obtained during user authentication, is passed to Graph. You may have to modify the business data graph identifier string from “v1” in the above code, before saving the file.

helloQuotes.js

Now are we finally ready to build the rudimentary basics of a classical three-page enterprise extension web app: a list-details-navigate application. This is what it will eventually look like:

Don’t expect fancy code, with all the necessary error and exception handling of a robust, production-ready application. Our goal is to show how easy it is to just create small business applications using Graph; we will discuss the finer aspects of robust Graph clients in another part of this tutorial.

We will first establish the skeleton of our application, in a file we will call helloQuotes.js:

// Hello Quote - our first SAP Graph extension app 
import express from 'express';
import Graph from './graph.js';
import Auth from './auth.js';
const app = express();
const port = 3003;
const auth = new Auth();
app.use(auth.getMiddleware());
const graph = new Graph(auth);
// ------------------    1) get and display a list of SalesQuotes   ------------------ 
// ------------------    2) show one quote and its items   ------------------  
// ------------------    3) navigate to the product details for all the items in the quote   ------------------  
app.listen(port, () => {
    console.log(`Example app listening at http://localhost:${port}`)
});

This code doesn’t do anything interesting. It basically logs in the user, using the standard authentication that we just discussed, and then listens on port 3003 for web (REST) requests. To make the code work, we need to install request handlers.

Using the express framework, we now create three such handlers, corresponding to three different expected URLs:

The root (/)

Request for a quote: /quote/…

Request for a quote’s product details: /quote… /product

Here is the first request handler:

// ------------------    1) get and display a list of SalesQuotes   ------------------  
app.get('/', async (req, res) => {
    const quotes = await graph.get(req, "sap.graph/SalesQuote", "$top=20");
    const qlist = quotes.value.map(q => `(${q.netAmount} ${q.netAmountCurrency})`).join("");
    res.send(` <h1>Hello Quotes</h1> ${qlist} `);
});

The handler will be fired if the browser requests the root document (“/”). What does the code do? It fetches the first 20 quotes (sap.graph/SalesQuote), and then wraps the resulting information (date and total amount) in HTML, and returns it.

Go ahead, paste this handler into the app skeleton, save, and run the server-side app on your terminal console as follows:

node helloQuotes.js

Open a new browser tab and enter the URL http://localhost:3003. If all went well, you will now see a list of dates and corresponding amounts in the browser.

That was nice, but not very interesting. To turn your app into an interesting list-details app, modify the qlist assignment above to introduce a link, as follows:

const qlist = quotes.value.map(q => `<p> <a href="/quote/${q.id}">${q.pricingDate} </a> 
(${q.netAmount} ${q.netAmountCurrency}) </p>`).join("");

Now, when the user clicks on one of the quotes, your app will be called again, and this time the URL will match ‘/quote…’.

Let us now also introduce our second and third handlers:

// ------------------ 2) show one quote and its items ------------------ 
app.get('/quote/:id', async (req, res) => { 
    const id = req.params.id; 
    const singleQuote = await graph.get(req, `sap.graph/SalesQuote/${id}`, "$expand=items&$select=items"); 
    const allItemLinks = singleQuote.items.map(item => `<p><a href="/quote/${id}/item/${item.itemId}"><button>Product details for item ${item.itemId}: ${item.product}</button></a></p>`).join(""); 
    res.send(` 
      <h1>SalesQuote - Detail</h1> 
      <h4><code>id: ${id}</code></h4> 
      ${allItemLinks} 
    `); 
}); 
// ------------------ 3) navigate to the product details for an item in the quote ------------------ 
app.get('/quote/:id/item/:itemId', async (req, res) => { 
    const id = req.params.id; 
    const itemId = req.params.itemId;
    const product = await graph.get(req, `sap.graph/SalesQuote/${id}/items/${itemId}/_product`, "$expand=distributionChains"); 
    res.send(` 
      <h1>Product Detail</h1> 
      <h4><code>For SalesQuote ${id} and item ${itemId}</code></h4> 
      <pre><code>${JSON.stringify(product, null, 2)}</code></pre> 
    `); 
});

The OData query at the heart of the second handler uses the $expand query parameter to fetch the details of the quote, including what was quoted (items). The product id in the quote is then used in the third handler to navigate across the business graph, to fetch the detailed product information from the product catalog. In both cases, the data is just dumped to the screen as JSON, but evidently, a real app would format the information much more nicely.

Go ahead, make the change in the first handler, and then paste the second and third handlers in your code, save the file, restart the service, and refresh the localhost:3003 page in the browser. Voila! Your app is live.

Note again, how you, as a developer, never had to ask yourself where the data came from. You just navigated from a quote object to a product object, without any effort. The landscape that you accessed via the configured business data graph may have managed quotes in SAP Sales Cloud, or in SAP S/4HANA, and the product catalog may have been, theoretically, in yet another system. You simply don’t have to care.

—————————————————————————————————————————

Leonid Gunko, Developer – Graph in SAP Integration Suite

Learn more about Graph in the SAP Community

API Composition with Graph: customizing your Business Data Graphs with Model Extensions

2024-03-15T13:43:13.362000+01:00

Hello!

in this part of the tutorial series we will have a look at how to use Graph for composing APIs and customizing business data graphs with model extensions. We will walk through an example of how to create a custom entity with a custom association.

For an overview of other parts of this series, check out the Information Map.

---

API Composition helps organizations to customize their API surface and combine multiple data sources into a single unified API. With Graph, as part of SAP Integration Suite, API administrators can create a single API using a customized connected graph data model either for their whole landscape or for specialized use cases.

API administrators can customize Business Data Graphs with the help of Model Extensions. These are packages that define several Custom Entities. All customizations in Graph are virtual: custom entity definitions are projections using mirrored entities as sources. Custom entities can have one or multiple source entities from possibly different data sources.

Example Scenario

In this blog we will walk through an example of composing and customizing an API from two separate services. An SAP S/4HANA Service and a service based on a custom CAP extension. Here is an overview of the example scenario:

Example scenario diagram

We will compose a demo.FrequentFlyer Custom Entity out of two sources: the sap.s4.A_BusinessPartner from an SAP S/4HANA data source and a my.custom.LoyaltyAccount entity from a custom CAP Extension on BTP. In addition, we will model an association from the custom entity demo.FrequentFlyer to the my.custom.LoyaltyStatus mirrored entity from the custom CAP Extension.

Example Setup

In this example we will be using the SAP S/4HANA sandbox provided on SAP Business Accelerator Hub and a simple CAP Extension service which we will be deploying in Cloud Foundry. The following steps will guide you through the required setup.

(1) Setting up Graph and SAP Integration Suite

First we need a BTP subaccount with an SAP Integration Suite instance with Graph activated. Follow the steps outlined in this previous blog post if you have not done so already. As a result you have a running SAP Integration Suite instance with Graph.

(2) Setting up the SAP S/4HANA Sandbox Destination

For demo data we will be using the SAP S/4HANA BusinessPartner sandbox service available on SAP Business Accelerator Hub. Create a destination named demo-s4-bupa in your BTP subaccount for this service with the following URL:

https://sandbox.api.sap.com/s4hanacloud/sap/opu/odata/sap/API_BUSINESS_PARTNER

You will also have to configure an API key for sandbox access as described in this previous blog post.

(3) Setting up the demo CAP Extension Service Destination

For the custom extension service, we will be deploying a small CAP-service in Cloud Foundry for demo purposes. We prepared this service here. Note that this example is only for demo puposes and would not fulfill requirements for any productive use cases.

To deploy the example CAP-service, make sure your BTP subaccount has the Cloud Foundry runtime enabled and a Cloud Foundry space exists (see also this tutorial). Note that this minimal demo service only serves a few example records and does not require a database.

Clone the example service repository and copy the contents of .cdsrc.json.template to a new file .cdsrc.json and add a password for the configured Basic Authentication. In this demo we use Basic Authentication, to learn more about authenticating against Graph see here.

git clone https://github.com/SAP-samples/graph-example-apps.git
cd graph-example-apps/blog-series/API-composition/graph-demo-service
cp .cdsrc.json.template .cdsrc.json

Make sure you have installed the prerequisites (Node.js, CAP, MBT) listed here. Then install and build the project:

npm ci
npm run build

Next, deploy the service, for example using the Cloud Foundry CLI (see also here)

cf login --sso
cf deploy gen/mta.tar

After the deployment is finished you can access the example Loyalty service under <CF-application-route-URL>/graph-demo/.

Finally, we need to create a BTP destination for this service. In the BTP Cockpit under Connectivity > Destinations create a new Destination demo-loyalty with the following URL: <CF-application-route-URL>/graph-demo/ (<CF-application-route-URL> depends on your Cloud Foundry deployment). Select "BasicAuthentication" for Authentication and add the user name and password you previously configured.

(4) Preparing a Business Data Graph for the Example Scenario

Now that we have created two destinations with our demo services, we can create a business data graph which we will extend with a model extension in the next section. In SAP Integration Suite open Design > Graph and create a new business data graph demo-bdg. Select the two destinations demo-s4-bupa and demo-loyalty. Leave the model extension input empty for now, this is what we are about to create. Activate the BDG in the final step. By default, Graph will use the namespace my.custom for destinations with services of unknown type, such as demo-loyalty in this case. When the business data graph is active we can start to model an extension for it.

Custom Entity Modeling

Graph allows to customize business data graphs with model extensions. A model extension is a package that contains one or more custom entity definitions. To customize a business data graph, we create a new model extension for it and then add it to the BDG configuration.

Start in SAP Integration Suite under Design > Graph and open the Model Extensions tab. Create a new model extension called demo-extension and select the demo-bdg as modeling metadata BDG (this is only for retrieving metadata while modeling, the extension itself is independent).

No Model Extensions exist

Create a new Model Extension dialog

Creating a Custom Entity

We will now create our custom entity demo.FrequentFlyer by composing it from two source entities. In the dialog select sap.s4.A_BusinessPartner as the main source entity. This is the entity that defines the identity of data-objects and is the source of the primary key for our custom entity. Then add my.custom.LoyaltyAccount as an additional source entity. Here, we need to define the join condition that defines how data objects from both entities are matched. For that we select which attributes from both entities are matching. When the complete primary key of the additional source attribute is matched, Graph infers that there exists a cardinality-relationship of 0 or 1 between the data objects of both entities, as is the case in our example.

In the other case where only a partial primary key is matched, a many-cardinality will be assumed. In that case, for each data object of the main source entity there could be any number of additional source data objects. Graph will treat that case as a composition, where an entity contains an array of sub-entities.

With the source entities defined, we continue by selecting which attributes of each source we want to project into our custom entity demo.FrequentFlyer. Here, we select the primary key attribute BusinessPartner of our main source entity in addition to other attributes from both sources (see below). Graph will suggest new names according to the Graph attribute naming best practices. Having selected some attributes we finalize the dialog via Create. We can then open our newly created custom entity and continue modeling the details.

Empty Model Extension

Custom Entity creation dialog

Source entities definition step

Additional source entity definition

Main source attribute selection

Additional source attribute selection

Model Extension with the newly created Custom Entity

Custom Entity attributes

Applying Transform Functions

When defining custom entities, graph allows to apply transform functions as part of the definition. When adding attributes from a source entity to the custom entity this is plainly called a rename transform (as was done in the entity creation dialog).

In our example, we want to change our data model and invert the boolean source attribute isMarkedForArchiving, which denotes whether an object was archived, and instead call the inverse isActive. For that we use the negation transform. We select the isMarkedForArchiving attribute and change the transform in the right-side panel to negation, rename the attribute and apply our changes.

Details of the applied negation transform

Adding a new Association

Graph allows to customize the graph structure of a business data graph with the help of custom associations in custom entities. For example, foreign-key relationships that are present in mirrored entities, can be converted into semantic associations between custom entities.

In our example, the additional source entity my.custom.LoyaltyAccount has an atttribute loyaltyProgramStatusId that references my.custom.LoyaltyStatus data objects by their ID. We turn this foreign-key relationship into an association as follows: in the dialog under Add > Association select the type of association. Here, it is a to-one association, as each LoyaltyAccount references only one LoyaltyStatus via ID.

Next, select the target of the association: my.custom.LoyaltyStatus. Graph will suggest a name according to the Graph modeling best practices.

Then define how these two entities are related by matching attributes from the source entity (foreign key) to the primary key attributes of the target entity. In our example we only map the LoyaltyAccount attribute loyaltyProgramStatusId to the single LoyaltyStatus key attribute statusId and then add the association to the custom entity.

This completes our example. Now we can apply the changes to our custom entity and save the extension.

Add Association dialog

Complete demo.FrequentFlyer Custom Entity definition

Applying the Model Extension to the Business Data Graph

Now that we have created a model extension for our example scenario with the demo.FrequentFlyer custom entity we want to see it in action. For that we will apply the model extension to a BDG.

Creating new BDGs with Model Extensions

With an existing model extension, we can simply create a new BDG and select the extension during the BDG-creation dialog. Graph will then generate a BDG configuration with locating policy rules for all custom entities.

Selecting an existing Model Extension during BDG creation

Adding Model Extensions to existing BDGs

Alternatively, we can also manually add a model extension to an existing BDG. Here we need to add the name of the extension to the top-level extensions array (see below), and add locating policy rules for all custom entities.

"extensions": [
    "demo-extension"
],

BDG configuration extensions snippet

In our example we add a single custom entity that is based on two source entities which requires two entries in the BDG locating policy rules, one for each source entity (see also here). Add the following snippet to the BDG configuration under locatingPolicy.rules (adapt the name of the leading data sources to match the ones in your BDG).

{
    "name": "demo.FrequentFlyer",
    "leading": "s4",
    "local": []
},
{
    "name": "demo.FrequentFlyer",
    "leading": "my.custom",
    "local": [],
    "sourceEntity": "my.custom.LoyaltyAccount"
}

BDG configuration locatingPolicy.rules snippet

Finally, we activate the BDG with the included model extension to try it out. Once the BDG was updated we can open the Graph Navigator in SAP API Business Hub Enterprise (see also this blog). There we can see that our updated demo-bdg now has a demo.FrequentFlyer entity with the schema we previously modeled. In the "Try Out" we can also see that we can follow the new _loyaltyStatus association via $expand or semantic navigation.

Custom Entity schema in Graph Navigator

Custom Entity Try Out in Graph Navigator

Summary

This small blog example illustrates how Graph can be used to compose APIs and customize the API surface with the help of a business data graph.

We used Graph to compose two different service APIs into a single connected business data graph: an SAP S/4HANA service and a custom CAP-extension service. We created a model extension containing a custom entity demo.FrequentFlyer with a custom association to another entity and a negation transform function.

To learn more about the full Graph modeling capabilities find the documentation here with more infomation on modeling topics such as all supported transform functions, creating compositions and adding to-many associations to your model.

Reference Materials

Find the full BDG configuration JSON and custom entity definition JSON files used in the example demo below.
Custom Entity definition JSON file:

{
  "entity": "demo.FrequentFlyer",
  "version": "1.0.0",
  "sourceEntities": [
    {
      "name": "sap.s4.A_BusinessPartner"
    },
    {
      "name": "my.custom.LoyaltyAccount",
      "join": [["BusinessPartner", "userId"]]
    }
  ],
  "attributes": [
    {
      "name": "id",
      "source": ["BusinessPartner"],
      "key": true
    },
    {
      "name": "businessPartnerFullName",
      "source": ["BusinessPartnerFullName"]
    },
    {
      "name": "loyaltyProgramName",
      "source": ["loyaltyProgramName"],
      "sourceEntity": "my.custom.LoyaltyAccount"
    },
    {
      "name": "loyaltyPoints",
      "source": ["loyaltyPoints"],
      "sourceEntity": "my.custom.LoyaltyAccount"
    },
    {
      "name": "isActive",
      "source": ["isMarkedForArchiving"],
      "sourceEntity": "my.custom.LoyaltyAccount",
      "transform": "negation",
      "type": "Boolean"
    },
    {
      "name": "_loyaltyStatus",
      "type": "Association",
      "associationTarget": "my.custom.LoyaltyStatus"
    },
    {
      "name": "_loyaltyStatus.statusId",
      "source": ["loyaltyProgramStatusId"],
      "sourceEntity": "my.custom.LoyaltyAccount"
    }
  ],
  "annotations": {
    "description": "",
    "readonly": false
  }
}

BDG configuration JSON:

{
  "businessDataGraphIdentifier": "demo-bdg",
  "graphModelVersion": "^v3",
  "schemaVersion": "1.2.1",
  "dataSources": [
    {
      "name": "my.custom",
      "services": [
        {
          "destinationName": "demo-loyalty",
          "path": ""
        }
      ],
      "namespace": "my.custom"
    },
    {
      "name": "s4",
      "services": [
        {
          "destinationName": "demo-s4-bupa",
          "path": ""
        }
      ],
      "namespace": null
    }
  ],
  "locatingPolicy": {
    "cues": [],
    "rules": [
      {
        "name": "sap.s4.*",
        "leading": "s4",
        "local": [],
        "cues": [],
        "sourceEntity": null
      },
      {
        "name": "sap.graph.*",
        "leading": "s4",
        "local": [],
        "cues": [],
        "sourceEntity": null
      },
      {
        "name": "my.custom.*",
        "leading": "my.custom",
        "local": [],
        "cues": [],
        "sourceEntity": null
      },
      {
        "name": "demo.FrequentFlyer",
        "leading": "s4",
        "local": [],
        "cues": [],
        "sourceEntity": null
      },
      {
        "name": "demo.FrequentFlyer",
        "leading": "my.custom",
        "local": [],
        "sourceEntity": "my.custom.LoyaltyAccount",
        "cues": []
      }
    ],
    "description": "",
    "keyMapping": []
  },
  "effectiveGraphModelVersion": "3.1.0",
  "description": "",
  "exclude": [],
  "extensions": ["demo-extension"]
}

---

Florian Moritz

Graph intro series, part 9: Use Graph With GraphQL

2024-03-17T04:30:00.031000+01:00

GraphQL

GraphQL is a query language for APIs that provides a type system to describe the data model in a structured way. It provides a strongly typed schema to describe the data model of an API in a structured way. Additionally, clients of an API use the query language to describe the data they want to request. GraphQL is similar to OData because they both provide a structured, typed schema for APIs and also enable clients to write powerful queries to request exactly the data they need using a single request.

The GraphQL adapter builds on the same metadata as the OData adapter.

Tutorial Setup

To keep things simple, we will be using the Graph sandbox endpoint. All you need to use this endpoint is your favorite GraphQL tool, for example the Altair GraphQL client, and your API key from SAP API Hub. To retrieve your API key, log into SAP API Business Hub, go to settings and copy your API key from the Show API Key button.

To make requests against the Graph sandbox, add your API key as an HTTP header in your requests: apiKey: <your API key>. Then you can use the Graph sandbox through the following endpoint:

https://sandbox.api.sap.com/sapgraph/graphql

Tutorial Specific Settings

Usually, GraphQL requests are done using POST requests. But, the sandbox is limited to GET requests, so we need to do GET requests for this tutorial. For most GraphQL clients this is just a setting and we are not creating too large request. A productive Graph instance is able to receive POST requests.

The API key is just used for the purposes of this sandbox endpoint and not relevant in the context of requests to productive Graph instances.

Also note that the URL of the Graph sandbox differs from the a productive URL of Graph.

Exploring the Schema

Every GraphQL service defines a schema that completely describes the set of types you can use for querying that service. GraphQL allows asking about what queries it supports using the introspection system.

Most GraphQL clients automatically load and scan the complete schema automatically, so you might not need to do that on your own and use the client to explore the schema.

To see what types are available, you can query the __schema field:

{
  __schema {
    types {
      name
    }
  }
}

This will return all service specific and build-in types of the service:

{
  "data": {
    "__schema": {
      "types": [
        {
          "name": "Query"
        },
        {
          "name": "sap_c4c"
        },
        {
          "name": "sap_c4c_BusinessAttributeCollection_connection"
        },
        {
          "name": "sap_c4c_BusinessAttributeCollection"
        }
        ...
      ]
    }
  }
}

To get more information for a specific type, you can either extend the query above or do a separate query for the __type field. If you introspect the Query with

{
  __type(name: "Query"){
    name
    fields {
      name
    }
  }
}

you get all namespaces. These include Graph's build-in namespaces as well as user-defined custom namespaces for custom entities.

{
  "data": {
    "__type": {
      "name": "Query",
      "fields": [
        { "name": "sap_c4c" },
        { "name": "sap_graph" },
        { "name": "sap_hcm" },
        { "name": "sap_s4 "}
      ]
    }
  }
}

You can use a similar query to get the list of entities in a namespace, by using the namespace instead "Query" as the name.

To get more information in a single request, you can extend the query, for example to get all fields of sap_graph_SalesQuote with their name and kind, you simply query this:

{
  __type(name: "sap_graph_SalesQuote"){
    name
    fields {
      name
      type {
        name
        kind
      }
    }
  }
}

returning all available properties of the sap_graph_SalesQuote:

{
  "data": {
    "__type": {
      "name": "sap_graph_SalesQuote",
      "fields": [
        {"name": "id", "type": {"name": "String", "kind": "SCALAR"}},
        {"name": "createdAt", "type": {"name": "DateTime", "kind": "SCALAR"}},
        {"name": "changedAt", "type": {"name": "DateTime", "kind": "SCALAR"}},
        {"name": "displayId", "type": {"name": "String", "kind": "SCALAR"}},
        {"name": "netAmount", "type": {"name": "Decimal", "kind": "SCALAR"}},
        {"name": "quoteType", "type": {"name": "String", "kind": "SCALAR"}},
        {"name": "soldToParty", "type": {"name": "String", "kind": "SCALAR"}},
        {"name": "_soldToParty", "type": {"name": "sap_graph_SalesDocumentReason", "kind": "OBJECT"}},
        {"name": "_soldToParty_id", "type": {"name": "String", "kind": "SCALAR"}},
        {"name": "items", "type": {"name": "sap_graph_SalesQuote_items_connection", "kind": "OBJECT"}},
        ...
      ]
    }
  }
}

We can see that a SalesQuote has several properties of different types, such as String or Decimal, but also more complex structured types like the items property, which is a collection of several sap_graph_SalesQuote_items, that are also defined in the same data model. The _connection types allow for retrieving data of entities of a to-many relation.

{
  "data": {
    "__type": {
      "name": "sap_graph_SalesQuote_items_connection",
      "fields": [
        {"name": "nodes", "type": {"name": null, "kind": "LIST", "ofType": {"name": "sap_graph_SalesQuote_items"}}},
        {"name": "totalCount", "type": {"name": "Int", "kind": "SCALAR", "ofType": null}}
      ]
    }
  }
}

Simple Example

Let us look at an example. We want to get a SalesQuote. For that, we create the following GraphQL request:

{
  sap_graph {
    SalesQuote (top: 1){
      nodes {
        id
        displayId
        netAmount
      }
    }
  }
}

In GraphQL, you always specify exactly what fields you would like to receive. In the example request above we selected the id, displayId and the netAmount of the SalesQuote. To make the query fast and have an easy to read result, we have added (top: 1) to get only one SalesQuote.

{
  "data": {
    "sap_graph": {
      "SalesQuote": {
        "nodes": [
          {
            "id": "c4c~1",
            "displayId": "1",
            "netAmount": "890"
          }
        ]
      }
    }
  }
}

Example With Nesting

We now want to get the items and the soldToParty of that SalesQuote as well, so we simply add these attributes to the query with the fields we would like to see.

Note that the attributes of the items attribute are encapsulated with nodes like it is done with the attributes of the SalesQuote as well. This has to be done for all list types. _soldToParty is a to-one association, so here the attributes are directly. The reason for this extra level is so that you can get the total amount of elements next to the actual elements of the list like here for the SalesQuote:

{
  sap_graph {
    SalesQuote (top: 1){
      totalCount
      nodes {
        id
        displayId
        netAmount
        _soldToParty {
          id
          name
        }
        items {
          nodes {
            itemId
            itemText
            product
            quantity
          }
        }
      }
    }
  }
}

This will result in the items of the SalesQuote and the associated soldToParty being returned. The total count of found SalesQuotes is now available as well:

{
  "data": {
    "sap_graph": {
      "SalesQuote": {
        "totalCount": 135,
        "nodes": [
          {
            "id": "c4c~1",
            "displayId": "1",
            "netAmount": "890",
            "_soldToParty": {
              "id": "c4c~10014",
              "name": "System Tec"
            },
            "items": {
              "nodes": [
                {
                  "itemId": "10",
                  "itemText": "Green Emission Calculator",
                  "product": "P300100",
                  "quantity": "1"
                }
              ]
            }
          }
        ]
      }
    }
  }
}

Working with collections: filtering, ordering and pagination

When working with collections of entities, we typically want to filter the entities by some criteria or arrange them in a specific order. In Graph's GraphQL schema this is supported via the filter and order arguments.

Let us continue with our example above. Say, we want to retrieve all SalesQuotes with a value greater than 100 U.S. Dollars. The value condition can be formulated with the filter rule netAmount: {ge: 100}. For the currency condition we need to compare it with a string for equality: netAmountCurrency: {eq: "USD"}. Filter rules that are in one filter object are combined with logical conjunction (and). If you want to combine rules with logical disjunction (or), you would pass multiple filters as a list in the filter argument.

In addition, we define an ascending ordering on the netAmount property: orderBy: {netAmount: asc}.

With top and skip we can additionally define a sliding window over the result to implement pagination. top specifies how many result entities should be returned: the page size. How many result entities should be skipped from the beginning of the ordering is defined with the skip argument.

{
  sap_graph {
    SalesQuote (
      top: 5,
      skip: 5,
      orderBy: {netAmount: asc},
      filter: {
        netAmount: {ge: 100},
        netAmountCurrency: {eq: "USD"}
      }
    ){
      totalCount
      nodes {
        id
        netAmount
        netAmountCurrency
      }
    }
  }
}

Summary

In this tutorial we had a look at using Graph with GraphQL. We covered all the features that you as a developer working with Graph need to know, like how to:

inspect the schema and structure of the business data graph
formulate complex queries
work with collections

GraphQL itself offers much more than what we showed in this tutorial. You can read more about it in the the GraphQL documentation and the Graph documentation .

You as a developer now have a second data protocol option you can use with Graph. The structure of all entities in the business data graph is exactly the same as if you access Graph with the OData protocol. You have one API to retrieve data in one unified format, no matter the source system.

________________________________________________________________
Alexander Hoffert, Senior Developer – Graph

Visit Graph on the SAP Community

Graph intro series, part 8: Use Graph With OData v4

2024-03-19T14:21:24.058000+01:00

What you will learn: use OData v4 to fetch data and explore the structure of the connected data model exposed by Graph.

Hello!

In this part of the tutorial on Graph we will focus on the OData protocol that Graph exposes and how to explore the structure of the data model of a business data graph. OData is one of the two data protocols supported by Graph - next to GraphQL.

For an overview of other parts of this series, check out the Information Map.

Graph is built on open standards and technologies. Clients can communicate with Graph using the Open Data v4 Protocol (OData). This is a standardized RESTful HTTP protocol with defined semantics that help promote interoperability between services.

OData is centered around resources (data entities), which are identified by URLs. In Graph, there are for example the Customer, Product, or SalesQuote entities. The structure of these entities is defined in an Entity Data Model (EDM) which can be inspected by clients. OData provides many operations to filter or search in entity collections, to navigate between associated entities and to adapt the response shape.

We will now look at examples on how to formulate OData requests for Graph.

Tutorial Setup

To keep things simple, we will be using the Graph sandbox business data graph (BDG). All you need to use it is your favorite HTTP tool, for example Postman, and your API key from SAP Business Accelerator Hub. To retrieve your API key, log into SAP Business Accelerator Hub, go to settings and copy your API key from the Show API Key button.

To make requests against the Graph sandbox BDG, add your API key as an HTTP header in your requests:
apiKey: <your API key>

Then you can use the Graph sandbox BDG through the following endpoint:

https://sandbox.api.sap.com/sapgraph/

Note: The API key is just used for the purposes of this sandbox endpoint and not relevant in the context of OData requests or productive Graph instances.

Exploring the OData data model

OData defines an Entity Data Model that describes the structure of all known entities. This helps developers and clients alike to reason about the available entities and their structure. The data model and further metadata can be inspected through a special $metadata resource. Graph makes metadata available for each namespace, such as sap.graph for the unified Graph data model.

To retrieve the metadata of the unified data model in Graph, make the following request, which will return an EDMX specification (an XML dialect for describing OData Entity Data Models).

https://sandbox.api.sap.com/sapgraph/sap.graph/$metadata

In the response, we can inspect the structure of all the entities (and sub-entities) that are described as EntityType entries as well as other metadata. Let's have a closer look at the definition of the SalesQuote entity type in this extract from the sales domain metadata:

<EntityType Name="SalesQuote">
    <Key>
        <PropertyRef Name="id"/>
    </Key>
    <Property Name="id" Type="Edm.String" MaxLength="82" Nullable="false"/>
    <Property Name="displayId" Type="Edm.String"/>
    <Property Name="netAmount" Type="Edm.Decimal" Scale="6" Precision="22"/>
    <Property Name="pricingDate" Type="Edm.DateTimeOffset"/>
    <Property Name="netAmountCurrency" Type="Edm.String" MaxLength="5"/>
    <NavigationProperty Name="_netAmountCurrency" Type="sap.graph.Currency"/>
    <NavigationProperty Name="items" Type="Collection(sap.graph.SalesQuote_items)" Partner="up_" ContainsTarget="true"/>
    <Property Name="soldToParty" Type="Edm.String" MaxLength="10"/>
    <NavigationProperty Name="_soldToParty" Type="sap.graph.Customer"/>
    <NavigationProperty Name="_cxsales" Type="sap.cxsales.SalesQuoteCollection"/>
    ...
</EntityType>

We can see that a SalesQuote has several properties of different types, such as String or Decimal, but also more complex structured types like the items property, which is a collection of several sap.graph.SalesQuote_items, that are also defined in the same data model. Furthermore, we see that the id property is referenced as key for this entity type. Navigation Properties allow for navigation to a related entity. The items property is a navigation property because the sap.graph.SalesQuote_items is modeled as a separate entity type in the metadata.

Let's look at an example. Add the following query path to the sandbox endpoint to make the request. This will retrieve one SalesQuote entity (here we add $top=1 to limit the result set to one entity):

/sap.graph/SalesQuote?$top=1

From inspecting the metadata, we have learned that SalesQuotes have items, however when comparing with the response from the example, no items are included in the response.

The reason for this is that OData has a mechanism for the client to control which navigation properties are included as part of the response. This is called expanding a property. By default, Graph returns responses non-expanded if not specified by the client. In addition to expanding the response, OData also allows for restricting it to requested values only. We will have a look at these mechanisms next.

Expanding and restricting the response

OData allows clients to adapt the response format in two ways. Clients can restrict the response to a set of specified properties via $select. And they can expand the response by including referenced entities inline as part of the response via $expand.

If we only require the netAmount of a SalesQuote, we can restrict the response by adding it to the $select query parameter:

/sap.graph/SalesQuote?$top=1&$select=netAmount

This will return only the netAmount property along with the id, as it is the key attribute and therefore always included.

If we also require the items of a SalesQuote, we need to expand the response (as it is a navigation property) by adding it to the $expand query parameter:

/sap.graph/SalesQuote?$top=1&$select=netAmount&$expand=items

This will result in the items array being returned as part of the SalesQuote response as illustrated here:

If we have a look at a response snippet, this is what is being returned:

{
    "@odata.context": "$metadata#SalesQuote(netAmount,id,items())",
    "value": [
        {
            "id": "cxsales~1",
            "netAmount": 890,
            "items": [
                {
                    "itemId": "10",
                    "parentItemId": "",
                    "alternativeToItemId": "",
                    "itemCategory": "AGN",
                    "itemText": "Green Emission Calculator",
                    "product": "P300100",
                    "soldToPartyProductId": "",
                    "quantity": 1,
                    "quantityUnit": "EA",
                    "grossWeight": 0,
                    "grossWeightUnit": "",
                    "netWeight": 0,
                    "netWeightUnit": "",
                    "volume": 0,
                    "volumeUnit": "",
                    "plant": "",
                    "netAmount": 890,
                    "netAmountCurrency": "USD",
                    "pricingProduct": "",
                    "incotermsClassification": "",
                    "incotermsLocation": "",
                    "processingStatus": "1",
                    "cancellationReason": ""
                }
            ]
        }
    ]
}

Note that we do not have to specify expanded properties explicitly as part of $select.

We see that the item in the example above has a property product that references an id. When we inspect the metadata of the items by searching for the EntityType SalesQuote_items. We see that the product property represents the referenced product with a string value and the _product navigation property references the connected sap.graph.Product entity.

<EntityType Name="SalesQuote_items">
    <Key>
        <PropertyRef Name="itemId"/>
    </Key>
    <Property Name="itemId" Type="Edm.String" MaxLength="10" Nullable="false"/>
    <Property Name="itemText" Type="Edm.String"/>
    <Property Name="product" Type="Edm.String"/>
    <NavigationProperty Name="_product" Type="sap.graph.Product"/>
    ...
</EntityType>

To also include this _product as part of the response, we can expand it inside the already expanded items: a nested expand.

/sap.graph/SalesQuote?$top=1&$select=netAmount&$expand=items($expand=_product)

Which will include the _product response inline in the item of the SalesQuote response.

If we also want to adapt the format of the expanded product we can nest a $select query parameter in parentheses after the product. To restrict the nested product to the displayId, for example:

/sap.graph/SalesQuote?$top=1&$select=netAmount&$expand=items($expand=_product($select=displayId))

If we also want to select more properties, such as netAmountCurrency, we can just add them to the $select query parameter targeting the SalesQuote, separated by commas:

/sap.graph/SalesQuote?$top=1&$select=netAmount,netAmountCurrency&$expand=items($expand=_product($select=displayId))

The response for the SalesQuote with included netAmountCurrency, items and _product now looks like this:

{
    "@odata.context": "$metadata#SalesQuote(netAmount,netAmountCurrency,id,items(_product(displayId,id)))",
    "value": [
        {
            "id": "cxsales~1",
            "netAmount": 890,
            "netAmountCurrency": "USD",
            "items": [
                {
                    "itemId": "10",
                    "parentItemId": "",
                    "alternativeToItemId": "",
                    "itemCategory": "AGN",
                    "itemText": "Green Emission Calculator",
                    "product": "P300100",
                    "_product": {
                        "id": "cxsales~P300100",
                        "displayId": null
                    },
                    "soldToPartyProductId": "",
                    "quantity": 1,
                    "quantityUnit": "EA",
                    "grossWeight": 0,
                    "grossWeightUnit": "",
                    "netWeight": 0,
                    "netWeightUnit": "",
                    "volume": 0,
                    "volumeUnit": "",
                    "plant": "",
                    "netAmount": 890,
                    "netAmountCurrency": "USD",
                    "pricingProduct": "",
                    "incotermsClassification": "",
                    "incotermsLocation": "",
                    "processingStatus": "1",
                    "cancellationReason": ""
                }
            ]
        }
    ]
}

Working with collections: filtering, ordering and pagination

When working with collections of entities, we typically want to filter the entities by some criteria or arrange them in a specific order. In OData this is supported via the $filter and $orderby query parameters. With $top and $skip we can additionally define a sliding window over the result to implement pagination.

To continue with our example above, let's remove the $top=1 we added initially to now retrieve a collection of SalesQuotes. Say we want to retrieve all SalesQuotes with a value greater than 100 U.S. Dollars.

The value condition can be formulated with the greater equal operator: netAmount ge 100. For the currency condition we need to compare it with a string (enclosed in single quotes) for equality: netAmountCurrency eq 'USD'. We then combine these conditions with a logical and expression and add it to the example query below. We also define an ordering on the netAmount property with the $orderby query parameter, which is ascending by default.

Note: OData operators are lower-case and space-separated. This requires URL encoding. If you are using Postman for this tutorial you don't need to worry as Postman automatically applies URL encoding.

/sap.graph/SalesQuote?$select=netAmount,netAmountCurrency&$expand=items($expand=_product($select=displayId))&$filter=netAmount ge 100 and netAmountCurrency eq 'USD'&$orderby=netAmount

Note: OData only supports writing filter expressions using a small vocabulary of filter operators. See here for a full list.

As a last step, we will now define a paging-window over all results. This can be achieved with the query parameters $top, which specifies how many result entities should be returned: the page size, and $skip, which defines how many result entities should be skipped from the beginning of the ordering. Hence, we describe the page size with $top and index the single pages with multiples of the page size in $skip. For the second page of five entities each, this would translate to our example as follows:

/sap.graph/SalesQuote?$select=netAmount,netAmountCurrency&$expand=items($expand=_product($select=displayId))&$filter=netAmount ge 100 and netAmountCurrency eq 'USD'&$orderby=netAmount&$top=5&$skip=5

Summary

In this tutorial we had a look at OData, one of the two data protocols used by Graph. We covered all the features that you as a developer working with Graph need to know, like how to:

formulate complex queries
inspect the metadata and structure of the unified data model
expand and restrict responses
work with collections

OData itself offers much more than what we showed in this tutorial. You can read more about it in the standard.

With Graph, you as a developer now have one data protocol you can use together with one API to retrieve data in one unified format, no matter the source system.

---
Florian Moritz

Creating a dynamic graph to use as an SPC chart purposes

2024-03-26T20:23:31.719000+01:00

In this project, we aimed to create a dynamic graph to use as an SPC Chart, ["Fig. 1."]. In order to achieve this, we created a custom plugin to view the graph from the POD, custom tables in a cloud database to feed data to the graph, the process to add data to the database and create scenario-based actions, tags to read data from the shop-floor, and a subscription.

["Figure 1- Overall Graph View"]

Details & Design of the Development

In our scenario, there will be five random measurements values at the first operation of an order. Our main process is triggered by the input fed by the tag in the form of an (sfc,value) structure, when related tag value changed, it is catched by the subscription created via the Automatic Trigger App, and this subscription triggers a spesific process. [“Fig. 2.”]

["Figure 2 - Main Process"]

Within the process, after separating this input into sfc and value, further information about the sfc, such as resources, is obtained using Retrieve Sfc Details Service.

After getting the SFC details there is a parallel condition to invoke both a second process [“Fig. 3.”] and a custom service that adds data to the 'z_spc_period' table ["Fig. 4."]. With the second process, we aimed to update the resource status as 'SCHEDULED_DOWN' and send a notification to a Teams Channel, when the value falls outside the maxOut and minOut limits. For the maxValue and minValue violations, we aimed to log a pre-defined Nc code, change the status of the SFC to 'HOLD' and send a notification to a Teams Channel with this process.

["Figure 3 - Second Process"]

["Figure 4 - z_spc_period Table"]

We created 3 graphs as; SPC, Average Value, Value Gap. When the custom plugin screen opened, the Average Graph is preselected. To facilitate ease of use, there are total of 5 filters that are same to all graph selections: Workcenter, Resource, Order, SFC, and Material. Average value graph gives the average of values for a completed period. Calculation is performed based on the values from the custom 'z_spc_period' table and the results are inserted in the 'z_spc_value' table at the cloud DB [Fig.5.], however the max. number of values that could be in a period can be changed from the process design that we create, by editing the maxDataNum value.

["Figure 5 - z_spc_value Table"]

SPC graph gives the value versus period ID graph based on a SFC. As this graph functions based on a SFC, SFC field at the filter section becomes mandatory. Graph also shows the maxValue&minValue limits, maxOut&minOut limits and for the points that exceeds those limits there is an NC logging option. To log an NC, user need to click on the desired data-point and the NC log button from the info box that is opened [“Fig. 6.”]. This button will lead to a pop-up NC Logging screen [“Fig. 7.”].

["Figure 6 - Info Box of Data Point"]

["Figure 7 - Custom NC Log Popup"]

Demo Video

If you like this post or have any questions, please let us know in the comments.
All questions are highly appreciated.

Dilahan Çiloğlu & Ege Aksöyek

Knowledge Graphs on Datasphere and HANA Cloud. The differences

2024-04-02T16:59:17.079000+02:00

The ability to enhance RAG with Vector search, Graph knowledge bases, or SQL Queries is fundamental. SAP recently announced the Datasphere capability to create Graphs, and there are some key differences between the graph capabilities in SAP HANA Cloud, the new announcement SAP Datasphere knowledge graph and the Intergation Suite capability called Graph:

1. SAP HANA Cloud has had a powerful graph engine for analyzing complex relationships in business data for a while now. It allows creating graph workspaces from existing tables/views, querying graphs using openCypher, writing custom graph algorithms, and visualizing graphs.

https://community.sap.com/t5/technology-blogs-by-sap/sap-hana-graph-resources/ba-p/13505490

https://www.youtube.com/watch?v=oaSQu9laYKE

2. Datasphere Creating knowledge graphs manually is very costly, so SAP Datasphere comes to help by automatically pre-populating them using content already available in SAP Datasphere like connections to source systems, tables, foreign keys etc. SAP Datasphere knowledge graph is a new capability announced in March 2024. As data is onboarded and integrated into SAP Datasphere, it automatically creates an ontology representing the relationships in the data, including business context from SAP sources like S/4HANA

caption by SAP. Currently in Preview

https://www.youtube.com/watch?v=PQrFjthwOWQ&t=169

https://news.sap.com/2024/03/future-of-data-driven-business-new-sap-datasphere-capabilities/

3. SAP Graph as an Integration Suite capability

Parallel to building Graphs from Databases, SAP Graph is an alternative unified API available on the SAP Business Technology Platform that provides access to a connected graph of SAP-managed business data, regardless of where the data resides.

SAP Graph is intended for building extension applications, such as workflow applications using low-code tools or event-driven applications, and it supports modern open standards like OData v4 and GraphQL

https://podcast.opensap.info/cloud-platform/2022/04/28/episode-82-sap-graph-the-easy-to-use-api-of-the-intelligent-enterprise/

https://community.sap.com/t5/technology-blogs-by-sap/graph-new-in-sap-integration-suite/ba-p/13555887

Conclusion

While the SAP HANA Cloud graph is more for custom graph algorithm development and analysis, the SAP Datasphere knowledge graph is an automated capability that provides a rich context for generative AI use cases by capturing complex data relationships and metadata. The two serve different but complementary purposes in the SAP data and analytics portfolio.

Additional information:
https://www.linkedin.com/pulse/how-use-sap-hana-cloud-graph-model-analyze-complex-your-holitschke

https://community.sap.com/t5/technology-blogs-by-sap/sap-hana-graph-resources/ba-p/13505490

https://community.sap.com/t5/technology-q-a/native-hana-vs-sap-datasphere-findings/qaq-p/12689997

https://www.techzine.eu/blogs/data-management/117331/sap-expands-datasphere-with-knowledge-graph-and...

https://community.sap.com/t5/technology-q-a/sap-datasphere-is-an-alternative-of-sap-hana-modelling-w...

https://community.sap.com/t5/technology-blogs-by-members/access-sap-hana-cloud-underneath-of-sap-dat...

https://developers.sap.com/group.hana-aa-graph-overview.html

Appraisal-Item categories in SAP SD

2024-10-10T14:52:02.844000+02:00

In SAP Sales and Distribution (SD), item categories play a crucial role in determining how sales documents are processed. Each item category controls various aspects of sales transactions, including pricing, billing, delivery, and inventory management. Here are some common item categories used in SAP SD:

1. **Standard Item (TAN)**:
- This is the most commonly used item category for selling products. It allows for pricing, delivery, and billing.

2. **Service Item (SERV)**:
- Used for services instead of goods. This category typically does not involve inventory management and is often tied to service contracts.

3. **Text Item (TXT)**:
- Used for non-billable items such as comments or notes. It does not affect pricing or inventory.

4. **Free of Charge Item (NORM)**:
- This item category is used for items provided at no charge, allowing for the processing of delivery and billing without affecting sales revenue.

5. **Subsequent Delivery (LUMF)**:
- Used for subsequent deliveries of previously sold items, often utilized in situations where partial deliveries occur.

6. **Consignment Item (CST1/CST2)**:
- These categories are used for consignment stock scenarios, where goods are stored at the customer’s location but remain owned by the supplier until sold.

7. **Returnable Packaging (VERP)**:
- Used for items that are returnable, such as crates or pallets. This item category helps manage inventory levels for packaging materials.

8. **Cash Sales Item (CS)**:
- Used in cash sales scenarios where the customer pays immediately, and the sales process is expedited.

9. **Intercompany Item (IV)**:
- Used for intercompany transactions between different entities within the same organization.

10. **Sales Order Item (OR)**:
- This category is used for processing orders that require specific handling or conditions.

Each item category has specific settings that influence the behavior of sales documents and the underlying logistics processes. The configuration of item categories can be customized to fit the specific needs of a business.

Please share your experience - new API Management survey

2024-11-28T12:08:40.807000+01:00

Dear @Pa_Vi Integration Customers,

We are always eager to learn more about how our customers interact with SAP Integration Suite.

In particular, we are interested in hearing how you use the API Management capability of SAP Integration Suite —or why you might not use it yet. Whether you’re an experienced API administrator, an integration specialist, or have never used API Management, we’d love to hear from you!

Your feedback helps shape the future of SAP Integration Suite and meet your needs better.

Who Should Participate?

✓ Current API Management users: Share how you're implementing and benefiting from the capability
✓ Customers not currently using API Management: Help us understand your reasons and challenges

Survey: Usage of API Management

Hugely appreciated! 🙂

--
Chaim Bendelac
Product Manager - SAP Integration Suite

Simplify connectivity to improve developer efficiency with the help of Enterprise Automation

2025-01-10T12:23:26.962000+01:00

co-authored by: @EvgeniyGorbunov

Hello everyone!

With Enterprise Automation with SAP, we bring together technologies such as SAP Signavio, SAP Integration Suite and SAP Build in order to provide a unified framework to address process analysis, automation and integration needs of an intelligent enterprise.

These technologies have multiple integration touchpoints and can be used together for the best benefit in a vast amount of use-cases.

You can find more detailed information about the Enterprise Automation with SAP here.

Practical need

In this blog post, I would like to focus on one specific usage pattern of the Enterprise Automation framework: how to ensure the developer efficiency while simplifying connectivity to underlying data sources. It is always better to explain such pattern with a practical scenario, so let us look into the manufacturing area as an example.

An organization wants a clear view of all maintenance orders and material reservations for the equipment maintenance. The bigger the company is, more the equipment it possesses – and it is vital to ensure the right maintenance timelines and see all the issues in a transparent way.

For this, the company needs to gather data from multiple sources and display it in a user interface. Later, the responsible person can review the information in a dashboard-like format and proceed with sending the relevant maintenance and repair orders.

How can they achieve their goal in a short time and with limited resources thanks to the Enterprise Automation capabilities?

How does it work?

Graph is a powerful enhancement to API Management, capability of SAP Integration Suite, which supports in transforming APIs. You can easily and securely provide your integration and application developers with selective, abstracted access to your enterprise data via a single, easy-to-use API. The enterprise data is semantically connected in the form of a business data graph.

To build the end user interface SAP Build Apps is being used. SAP Build Apps is a professional application development solution providing an intuitive no-code development environment to empower business users and developers to create apps quickly and visually.

Setup

You can setup business data graph in your subaccount, where identity, trust and connectivity can be established between your applications, extensions and integrations, and your landscape. An advantage of Graph is that IT Administrators take care of the Business Data Graph as well as the destination’s configuration, while developers just consume the entities via Graph independent of which specific tenants they are working with.

In our use case architecture, SAP Build Apps application consumes both SAP S/4 HANA Cloud entities Reservation and maintenance Order via Graph. User Identity is propagated from SAP Build Apps to Graph, and Graph will propagate the identity to each specific backend tenant to verify the end user authentication and authorization.

Developers only connect to the Graph destination configured by IT Administrators without having to care about changes on the specific backend servers’ configuration.

Creation of Graph custom entity

You can start by defining a custom entity using Graph Model extension editor in SAP Integration Suite. Reservation and maintenance order entities can be composed using the step-by-step business data graph extension wizard. The activated business data graph API will be binded to SAP build apps for further consumption.

Please refer the blog post to understand how a model extension is created.

Creating an app with SAP Build Apps

Create a web and mobile application in SAP Build apps as per the custom scenario by consuming the data from Graph unified API.

Once the Graph API is consumed, it makes it possible to execute queries by consuming data from multiple entities composed in Graph in a same UI Component.

Now that we are done with configurations and designing the UI for the scenario, our scenario would look like the one recorded in the video here.

Summary:

We saw how you can connect your applications using a unified API that abstracts underlying data sources using the Graph functionality of SAP Integration Suite. This way, you can consolidate the data, expose and easily reuse it in your application at the runtime.

But that is not all. We looked at an example with an application above. On top of that, we also face the need to have an abstraction layer to connect data to the process flow, created in SAP Build Process Automation. We can ensure API connectivity from the process using actions to encapsulate API calls, and by using Graph we can simplify this connectivity by having one unified layer underneath. If we put it in frame of a scenario above, if we need an additional approval step to coordinate, we can leverage SAP Build Apps, SAP Build Process Automation and Graph in one unified scenario.

Find more detailed information about the Enterprise Automation with SAP and how to get started in the blog post.

Find more information about Graph in SAP Integration Suite in this blog post series.

And use the community page of SAP Integration Suite for more information and exchange on the SAP Graph topic.

Supercharge efficiency with Enterprise Automation: SAP Build and SAP Integration Suite

2025-02-05T18:22:37.224000+01:00

The ability to intelligently automate business processes is top of mind for many stakeholders involved in process management across organizations. According to a recent IDC study, annual spending on Intelligent Process Automation (IPA) technologies is projected to reach $102 billion by 2028. Of this, $19.9 billion will be allocated to AI-powered automation tools, with an impressive annual growth rate of 43.4%.

While there will be certainly no shortage in resources to spend for automation software, the real challenge remains in the details: How can organizations implement a holistic approach for process excellence, which allows them to manage processes, identify bottlenecks, deliver scalable automations and integrate their process extension within a holistic process landscape. In my previous blogpost I have already outlined in detail how SAP’s framework on Enterprise Automation delivers an solution to the problem statement mentioned above.

And this blogpost series will offer you a more detailed guidance on the interconnectivity of each service included in Enterprise Automation which are:

SAP Build Process Automation
SAP Integration Suite
and of course SAP Signavio.

Let’s explore the value you can unlock for your processes by combining SAP Build Process Automation with SAP Integration Suite in this one.

What is Enterprise Automation?

As outlined in my previous blogpost Enterprise Automation with SAP: Enterprise automation with SAP software provides an integrated set of tools for process mining, automation, integration, monitoring, and optimization of your processes and workflows. It helps you quickly and intuitively gain insights into your business processes and identify the right automation tool for the right outcome. While each solution can be leveraged independently, Enterprise Automation offer native integration between SAP Build, SAP integration Suite and SAP Signavio – supplemented with best practices, guidance and pre-build content which can be implemented directly.

SAP Signavio provides visibility into business processes and potential bottlenecks, root-cause analysis, and suggestions for improvement based on 200,000 industry benchmarks and best practices. This detailed understanding of inefficiencies across your organization enables you to optimize and automate processes.
SAP Integration Suite is an integration platform as a service with thousands of prebuilt integrations, APIs, events and connectors to SAP and third-party software applications. The suite reduces complexity across on-premise and multi-cloud environments, helping you optimize comprehensive business processes.
SAP Build to create automations and applications usingthe low-code and no-code design tools. Including pre-built automations and connectors for SAP software and third-party systems, the solutions let your business experts rapidly address process inefficiencies

Here you can also see a visualization of the main components and its respective capabilities:

Leverage the combined power of SAP Build Process Automation and SAP Integration Suite

1st scenario: Integrate to innovate

The first scenario we are going to cover in this blogpost is about building required process extensions and integrating the to your systems of records. SAP Build Process Automation allows you to create entirely new business processes and automation from scratch. However, during development, you may need advanced integration capabilities and various types of connectors to link your processes with different systems, whether cloud-based or on-premise, and whether using SAP or third-party platforms.

Integration Suite, you can natively trigger an iFlow created in SAP Integration Suite at any point within your process definition. This is particularly useful when handling tasks like data transformation, entity mapping, field validation, or accessing over 250 connectors such as iDoc, SOAP, SMTP, Kafka, and more. Moreover, customers that start their process excellence journey with Integration Suite can complement their integration styles with additional automation capabilities like approval workflows, business rules or RPA bots that have been provisioned with SAP Build Process Automation.

Let’s jump into an example. In the screenshot below you can see a process definition within Build Process Automation to automate the creation of Purchase Requisitions within your organization:

Once all the parameters and required approvals are fulfilled, we want to create a PR document within our system of record. In the first Action of the screenshot below you can see that we are natively calling an OData service to directly push this new PR within our SAP S/4HANA on-premise system. But in the second Action, we trigger an additional Integration Flow (iFlow) that has been established within the SAP Integration Suite:

This is done rather quickly thanks to the ability to natively trigger an iFlow within the Action design-time of SAP Build Process Automation, which is also documented in our Help-Portal:

This allows you to include in iFlow within your process definition whenever it is necessary. Because in the iFlow design-time of the Integration Suite you can establish any scenario that is relevant, make use of data validation and entity mapping, and use more than 250 different connectors to integrate to any backend application. The connectivity options and adapters are also documented within the Help-Portal. In this screenshot you can see how the iFlow replicates the PR document in our MM-module of SAP ECC by using a SOAP adapter:

And here you can see an example how entity mapping looks like: We are mapping the corresponding data fields of the OData service to the SOAP service to make sure that no data gets lost or misinterpreted.

2nd scenario: Event-driven architectures

Another common use case for combining SAP Build and SAP Integration Suite is in the area of event-driven architectures. Thanks to the Event Mesh service available in SAP Integration Suite, you can listen to and subscribe to critical business events, whether they are happening within your SAP or non-SAP environment. This also includes the new Advanced Event Mesh service, which offers more capabilities, broader deployment options, and the ability to handle larger payloads compared to the regular Event Mesh service.

SAP Build provides native connectivity to both Event Mesh and Advanced Event Mesh, enabling you to proactively trigger process instances without human intervention, based on business events as they occur.

For instance, you can use Advanced Event Mesh to listen for and subscribe to the creation of business partners within your S/4HANA system, as well as in third-party systems. Whenever a new business partner is created, SAP Build triggers a process instance to validate the data, sending approval notifications to business users to assign addresses and payment information for the new business partner, ensuring high data quality.

By integrating event-driven architectures with SAP Build, you can significantly increase the processing speed of your business workflows, reduce human intervention, and enhance operational excellence for your IT department.

Here you can see a screenshot of the Advanced Event Mesh cockpit within SAP Integration Suite:

You can listen and subscribe to multiple events by creating queues in your SAP or non-SAP system within multiple regions and hyperscalers. For example it can be an event that indicates that a new business partner has been created within your ERP landscpape:

Once this subscription has been established you can proactively trigger a workflow or automation task within SAP Build Process Automation. To stay within the example, you can trigger new approval workflows once a new business partner has been established. As a result, every time a new business partner has been entered, an additional approver makes sure that the payment details and to address of the organization has been assigned correctly. By doing so you increase the degree of data accuracy and compliance of your business processes while minimizing the degree of human intervention:

Thanks to the native connectivity of SAP Build and our Event Mesh services you can easily select any event to trigger a process instance in SAP Build Process Automation. Further details on how to establish the connectivity can be found on the blogpost of my colleague Win, which can be found here or within the public documentation in the Help-Portal.

3rd scenario: Simplifying connectivity to improve developer efficiency

The final scenario for combining SAP Build and SAP Integration Suite involves our new consolidated API for SAP-managed data: Graph.

Graph uses modern open standards like OData v4 and GraphQL, serving as a key capability within API Management in SAP Integration Suite. With Graph, developers can access your business data as a single, semantically connected data graph that spans the entire suite of SAP products and beyond. It is designed for SAP’s ecosystem of partner and customer developers, offering a powerful API that significantly reduces the cost and complexity of creating and deploying reusable extensions and other client applications.

As enterprise landscapes continue to expand in both scale and complexity, each new system, SaaS, or microservice introduces new protocols, data models, connectivity requirements, and security conventions. Real-world challenges often span multiple lines of business, services, and APIs, making it difficult even for experienced developers to grasp all the underlying technologies and interfaces. Creating new business-extending client applications requires a growing range of expertise and skills. The rise of low-code tools, now widely adopted by nonprofessional developers, further widens this gap.

Graph simplifies this complexity by allowing you to combine and expose data from multiple systems and data sources. You can then easily consume this API within SAP Build. At any point in your SAP Build Process Automation workflow, you can leverage an Action to retrieve, post, patch, put, or delete data within your SAP landscape.

This connectivity model allows you to interact with systems based on a unified enterprise data model, simplifying data access and avoiding unnecessary ETL processes and data replications for specific use cases.

Here you can also find a simplified architecture, that describes this scenario:

Additionally, SAP Integration Suite allows you to leverage proven integration features such as API Management, which helps monitor and evaluate your connections. You can also apply critical policies to these connections to ensure compliance and secure operations.

Further details can be found on the blogpost of my colleagues Palak Garg and Evgeniy Gorbunov.

Conclusion

I hope this blog post has helped you identify the key synergies between SAP Build and SAP Integration Suite and how they can enable seamless automation across your enterprise. Please remember that the use cases provided are just examples and can be tailored and refined to meet your specific needs.

Here you can also find a simplified architecture, that describes the entire scenario in a more generic way:

For further guidance, I’ve included links to additional blog posts and resources on the Help Portal that will assist you in implementing these use cases. If you're interested in exploring more scenarios related to Enterprise Automation, feel free to check out the following links:

Stay tuned!

Join the upcoming CEI project in 2025 for SAP Integration Suite

2025-02-24T14:45:33.895000+01:00

In this year’s Customer Engagement Initiative (CEI) project for SAP Integration Suite, we will continue collaborating with our customers and partners to gather feedback on product improvements, enhancements and new developments to validate at an early stage, and ensuring that we not only build the right features for your needs but also building it right.

This will include open discussion about our current product backlogs, roadmap items, addressing pain points and collecting feedback. Some of the core investments which we want to validate in the upcoming CEI project include Gen AI for Integration, move from SAP Process Orchestration to SAP Integration Suite, new adapters, integration in the context of Enterprise Automation, etc.

If you like to join the upcoming SAP Integration Suite influence project for providing feedback and shaping the SAP Integration Suite product, please register at the customer influence page.

Registration is open from 24th of February until 28th of March.

Once, the registration closes, we will invite you for an initial call where we go through the scope and the prerequisites of the feedback project. This will be around April so that we are able to start the project latest in May this year.

Accessing SAP Graph OData V4 through SAP Cloud Integration (CPI)

2025-06-19T15:04:44.943000+02:00

This blog explains how to access an SAP Graph OData V4 URL using SAP Cloud Integration (CPI). We will configure the connection, use OAuth 2.0 Client Credentials, and query data using OData parameters.

What is SAP Graph?

SAP Graph is a unified API that provides a simplified, single interface to access data across various SAP systems (like SAP S/4HANA, SAP SuccessFactors, SAP Sales Cloud, etc.). It helps developers interact with complex SAP systems using a consistent API structure, making integration and data access easier.

Prerequisites

Access to SAP BTP with an SAP Graph instance.
OAuth 2.0 Client Credentials for SAP Graph.
SAP Cloud integration with design privileges.

Step 1: Create OAuth 2.0 Credentials

In SAP BTP Cockpit, create your SAP Graph instance.
Create the service key for graph instance . Go to Security material and create OAuth 2.0 client credentials.
Note the Client ID and Client Secret.
Save the credentials in Security Material as a new OAuth2 Client Credentials (e.g., Credential Name: GraphOAuthCredentials).

Step 2: Get the SAP Graph URL

In SAP Integration Suite, navigate to the Design section.
Inside Business Data Graph, you can find the OData V4 URL for your SAP Graph instance.
Copy the OData V4 URL (e.g., https://<your-graph-url>/graph/api/graphdemo).

Step 3: Configure OData Connection in CPI

Log in to SAP CPI, go to Design, and create an Integration Flow.
Add a Start Timer and a Request Reply step.

3. Set connection details:

Address: https://<your-graph-url>/graph/api/graphdemo/sap.s4
Authentication: OAuth2 Client Credentials
Credential Name: GraphOAuthCredentials

Step 4: Set the Resource Path

Resource Path: A_SalesOrder
Query: $select=SalesOrder,SoldToParty&$filter=SalesOrder eq '1'&$expand=_SoldToParty

Step 5: Deploy and Test

Deploy the integration flow.
Monitor message processing to verify the response.

Conclusion:
By following the above steps, you can seamlessly connect SAP Cloud Integration (CPI) with SAP Graph using OAuth 2.0 Client Credentials. This setup allows you to securely access and query data from multiple SAP systems through a unified OData V4 endpoint.

Graph on Integration Suite: Simplifying Multi-API Data Retrieval with Unified Business Data Graph

2026-01-09T16:13:06.365000+01:00

Graph is a new and innovative feature of API Management, part of the SAP Integration Suite. Expanding on traditional API Management, Graph allows you to present all your business data as a semantically connected data graph, accessible through a single, unified, and powerful API.

SAP Graph is generally available as a core capability within SAP Integration Suite includes the following new features:

A configuration UI for creating business data graphs – an extension of the new Integration Suite configuration UI.
The ability to extend the built-in Graph data model.
Graph Navigator (Enterprise Edition) – a tool for exploring and testing queries on your configured business data graphs.
GraphQL support (in addition to OData v4).

Graph Capability in Integration Suite:

Graph can be used in any SAP Integration Suite plan where API Management is available (including SAP BTP trial accounts), but not necessarily in every region where API Management is available. For more details about the regional availability of Graph, be sure to check out SAP Note 3338820.

Enabling Graph on your Integration Suite

Ensuring the Required Roles and Enabling Graph

Make sure you have the Integration Suite Provisioner role.
Navigate to "Manage Capabilities" → "Add Capabilities" in your Integration Suite home.
Enable API Management (if not already enabled) through the "Manage APIs" section.
Enable API Business Hub Enterprise and Graph (API Business Hub Enterprise is mandatory for Graph).
If Graph is not visible, refer to SAP Note 3338820, as it may not be supported in your region.
Select "Enable API Business Hub Enterprise" and "Graph" to complete the setup.

Note: Graph requires SAP API Management to be activated.

Assigning Roles for Graph

Once Graph is enabled, you will see two additional Role Collections in the SAP BTP Cockpit:

Graph.KeyUser – A role for Graph Developers to define Business Data Graphs (BDGs).
GraphNavigator.Viewer – A role for viewing graphs in Graph Navigator.

To proceed, go to your SAP BTP Cockpit and assign these Role Collections to your user.

Note the term: Business Data Graphs. SAP refers to Graphs as BDGs or Business Data Graphs in their documentation.

That's 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

In below screenshot Graph entitlement is enabled

To enable SAP Graph (Business Data Graphs - BDGs) in your BTP Subaccount, follow these steps:

Navigate to your BTP Subaccount.
Go to Entitlements → Configure Entitlements.
Click "Add Service Plans".
Select SAP Graph and choose the api service plan.
Save your changes to apply the entitlement.

Creating a Service Instance for SAP Graph

Go to your BTP Subaccount.
Navigate to Services → Instances and Subscriptions.
Click "Create" and select SAP Graph as the service.
Choose the api plan.
Provide a name for your service instance.
Click "Create" to finalize the setup.

Creating a Service Key for SAP Graph

Go to your BTP Subaccount.
Navigate to Services → Instances and Subscriptions.
Find the SAP Graph service instance you created in the previous step.
Click on the instance and select "Create Service Key".
Provide a name for the service key and click "Create".
Once generated, copy and save the Service Key, as it will be required for exploring Business Data Graphs (BDGs) using Postman.

The Graph instance is created and Binded with its Service Key:

Once your Service Key is created, make sure to note the following details:

clientid – Required for authentication.
clientsecret – Used for authentication along with the client ID.
url – This is the Token URL used to obtain authentication tokens.
uri – Contains the hostname, which includes the GraphQL Endpoint hostname for accessing Business Data Graphs (BDGs).

You'll need these details when exploring BDGs using Postman or any API client.

Graph Creation

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-Premises 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.

Note: In my case I’m using SAP Business Accelerator Hub – API HUB

Querying Sales Orders and Customer Details with SAP Graph

In a typical integration scenario, querying Sales Orders from SAP S/4HANA and fetching Customer Details (SoldToParty) involves:

Making an OData GET request to the Sales Order API to retrieve Sales Order details.
Making another OData GET request to the Business Partner API to fetch the corresponding SoldToParty details.
Enriching the data using SAP Cloud Integration to combine the two datasets.

Since SAP provides this information through two separate APIs, this approach traditionally requires two API calls and additional processing to merge the data. However, with SAP Graph (BDGs - Business Data Graphs), you can simplify this by using a single GraphQL query to fetch Sales Orders and their associated Customer details in one call.

Simplifying Data Retrieval with SAP Graph

Traditionally, in SAP Cloud Integration, fetching Sales Order details along with SoldToParty (Customer Details) from S/4HANA Cloud requires:

Multiple OData API calls (one for Sales Orders, one for Business Partners).
Content Enrichers to merge and process the data.
Lookups to fetch related information across different API endpoints.

This is a common challenge when integrating SAP and non-SAP SaaS applications.

The Power of SAP Graph (BDGs - Business Data Graphs)

With SAP Graph on Integration Suite, you can retrieve all this data in one API call—with no custom development!

SAP Graph introduces the concept of Mirrored Entities, which allows you to:

Access data from multiple APIs as a single, unified data model.
Query related entities (e.g., Sales Orders and SoldToParty) in a single request.
Reduce integration complexity and eliminate the need for multiple lookups/enrichers.

What’s Next?

We’ll explore Mirrored Entities in SAP Graph and see how they can simplify fetching Sales Order details along with Customer details from an Business Accelerator Hub—all in one call.

Creating Destinations on SAP BTP

To integrate SAP Graph with your S/4HANA Cloud or On-Premise system, you need to create destinations on your BTP Subaccount.

Prerequisites

You have your OData API endpoint for Sales Orders and Business Partners.
A Technical Communication User is set up with the required roles and permissions to access these APIs.

Steps to Create Destinations in BTP

Navigate to BTP Cockpit

Go to your BTP Subaccount where Integration Suite / Graph is running.
Open the Destinations section.

Create a Destination for Sales Orders API

Create a Destination for Business Partner API

Setting Up a Business Data Graph in Integration Suite

Next, we’ll create a Business Data Graph (BDG) in SAP Integration Suite. To get started, go to Integration Suite → Design → Graph.

Once destination as source are added, click next, review the configurations, below screen will appear in a while after processing

Click on Activate.

Test Your Graph on Graph Navigator

Validating Graph OData API

As discussed earlier, all Business Data Graphs (BDGs) created in SAP Integration Suite are accessible via OData V4 APIs, as documented in SAP's official guides.

Now, we’ll use the Service Key generated in the previous step to obtain an OAuth token and authenticate our request to test the Graph OData API.

Note the URI in your Service Key has the format

https://<subdomain>.a.integration.cloud.sap/graph/api

List all BDGs

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.

List all Entities in a namespace in a BDG

Entities of a Graph can be displayed using below

Get Metadata of a Service (Namespace)

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 )

That's it! We have successfully invoked your Graph OData V4 API and retrieved Sales Order data enriched with Business Partner details.

What would typically require a two-step process using a Content Enricher in Cloud Integration is now streamlined into a single API call—thanks to Graph on Integration Suite.

SAP Graph has the below GraphQL endpoint :

https://<subdomain>.a.integration.cloud.sap/graph/api/<bdg>/graphql

Use REST services in Graph

2026-01-20T16:41:34.615000+01:00

Hello!

In this part of the tutorial on Graph we will focus on the support of REST services in Graph. For an overview of other parts of this series, check out the Information Map.

REST support in Graph

Graph enables the use of REST services as data sources for business data graphs (BDGs). Compared to OData data sources, there are some key differences:

The metadata that describes the service must be provided separately along with the service endpoint in the OpenAPI format.
OpenAPI does not have the concept of entities like OData does. Instead, it focuses on operations, which are represented as actions and functions in a BDG.

We will now explain how these differences are being handled by Graph in more detail:

Metadata for a REST service

REST services are commonly described using the OpenAPI format, which outlines the operations and resources available in the service. Unlike OData, which provides a $metadata endpoint for accessing service metadata, plain REST services do not have a standard way to access this information. Since Graph requires metadata to work with REST services, users must provide this metadata when setting up a business data graph.

Graph uses BTP destinations to define access to data sources. To use a REST service as data source, users need to create 2 destinations:

a data destination: that points to the actual REST service
a metadata destination: where the OpenAPI metadata document for the REST service can be retrieved

Both destinations also need annotations that connect them together, so that Graph can understand which metadata destination belongs to which REST service destination.

Data Model

Graph exposes a unified API endpoint for the OData and GraphQL protocols. Both offer an entity (or type/object) model in which data can be represented. Plain REST as described by OpenAPI does not have a strict entity model, and services are defined as different operations. For example, an operation might be to 'find a pet by name' or 'retrieve pets of a store' in a pet-store service. However, to expose these REST-operations as valid OData in the unified API, Graph transforms them into unbound OData operations (actions & functions) in the BDG. We refer to these also as mirrored operations, similar to mirrored entities. As part of that transformation, some changes are made to the signature of the operations to align with the OData standard. These include:

all paths are flattened: for example a GET /users/pets is transformed to a GET users_pets in the BDG
all methods are standardized to GET and POST, with the underlying method being appended to the operation name: for example a DELETE /users/pets becomes a POST /users_pets__delete

Example

Having explained the main concepts of REST support in Graph, let's now look at a practical example. We will take the try-out sandbox of this SAP Ariba Network Catalog Management REST service and use it in a BDG. You can also download the OpenAPI metadata document for the service there under API Resources / API specification.

Tutorial Setup

Before we can use the SAP Ariba service in a BDG, we need to setup the two destinations in SAP BTP.

Prerequisites:

SAP Integration Suite with API Management and Graph enabled
Access to destinations and service instances in SAP BTP cockpit

Data Destination

Open the SAP BTP Cockpit and create a new destination from scratch in the BTP subaccount where you have Graph and SAP Integration Suite. Enter the following details

Name: ariba-network-catalog-mgmt
URL: https://sandbox.api.sap.com/ariba/api/network-catalog-mgmt/v1/sandbox

Also add these two additional properties to the destination:

Key: Graph.destinationType with the value: REST. This declares this destination as a REST data destination to Graph.
Key: URL.headers.apiKey with the value: <your sandbox API key> to add your sandbox API key for authentication purposes (this only applies to this sandbox-example). You can retrieve your API key here: https://api.sap.com/settings.

data destination in BTP cockpit

Metadata Destination

Next, we need to define the metadata destination that points to a location where Graph can access the OpenAPI metadata document. This could be done in a number of ways by hosting this file in a file-server/document storage or at a custom service endpoint for example. For sake of keeping this tutorial simple we will only use SAP Integration Suite to make this file available to Graph: we will create an API artifact which returns the content of the OpenAPI metadata file and then create the metadata destination that points towards the endpoint of that API artifact. Note that this is only for the purposes of this tutorial, and not a requirement.

Hosting the OpenAPI file with an API artifact (optional, only for the tutorial)

First we create the API artifact in SAP Integration Suite. Open Integration Suite and go to Design > Integrations and APIs. Choose an existing package or create a new one. In the package click Edit and open the Artifacts tab. Now you can select Add > API in the table menu. Follow the API creation dialog and select REST API as API Type, Create as Method and then give it the following name: Ariba-Network-Catalog-OpenAPI. Open the created API and in the 'Handle Request' lane select the 'Content Modifier' step. In the bottom UI panel you will then see the Message Body tab where we can paste a constant body this API should return. Here, we will paste the JSON content of the OpenAPI specification of the service (available here). If you have other APIs in the tenant you might also want to assign a unique path for this API. To do that select the HTTPS arrow outgoing from the Start participant, and then in the bottom UI panel you can edit the 'Connection' and change the path in the 'Address' field. Here, we are using /ariba-network-catalog-openapi. Then save the API artifact and deploy it. You can check the deployment status under Monitor > Integrations and APIs > Manage Integration Content: All. When it is deployed, the OpenAPI document will be available at that endpoint. Copy the endpoint URL for later.

constant message body returns the OPenAPI spec JSON

unique path for this API artifact

monitoring view of the deployed API artifact, with the endpoint URL

To access that endpoint in a destination, we also need the authentication details. Here, we want to authenticate using OAuth client credentials that we obtain from a SAP Process Integration Runtime. For that, go to BTP Cockpit and under Services > Instances and Subscriptions you can find it or create a new one. Then create a Service Key for that instance. We now have a set of client credentials we need for authentication: namely the clientid, clientsecret and tokenurl.

process integration runtime with a service key in BTP cockpit

Creating the Destination

Now we can create the Metadata destination. Enter the following details:

Name: ariba-network-catalog-mgmt-openapi
URL: the API artifact endpoint URL from above
Authentication: OAuth2ClientCredentials
Client ID: clientid from above
Client Secret: clientsecret from above
Token Service URL: tokenurl from above

We will also annotate this destination with additional properties, to tell Graph that this is the metadata destination for the previously created ariba-network-catalog-mgmt destination:

Key: Graph.destinationType, with a value of OpenAPI
Key: Graph.metadataFor, with a value of ariba-network-catalog-mgmt

metadata destination

Now the destination setup is complete and we can create a BDG.

Creating the BDG with REST data sources

With the data destination and the metadata destination created, we can now continue to create a BDG with the REST service. The process does not differ much in this case. In Integration Suite under Design > Graph, create a new Business Data Graph with the ID rest-bdg. In the list of destinations, you can now see an ariba-network-catalog-mgmt entry with the type REST. The info icon shows you more details, for example that Graph has identified which metadata destination belongs to this entry. Just select the entry and continue. When the dialog is finished and we see a preview of the BDG details, we can also change the namespace of the data source from my.custom to my.ariba (this is optional). Continue by activating the BDG.

data source selection when creating a new BDG

editing the namespace of a data source

overview of the activated BDG

Making Queries against the BDG

With the BDG activated, we can now inspect the mirrored operations. Open the BDG in Developer Hub (there is a link on the overview tab of the BDG). You will see the following operations:

GET products (mirrored from GET /products)
GET products_ (mirrored from GET /products/{productid})
POST products__delete (mirrored from DELETE /products/{productid})
POST products__patch (mirrored from PATCH /products/{productid})
POST products_post (mirrored from POST /products)

The productid path parameter here is either transformed into an unbound function path parameter, or an unbound action body parameter in this example. This illustrates the transformation that Graph makes of the mirrored operations into valid OData operations as mentioned earlier. In the try out tab we can see all the parameters of the operation and also give it a go.

Note: Graph treats all parameters of mirrored operations as required at this time. However, you can set the value to null.

This SAP Ariba sandbox API requires an X_ARIBA_NETWORK_ID parameter. You can use the value AN02005777309 for this sandbox. When running the my.ariba/products operation, we can see that we get the response from the REST service in a valid OData format.

trying out the mirrored functions in Developer Hub (Graph Navigator)

Summary

In this tutorial we had a look at how REST services can be used as data sources in a business data graph. With this feature, you can integrate data from REST services alongside data from OData services into a single unified Graph API.

You can learn more about REST-support in Graph in the documentation:

Florian Moritz

Announcement: Register to the new CEI project for SAP Integration Suite in 2026

2026-02-09T08:33:34.010000+01:00

Like in the previous years, we will run a Global Customer Engagement Initiative (CEI) for SAP Integration Suite also in 2026.

Last year, we had 180+ registered customers and partners from over 20 countries worldwide. We ran multiple feedback sessions covering various capabilities and strategic investment topics of SAP Integration Suite such as "SAP Process Orchestration move" (ABAP proxy generation, mass migration, migration assessment, migration agent, etc.), AI & gen AI in the context of SAP Integration Suite in general and for B2B in particular, monitoring and operations, new adapters and adapter enhancements, reusable APIs and governance of API key access, event driven architecture, etc.

In 2026, we will continue collaborating with our customers and partners to gather feedback on product improvements, enhancements and new developments to validate the planned enhancements at an early stage, and ensuring that what we build will meet your business needs.

This will include open discussion about our current product backlog from the roadmap explorer as well as addressing pain points and topics that we collected in last year's CEI project such as more on Edge Integration Cell, AI, SAP PI/PO to SAP Integration Suite migration, Event Driven Architecture, ISA-M, best practices and guidelines, developer experience, etc.

If you like to join the upcoming SAP Integration Suite influence project for providing feedback and shaping the SAP Integration Suite product, please register here (link leads to the customer influence page).

Registration is open from 9th of February 2026 until 13th of March 2026.

Once, the registration closes, we will invite you for an initial call where we go through the scope and the prerequisites of the feedback project. This will be around end of March/ begin of April so that we are able to start the project latest in April this year.

We will run monthly feedback sessions through the end of the year and hold a closing call to summarize our learnings, review the feedback collected, and discuss next steps.

Register today to ensure you do not miss this opportunity to influence and contribute to shaping SAP Integration Suite to meet your business needs.

We look forward to your active participation and valuable feedback.