SAP Community - API Management

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",
    "script" : {
        "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, `${req.url}`, "");
    res.send(`<pre><code>${JSON.stringify(response, null, 2)}</code></pre>`);
});

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

SAP Recognized as a Leader in 2024 Gartner® Magic Quadrant™ for iPaaS

2024-02-29T05:15:00.020000+01:00

We are proud to announce that Gartner has recognized SAP as a Leader in the Gartner Magic Quadrant for Integration Platform as a Service (iPaaS) worldwide. SAP’s Integration Suite was evaluated and based on various factors including reviews of current users of our service. We were recognized as a Leader for the fourth consecutive time. We believe we have received this recognition for the targeted efforts to deliver a customer-centric service with a strong focus on innovation and being future-ready.

Built as a single, comprehensive integration platform, SAP Integration Suite empowers you to integrate and automate processes with speed and confidence across SAP and third-party landscapes. You can leverage our pre-built integrations, APIs, connectors and best practices to design end-to-end automated business processes and deliver innovations that can set you apart from your competition. You can learn more about it here.

SAP is recognized for its ability to execute, we believe this validates our customer-centric approach to product development and evolution. Our innovations which include new integration patterns and artificial intelligence-based features that enhance developer productivity, were rated highly.

We offer a strong commercial and product support presence across all geographical regions. This makes Integration Suite one of the few truly global managed iPaaS offerings suitable for all market segments. We also offer deployment flexibility with our service’s ability to be deployed on client data centers, data centers for regulated industries and private cloud regions.

It gives us immense satisfaction to see that 97% of our customers strongly recommend SAP Integration Suite on Gartner® Peer Insights™. We feel this is an indicator of our customer-focused execution and a shot in the arm for our teams to double down on our roadmap and continue to deliver innovations. Customers also reported that their trust in our roadmap and vision is 4.5% higher than the market average reported by We focus on ensuring that our customers have an enterprise-grade feature set that can help them remain competitive in a market that continues to evolve at a rapid pace, while also ensuring that their investments in SAP Integration Suite is protected for the foreseeable future.

What makes Integration Suite a Leader in the iPaaS Market?

SAP Integration Suite is an AI-assisted integration platform as a service (iPaaS). With this single solution, you can connect applications from SAP and third parties, whether they run on-premise or across clouds. You can use a combination of integration modes to address specific use cases and run your integrations on major public clouds for greater flexibility.

Robust functionality in SAP Integration Suite means you can confidently integrate and manage your mission-critical processes across SAP and third-party applications in complex and distributed landscapes.

Here are some of the key value propositions that we believe set SAP Integration Suite apart from the competition:

Third-Party Connectivity: SAP Integration Suite is a general-purpose iPaaS that can easily integrate with third-party applications as well. We offer 250+ third-party application connectors in addition to protocol-based connectors that can be used to connect with different systems. We also have a strong roadmap to increase the number of non-SAP connectors, further demonstrating our intent to be an excellent all-purpose iPaaS.
Runtime Deployment Flexibility: Depending on your needs and security constraints, you can choose to deploy our runtime in the public cloud, private cloud, within your private data centres, or employ a hybrid setup with runtimes in both public and private regions.
Power of Artificial Intelligence: We at SAP are committed to leveraging artificial intelligence in the Integration Suite to boost developer productivity and insights via behavioural patterns that include mapping proposals, industry-based inter selection and scenario generation. This is a priority topic for us and we are investing continuously to offer a true next-gen integration platform.
Enterprise Automation: We at SAP believe that Process Automation is the key to any digital transformation and our endeavour is to equip you with the tools necessary to build end-to-end intelligent business and IT processes. In combination with SAP Signavio and SAP Build, we offer the perfect enterprise trifecta for Enterprise Automation.
API and Event-Driven Integration: Support for modern integration patterns is a critical aspect of any future-proof iPaaS. Integration Suite supports and offers best practices for both API-centric and event-driven integrations. We offer out-of-the-box 600+ business events and ~4000 APIs on the SAP Business Accelerator Hub, with the number growing at a rapid pace as more SAP LoBs publish their content on the hub.
SAP Process Orchestration Move: We are very cognizant of the fact that many of our customers have significant investments in SAP Process Orchestration, and we are fully committed to helping them transition to Integration Suite with the least business disruption and maximum reusability while staying true to the digital transformation objective. Our migration tools and special programs like Migration Factory focused on migration help customers craft a strategic journey that will ensure the lowest TCO and highest value in their transition from the on-premise SAP Process Orchestration to the hybrid SAP Integration Suite.
Business Integration Content: Getting started quickly by using integration packages infused with business expertise and best-in-class industry experience on the SAP Business Accelerator hub has been one of our unique offerings for our customers. We engage our vibrant community to develop content in a collaborative model and offer it to our customer base. As of today, SAP offers 3400+ pre-packaged Integrations including SAP and third-party integration scenarios.

Summary

We are very grateful for the vote of confidence from our customers, partners, and analysts that has culminated in SAP. We are happy to be recognized as a Leader in Gartner Magic Quadrant for Enterprise iPaaS. We feel, this is validation and it has boosted our confidence that we are heading in the right direction and will further energize us to deliver more customer-centric features and innovations while staying true to our core principles of high developer productivity, happy user experience, and optimized total cost of ownership (TCO).

Where Can I Learn More?

GARTNER is a registered trademark and service mark of Gartner and Magic Quadrant and Peer Insights are a registered trademark, of Gartner, Inc. and/or its affiliates in the U.S. and internationally and are used herein with permission. All rights reserved.

Gartner Peer Insights content consists of the opinions of individual end-users based on their own experiences with the vendors listed on the platform, should not be construed as statements of fact, nor do they represent the views of Gartner or its affiliates. Gartner does not endorse any vendor, product or service depicted in this content nor makes any warranties, expressed or implied, with respect to this content, about its accuracy or completeness, including any warranties of merchantability or fitness for a particular purpose.

Gartner does not endorse any vendor, product or service depicted in its research publications and does not advise technology users to select only those vendors with the highest ratings or other designation. Gartner research publications consist of the opinions of Gartner’s research organization and should not be construed as statements of fact. Gartner disclaims all warranties, expressed or implied, with respect to this research, including any warranties of merchantability or fitness for a particular purpose.

This graphic was published by Gartner, Inc. as part of a larger research document and should be evaluated in the context of the entire document. The Gartner document is available upon request from SAP.

There is no AI without API - Integration is the backbone of digital transformations.

2024-03-04T08:00:00.021000+01:00

Why API?

When we talk about AI (like generative AI) we need to remember they can't do much alone. They need APIs, which are like bridges, to connect them to other applications or software in general. This way, AI can get the data it needs and tell other systems what to do. Think of AI as someone who wants to cook but needs someone else to bring the ingredients and turn on the stove. That helper is the API.

"Integration is the backbone of digital transformations and APIs are the building blocks of every SAP customer who sells, buys or transports their products with its use" - Michal Krawczyk

Why APIs are Important for AI - communication layer?

Figure 1 - AI cannot exist without API as it needs it to communicate

APIs help AI in many ways:

Getting Data: AI needs lots of information to learn and make decisions. APIs bring this data to AI from different places.

Working Together: Different programs and applications (event from SAP Ecosystem) don't always speak the same language. APIs help them understand each other so AI can be part of the team.

Creating New Things: With APIs, people can make new smart tools by using what's already there, like mixing different ingredients to bake a new cake.

Things to Watch Out For

APIs make a lot of things possible, but there are some issues, like keeping data safe, making sure private stuff stays private, and getting different APIs to work well together. Making APIs secure, protecting privacy, and making them fit together better are big tasks for the people who make them.

What's Next for AI and APIs (and iPaaS like SAP BTP Integration Suite)?

As the world gets more connected and smart, AI and APIs will become even more important. We need better, safer, and easier-to-use APIs so AI can do more cool stuff in areas like health, money, making things, and moving around. In the future, we need APIs that can handle big tasks, keep data safe, and work well with all kinds of systems. This will help AI do more for us, making life easier and more interesting. When reading articles like iPaaS Emerges as the Dominant Platform for Automation and Integration all of a sudden you may understand why we might see such a big expenditure shift in iPaaS technology like SAP BTP Integration Suite.

Figure 2 - Figure 2 - iPaaS Dominates the Automation + Integration Technology Market from linked article

To Summarise

Just like a chef needs a good kitchen team, AI needs APIs to bring its smart ideas to life. Without APIs, AI can't do much. But with good APIs, AI can help us in many ways, making our world smarter and our lives better. As we move forward, making better APIs will help AI do even more amazing things.

The State of Integration – Research from ASUG and SAP

2024-03-07T21:19:30.312000+01:00

Integration is not only a technological investment, but also strategically imperative across organizations to thrive in today’s digital economy. Through the research conducted by ASUG, we know that the integration topic is highly relevant for ASUG members with almost all being actively involved in integration projects. The study also highlighted how SAP Integration Suite is being used today.

ASUG discovered that many customers use a wide range of connections with SAP applications including SAP SuccessFactors and SAP S/4HANA, but they are also connecting with a multitude of other non-SAP application types and in their landscapes. The ASUG research shows our customers growing diversity in their application landscape confirming the need for seamless integration across all application types. We have seen more customers connecting with non-SAP applications and these results validate what we have seen across our customer base. There are an equal number of integrations between SAP to SAP applications and SAP to 3rd party applications. Interestingly, over half of those surveyed are connecting non-SAP to non-SAP which speaks to the comprehensive set of features we have in Integration Suite.

The ASUG study also noted that 90% of respondents face challenges with integrations, with a wide array of issues experienced such as lack of internal skills/resources, data inconsistencies, and budget constraints top the list. However, many benefits can be realized from integrating data, processes, and/or applications. They include:

Improved use of data and analytics
Streamlined business processes
Better application adoption and use.

More than 1/3 of users also find realized value by using intelligence to drive business decisions and to collaborate with others.

Listen to this webcast to learn more about how customers see having an integration strategy is critical, the benefits of implementing an integration strategy, the types of landscapes and applications they are integrating, what capabilities are most used, and what common challenges users experience with integration. Here’s a synopsis of the study.

How to remove __Metadata from CPI json payload

2024-03-08T17:49:09.791000+01:00

Hi,

Please suggest, how to remove __metadata from json payload using groovy script.

What’s New for SAP Integration Suite – February 2024

2024-03-12T09:22:05.281000+01:00

Before going into the highlights of our innovations, we are thrilled to inform you that SAP Integration Suite has been recognized as a Leader in the latest Gartner Magic Quadrant for Integration Platform-as-a-Service (iPaaS) for the fourth consecutive time. We are convinced that we have been received this recognition for our commitments to deliver a top-tier customer-centric integration solution, the ability to accelerate business outcomes through prebuilt content, ongoing innovation, the global geographic strategy, and readiness for the future. And a big thanks also goes to you in supporting us with all your great feedback. For more details checkout the blogpost and the SAP News article.

SAP Integration Suite highlights are:

JMS receiver adapter: property to identify sending integration flow
Inspect resource consumption through SAP Cloud ALM/SAP Focused Run
Call to action: Upgrade to new version of third-party connectors
Duplicate nodes on target side in a MAG
Definition of more complex code value mapping scenarios
Add metadata for OData-based API artifacts deployed on Edge Integration Cell
Enhancement of security standards in API Management
Policy templates in API Management
Distributed tracing in advanced event mesh
Direct consumption of SAP S/4HANA Cloud events in advanced event mesh

Cloud Integration

JMS receiver adapter: property to identify sending integration flow

We have extended the JMS receiver adapter by storing a new SAP_IntegrationFlowID property. It contains the ID of the integration flow that has sent the message through the JMS receiver adapter. The JMS consumer can use this property to define steps depending on the sending integration flow ID. Refer the documentation.

Inspect resource consumption through SAP Cloud ALM/SAP Focused Run

Inspection of your resource consumption has been available since the middle of last year. Now you may analyze the utilization of database and system resources through the health monitoring application of SAP Cloud ALM and SAP Focused Run. For troubleshooting bottlenecks caused by integration flows you may jump directly to the Inspect section of the Cloud Integration monitor.

Call to action: Upgrade to new version of third-party connectors

As per SAP note 3001980 the following previous adapter versions are deprecated since end of 2020: Salesforce, Amazon Web Services, Microsoft Dynamics, SugarCRM. There haven't been any new features or enhancements for these previous adapter versions. After the upcoming Apache Camel upgrade, the adapter versions will no longer run.

Action is required from the customer's side. Check all your tenants to see whether you have any kind of the above adapters still deployed. Please undeploy and delete the adapters. In case of question reach out to annemarie.kiefer@sap.com.

B2B Integration

We have extended the mapping functionality of the Integration Advisor capability to offer you more flexibility.

Duplicate nodes on target side in a MAG

When designing B2B integration scenarios you may have situations where certain information within the source structure needs to be mapped to only one node in the target structure. Now the mapping guidelines editor of the Integration Advisor capability enables you to duplicate group or leave nodes and map each source alternative to one of the reproductions. Refer to the documentation.

Definition of more complex code value mapping scenarios

You are now able to define local or global mappings of multiple code values at the source side to one code value at the target side. The value function now supports N:1 cardinality code value mapping ease e.g., situations where you have to map multiple partners or currencies.

API Management

Add metadata for OData-based API artifacts deployed on Edge Integration Cell

You can now supply an EDMX specification for API artifacts (API-led integration flows for deployment on Edge Integration Cell), that are based on OData APIs. This allows you to easily specify additional integration steps based on the resources of this API. See the detailed documentation.

Enhancement of security standards

As always, our intention is to offer the highest security standards to avoid attack vulnerabilities. Therefore, we encourage you to use strong certificates, and will no longer accept uploads to the Trust Store of weak customer-owned self-signed certificates or certificate chains used for mTLS handshakes. Consequently, the OpenSSL security level has been increased to level 2. See a comprehensive definition of security level 2 published on the OpenSLL site. For additional details please see note -3418201.

Policy templates

We have filled a small gap when applying policy templates to an API proxy. Default fault rules or post-client flows available within a policy template will now also be appended to the API proxy. Refer to the documentation.

Event-driven Integration

We have news regarding SAP Integration Suite, advanced event mesh our offering for distributed network of event brokers and sophisticated features.

Distributed tracing

We have extended SAP Integration Suite, advanced event mesh with a distributed tracing capability. Now you are able to trace the the lifecycle of events through OpenTelemetry, from the producing application across one or multiple event brokers to the receiving application.

Direct consumption of SAP S/4HANA Cloud events

We have an update regarding the event sources. We have enabled the direct consumption of SAP S/4HANA Cloud events into SAP Integration Suite, advanced event mesh without any intermediate hops. SAP S/4HANA Cloud customers may leverage SAP Integration Suite, advanced event mesh for very large projects, where performance is crucial. Read the documentation.

How to stay tuned to recent and upcoming innovations?

The SAP Road Map Explorer is your one-stop shop for all SAP Integration Suite innovations. You can easily check out the latest innovations and follow what is planned for the following quarters. All recent innovations also cover under the tab Features further links to blogposts or documentation.

We also refer to the complete list of new releases in our documentation: What’s New in SAP Integration Suite.

And if you have not heard of our monthly webinars, I suggest you sign up to get an invitation to the upcoming ones. Our team of Product Management experts host these webinars to showcase the latest and greatest updates regarding all SAP Integration Suite capabilities. The webinars are hosted on the last Tuesday of every month and the next one is already scheduled for February 27th.

In case you have missed our last monthly webinar, don’t worry. Visit 2024 Learning Sessions for SAP User Groups on SAP Integration Suite for all recordings, presentations, and Q&As.

Are you aware of the Release Navigator for SAP BTP? It consolidates release information across SAP BTP products and services easing you the way to find product release related notes, blogposts, and webpages. For your convenience use the direct link to the SAP Integration Suite section of the Release Navigator.

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

Expanding the Reach of API Catalog with SAP API Management

2024-03-20T11:33:41.357000+01:00

In our ongoing efforts to enhance the developer experience and promote collaboration, we are thrilled to introduce an upgraded set of access controls for our API catalog. For detailed instructions on how to manage access control, please refer to our comprehensive help documentation.

Expanding Horizons: Amplifying the reach of API Catalog via SAP API Management

2024-03-20T19:32:32.803000+01:00

Introduction:

SAP API Management offers a straightforward and sophisticated solution for creating a comprehensive API catalog. Within this catalog, you can easily find and leverage APIs (application programming interfaces) that have been published by your organization. This portal provides administrators with the ability to manage developer access to the catalog. Currently, developers can access the catalog through two different methods:

If the user already has the developer role assigned in BTP (Business Technology Platform), they will be automatically registered when they log in to the catalog. For more information on developer auto registration, please check the Blog .
To gain entry to the catalog, the developers must request registration, and their requests are subject to approval by the administrator.

Feature Enhancement:

In our continuous pursuit of improving developer experience and fostering collaboration, we are excited to introduce an enhanced set of access controls for the API catalog. This update offers three distinct levels of access, empowering your team with flexibility. Let us delve into the details of each level and how it reshapes the landscape of API utilisation.

Authorised Users: Business as Usual : At the heart of our system lies the familiar terrain. Authorised users, those who are logged in and possess the necessary developer role, can seamlessly access, and consume the APIs, maintaining the current behaviour. This ensures a smooth transition for those accustomed to the existing framework.
Authenticated Users: Expanding Horizons : Breaking down barriers, we introduce a new layer of access control. Authenticated users, even without a designated role, can now access the API catalog. This provides an opportunity for broader exploration, enabling users to familiarize themselves with available resources. However, to consume any API, the developer role is still a prerequisite, ensuring a balance between exploration and controlled utilization.
All Visitors: Welcome All, Consume with Care: In a move towards inclusivity, we now extend access to all visitors, whether logged in or not. This allows anyone to explore the APIs and understand its details without the need for authentication. However, the key to consumption still lies in obtaining the necessary developer role. It is a strategy designed to encourage exploration while maintaining a secure environment for API usage.

How to set the access control?

This is how the Manage Access page looks like.

You can manage the access control by referring to the help documentation.

Additionally, we have a comic strip available for you to explore a use case.

Note:

The "Manage Access" feature is only available in the new design of the Cloud Foundry environment. If you are still using the Classic design, we recommend that you move to the new design, as the Classic design is deprecated and will not be available after June 2024. To learn more about the new design, please see the help documentation. 
Access to the developer portal content using the API access plan is not affected by these permissions.
Please be mindful while changing the access control to All Visitors, as this would make your catalog public.

Conclusion: Take Charge of Your Access

With these changes, we made the API catalog accessible for everyone. Whether you are someone with exclusive access, an explorer without a specific role, or just a casual visitor, it is all straightforward. Our catalog administrators, by using the 'Manage Access' settings, ensure that you have the right access and control. Enjoy the simplicity, stay in the loop, and let your catalog administrator be your guide through this improved API catalog experience.

Single Sign On to SAP Cloud Integration (CPI runtime) from an external Identity Provider

2024-04-11T06:53:39.270000+02:00

Introduction:

Yes, you read it right (and you read it right here !). There is an out-of-the-box approach to achieving a single sign-on (SSO) experience for user flows between a corporate identity provider (that authenticates and authorizes the user) and a tenant of Cloud Integration runtime (loosely called CPI worker) fully within the BTP ecosystem.

Ok, let’s zoom out a bit and break this down.

If you are reading this blog post, you probably know already that SAP BTP Services can leverage the OpenID Connect federation-based mechanics of SAP Cloud Identity Service (read: SAP IAS) to connect users from corporate Identity Providers like Entra ID (formerly known as Azure AD), Okta, etc. to XSUAA BTP’s OAuth Authorization Server.
This is certainly not uncharted and I did a detailed blog post a few months ago demonstrating this setup.

However, this setup applied mostly to browser-based SaaS applications (read: Design Time applications with a web frontend), and that brings us to the objective of this blog -> Customers want to put together a similar setup for their client applications that interface with SAP Cloud Integration’s IFLows (in other words, the CPI runtime).
Certainly, this is not impossible to achieve and solution blueprints like these have existed in the past:

My colleague Francisco’s blog puts API Management in between a client and Cloud Integration and enforces API Management to perform an OAuthSAMLBearer handshake.
Microsoft champion Martin Raepple teaches how to set up SAML Trust between Entra ID Identity Provider and BTP to set up a user impersonation flow.

However, these approaches were often seen as cumbersome to set up / troubleshoot and certainly not for the faint-hearted!

Solution Summary:

An easier solution can be described in two phrases: 'OpenID Connect' and 'Authorization Code grant type'. If you are super-smart then you've figured it out already. You can stop reading this blog and hack this yourself.
I wish you a nice day ahead! If you are like me and need a bit more explanation, keep reading 🙂

Here is the solution blueprint that explains that handshake:

SCENARIO: Flows that require end-user authentication from external Identity Providers can natively do so with OIDC and Authorization Code grant type

Step 0: Generate Service Instance / Service Key SAP Cloud Integration Runtime. Refer to this link. Instead of Client Credentials make sure to select Authorization Code.

Step 1: Onboard the needed corporate identity providers in SAP IAS and set up the 'Application' that connects back to your SAP BTP Subaccount as a Trusted Identity Provider via OpenID Connect. Refer to my previous blog post for a detailed procedure.

Step 2: Client (end-user) initiates a connection to the required IFlow (or API artifact). This kicks off the 3-legged OAuth user login flow.

Step 3: As the user is not signed in, she is redirected to XSUAA's login endpoint, and upon login the IAS tenant's OAuth server authorization endpoint at https://<IAS tenant name>.accounts.ondemand.com/oauth2/authorize is invoked using the authorization code grant type. The details of the actual federation as part of the handshake have been omitted here for simplicity. But suffice it to say that the authorization code from the identity provider is made available to the IAS's callback endpoint and finally made available to XSUAA's authorize endpoint and exchanged for the actual access token. This access token will bear the user's scopes and role permissions needed to access the Cloud Integration's IFlow resource.

Step 4: Once successfully authorized, on the receiver side of the IFlow, we will establish connections to 3 different types of backends for illustration purposes. a) S/4HANA Onpremise system over Cloud Connector and Principal Propagation b) SuccessFactors and c) S/4HANA Cloud with OAuth2 SAMLBearer Assertion security material.

Putting it all together:

Let's get our hands dirty by putting together the sequence now. The prerequisites to follow along are listed below:

Administrator privileges in the BTP subaccount where the Integration Suite subscription exists.
An IAS Tenant (with Administrator privileges) that can be coupled (read: Trusted) with the said BTP Subaccount.
Privileges to create Applications (read: IDP configurations) in Entra ID (Azure AD) and/or Okta.
Postman Client.
Backend systems to which the frontend user principal can be propagated to. Either of S/4HANA OnPrem, S/4HANA Cloud, or SuccessFactors tenant.

Step 0: Create a Service Instance for the Authorization Code grant type

Create an instance of the 'Process Integration Runtime' Service (integration-flow service plan) specifically with the authorization code grant type. You can copy the JSON snippet pasted below. Do not worry about the location of the redirect_uri. (When we get down to testing the flow, the browser will invoke the redirect_uri, but this has no consequence as the 'code' will be available for us to copy as a query parameter from the URL itself. When we test this from Postman the client, Postman does not invoke the URL. If you are curious to know, you can read about it here.) Also, make a note that we have specified refresh_token as part of the requested grant type. This will let us demonstrate the ability for clients to refresh the access token post-expiry.

{
    "grant-types": [
        "refresh_token",
        "authorization_code"
    ],
    "redirect-uris": [
        "http://localhost"
    ],
    "roles": [
        "ESBMessaging.send"
    ]
}

With the service instance created, generate a service key (example block is pasted below). Grab the clientid, clientsecret, authorizationurl, tokenurl attributes. We will need these later.

Step 1: Configure OpenID Connect based Trusted Identity Provider of SAP IAS in your SAP BTP subaccount

This step is the heart-and-soul of our approach. We will couple an SAP IAS tenant with our BTP subaccount that has the subscription of our SAP Cloud Integration (SAP Integration Suite) tenant using OpenID Connect protocol and then onboard the desired external Identity Providers (I will demonstrate Entra ID and Okta) as corporate identity providers in the IAS administration console.
Since I've documented the steps in my previous blog, I will not repeat the exact steps here. Please refer to the following sections in the linked blog.

Objective	Steps to follow from the linked blog
Couple your BTP subaccount and your SAP IAS tenant.	Steps 1-6
Configure applications (relying party) in Azure AD and Okta IDP based on OpenID Connect and SAP IAS as the callback URI.	Steps 7 - 25
Configure application in Okta with SAML Trust to SAP IAS.	Steps 26 - 33
Onboard the above Corporate Identity Provider configurations into SAP IAS.	Steps 34 - 46
configure IAS as the proxy Identity Provider and SAP BTP as the Service Provider.	Steps 47 - 52

Nevertheless, here is a summary of the main steps involved in the setup.

1. The subaccount where the Integration Suite subscription exists has a 'Trusted connection' with the OpenID Connect protocol (not SAML) to the IAS tenant.

2. The IAS tenant has a 'Corporate Identity provider' connection to Azure AD (Entra ID) via a set of Application credentials and OpenID Connect protocol.

3. Notice the 'Application' settings on the Azure side. The redirect URI has been set to the IAS tenant's '../oath2/callback' segment

4. The IAS tenant has a 'Corporate Identity provider' connection to Okta IDP via a set of Application credentials and OpenID Connect protocol.

5. Notice the 'Application' settings on the Okta side. The redirect URI has been set to the IAS tenant's '../oath2/callback' segment.

6. We will not leverage this flow in our demonstration but note that it is very much possible to use SAML bindings between the Corporate Identity Provider and IAS. The federation works exactly as OIDC.

7. Next, we want to demonstrate a dynamic / Group assertion / Role Collection based user role/authorization determination. For that note that on the Azure side, we have a group called 'IntegrationDevelopers' that contains the users who must be authorized to call the IFlow / API on the Cloud Integration side.

8. Notice how the 'groups' claim on the IAS side resolves to the value of the group from Azure.

9. Similarly, see that the target user has been assigned to the 'IntegrationSuiteDevelopers' Group in Okta.

10. Okta presents the user's 'Groups' claim to IAS that XSUAA will resolve in a later step.

11. As a last configuration step, notice that there is a RoleCollection on the BTP side (with the 'MessagingSend' role assigned) mapped to the respective groups from the source identity providers.

Step 2 & 3: Initiate the client flow.

The easiest way to demonstrate a client flow is to do so in Postman which natively supports simulating an OAuth 2.0 3-legged Authorization Code grant flow. We can break down the segments of the 3-legged flow in a browser as well. I will demonstrate both of these user agents.

Summary of the steps about to be performed in this section

Objective	Steps
Use Postman to set up Authorization Code flow with Okta Identity Provider	1-8
Use Postman to set up Authorization Code flow with Entra ID Identity Provider	9
Usage of Refresh Tokens	13-14
Use Browser to set up Authorization code flow with Identity Providers	15-18

1. Within the 'Authorization' tab in Postman, set the 'Type' to 'OAuth 2.0' and the 'Grant type' to 'Authorization Code'.

2. Enter the values for the Callback URL, Auth URL, Access Token URL, Client ID, Client Secret from the values saved in the Step 0 block above.

3. Click on 'Get New Access Token'. Make sure to turn on the 'Console' tab at the bottom to keep track of requests and responses across the wire.

4. Postman will launch the Logon pop-up from BTP's Authorization Server. Notice that you are presented with a list of Identity Providers to log into as configured in BTP's Trust Management section. Select the one that corresponds to your IAS Tenant.
Pay attention to the GET requests in the Console tab. You will see that the request to the 'authorize' resource is being redirected to the login page.

5. The system will prompt you to present the user identifier, this will serve as an input to the 'Conditional Authentication' block set in the IAS tenant to resolve which corporate identity provider to redirect to, for the user logon challenge.

6. The system determines that the challenge should come from Okta IDP for my *.sap.com user name. Please refer to the 'Conditional Authentication' screenshot to get a summary of the determination process.
In the 'Console' section, make a note of how the callbacks are handled.

Conditional Authentication section in SAP IAS

7. Okta will authenticate the user and present back the 'authorization code' to IAS.

8. Finally the client will exchange the authorization code for the access token from the configured token endpoint.

9. Let us now perform steps nos. 3-8 again, but this time let us log in with our *.outlook.com user that gets authenticated and authorized from Entra ID (Azure AD).

10. Upon inspection, you will note that the access token issued by XSUAA has the 'ESBMessaging.send' scope as determined by the 'Groups' claim presented by the source IDP. You will remember that we created a mapping for this resolution in a previous step. Also, note that the system bears a refresh_token.

11. Further, if you inspect the respective JWTs issued by Okta and Entra ID, you will see that the tokens contain the claims that represent the Groups, RoleCollections, and User Identifier info.

12. Simply go ahead and 'Use Token' to load the token to make your request.

13. Using the refresh_token -> Notice that the token will expire after a set duration (based on the 'expiry' setting). As you can see in the screenshot below, Postman detects that the available token is expired. It gives an option to 'Refresh' the token. Click on this button.

14. Make a note in the Console tab that the client POSTs to the token endpoint with the available refresh_token and the refresh_token grant_type to get a fresh access token.

15. In the next screenshots, let us perform the same set of steps in a browser. We will need to frame the URL to the /oauth/authorize endpoint. The easiest way to do so would be to copy the URL from the Postman Console we referred to before. The URL is in the format :

https://<tenant-id>>/authentiation.<dc>.hana.ondemand.com/oauth/authorize?
response_type=code&client_id=<url-encoded-client-id>&redirect_uri=<url-encoded_redirect_uri>

16. Invoke the URL in a browser.

17. After the 'login' and 'authenticate' procedures, you will see that the browser is redirected to the redirect_uri location. You can copy the 'code' parameter from the URL.

18. Go back to Postman and POST the Access Token endpoint with the grant_type set to authorization_code and the copied code and the redirect_uri. The server will respond with the access_token with the same set of attributes populated as demonstrated in Step 11.

Step 4: Integration Flow Reciever side propagation

Now that we have an access_token that can be presented to the Cloud Integration runtime (to a 'Sender Adapter'), let us put together a simple IFlow that can demonstrate the fact that the user's identity from the external identity provider can be propagated to 3 backend systems - a) S/4HANA Onpremse, b) SuccessFactors and c) S/4HANA Cloud via Principal Propagation and OAuth2SAMLBearer mechanisms respectively.

Here is a summary of the steps we intend to achieve:

Objective	Steps
Create a sample IFlow that demonstrates the user propagation sequence to 3 different types of backend systems.	1-2
Invoke S4HANA Cloud backend	3 - 7
Invoke SAP SuccessFactors backend	8 - 13
Invoke SAP S/4HANA Onpremise backend	14 - 17

1. Let's start by putting together a simple IFlow to illustrate the user propagation flow. Since we are planning to invoke with 3 backends, the quickest way to demonstrate this would be to create a Router that has 3 branches. Each with a 'Request-Reply' step for the backend type, S/4HANA Cloud, SuccessFactors, and S/4HANA OnPremise respectively.

2. The logic we will follow is that the client passes a value in a custom header named 'target' that shall determine which of the routes is to be invoked.

3. In the property sheet of the HTTP Receiver for S/4HANA Cloud backend, notice that we've used a credential named 's4hanaCloudCredentials' with the OAuth2 SAML Bearer Assertion type.

4. I will not get into the details behind how the attributes of this Security Material have been formulated. Refer to parts of this blog post for details. The points worth mentioning here are that a) we are using the target system type SAP BTP (CF) and b) the 'userIdSource' attribute is annotated for 'email' & nameIdFormat is set to 'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress', thereby implying that the user identifier from our original JWT token negotiated with the corporate identity provider will serve as the user principal to be propagated.

5. Let us make a call to the IFlow URL with the access token set from step 8 described in the above section. Note that we've set the 'target' header attribute to 's4hanacloud' so that the call gets executed in the first route. We get an HTTP 200 OK and the service document as the response and there you have it! We were able to successfully propagate the user from an external identity provider and execute a call in an S/4HANA backend with the user's context.

6. How do I prove my point that the user was indeed propagated? The next two screenshots do so. Note that on the S/4HANA side, I have a 'Business User' that bears my (that is propagated from Okta) emailID. Also, note that the HTTP Call is executed with this user context and NOT with a Communication User (technical user) attached to the Communication Arrangement.

7. Further to prove my point, I execute step no. 5, this time by presenting my *@outlook.com user (that comes from Entra ID), you see that the call fails and the error description calls out that the backend was not able to resolve the presented *.outlook.com user.

8. Let us now look at the 2nd route, the one that invokes a SuccessFactors URL. We extend the same 'OAuthSAMLBearer Assertion' type with a credential named 'SFSFUserPrincipal'. On the processing tab, you will see that I'm invoking a GET Query on the JobProfile resource.

9. In the details of the Security Material, note that we've set the attributes per SuccessFactors documentation. The User ID is set for principal propagation. Like before, we've used the same nameIdFormat as set in step 4 above, and don't forget to include the apiKey attribute as well.

10. Let us now invoke the IFlow, this time around with the header 'target' set to 'sfsf'. I get back a response from SuccessFactors with the JobProfile details.

11. Again, how do we prove that the call indeed was made in the signed-in user's context? There are many ways to establish this. A simple way I followed was to put a 'proxy' layer like API Management before the call hits the SuccessFactors backend and print out the 'Bearer token' from the 'Authorization' header. Upon Base64 decoding the token, you will see that the token bears a 'sfPrinciple' attribute with the employee ID identifier.

12. Look up the employee profile of the user in question in your SuccessFactors tenant and you can verify the matching employee ID and the corresponding email address.

13. Negative testing -> If I perform the call again, this time by signing in with the email address from Entra ID you should see a 401 unauthorized exception stating that the propagated user wasn't resolved.

14. Finally, we are down to the last segment of our testing. A connection to S/4HANA On-premise. I've configured an SAP Cloud Connector and an X.509 certificate signing procedure (that is beyond the scope of this demonstration) and have dialed 'Principal Propagation' for the authentication type.

15. Invoking the client this time around with the 'target' header set to 's4hanaonpremise'. I get back a response from the server with my service document for the invoked GWSAMPLE_BASIC OData service.

16. As a quick verification step, let us go to the 'Monitor' section in the Cloud Connector and within the 'Most Recent Requests' tab, you can see a record for the 'User' that was propagated.

17. Open the LJSTrace log file and you can hunt down a log entry that corresponds to the user subject that was propagated via the short-lived x.509 certificate.

Phew!

Summary:

It is beyond doubt that 'client credentials' and 'x.509 certificate' are the two most prominent and widely popular ways to authenticate to an Integration Flow / API artifact in SAP Integration Suite, but should you have a requirement to authenticate and authorize with the client user's identity from a corporate Identity Provider, OpenID Connect support from SAP Cloud Identity Service along with the Authorization Code grant type in SAP Integration Suite provide an excellent and out-of-box approach to get your job done.

Cheers, and more power to the SAP Integration Suite Community!

10+ ways to reshape your SAP landscape with SAP Business Technology Platform - Blog 5

2024-04-18T11:57:49.712000+02:00

Blog 5: How hybrid Integration upholds the role of Clean Core

Summary: In this blog series we will look at the role of the SAP Business Technology Platform in reshaping your SAP landscape including SAP and Non-SAP systems. In this seventh blog we’ll look into the important role of integration in terms of clean core and the overall transformation journey.

We’ve learned about the The Central Role of Clean Core in the first issue of this blog series. The concept of a clean core refers to keeping the core ERP such as SAP S/4HANA as up to date, unmodified, documented, consistent, efficient, and cloud compliant as possible. And while extensions - either as in-app or side-by-side - probably come to mind right away when talking about these topics, it’s imperative to apply the same guiding principles to integration.

Being Aware: A Broader Perspective

Some of the more severe technical debts in terms of integration include an existing, oftentimes rich SAP Process Orchestration (SAP PO) landscape, which is going to be out of mainstream maintenance until 2027, along with the Business Suite 7. On top of that there’s usually a multitude of non-SAP Adapters and Connectors, probably collected from multiple vendors and solutions over the last decade(s), which have created not only duplications, but also technical-, as well as commercial- and knowledge lifecycles. The Assessment-, Migration and ISA-M- Tooling as well as the SAP Edge Integration Cell will make this transitions as plannable and digestible as possible and are all included with the SAP Integration Suite.

The significance of integration extends far beyond the migration and modernization phase.
APIs have become ubiquitous across the technological landscapes, forming the backbone of communication and service delivery and must be centrally secured, monitored and documented. But modern API-Management is not just about managing technology - it's about managing business outcomes. It enables organizations to leverage the full potential of their digital assets, create expansive ecosystems, and deliver exceptional user experiences while achieving and maintaining security, compliance, and performance.

Decoupling for Flexibility and Agility

Staying as close as possible to the standard through decoupling go hand in hand with the SAP Business Technology Platform (BTP). In terms of integration the hybrid PaaS/on-prem runtime SAP Integration Suite covers all kinds of cloud-to-any as well as ground-to-ground integration needs.

With its comprehensive integration capabilities, the SAP Integration Suite provides the following contributions and qualities:

“Standard” in terms of integration

In the ongoingly updated SAP Integration Strategy Paper Christian Klein, Juergen Mueller and Thomas Saueressig have outlined the SAP road map towards an integrated intelligent suite and declared SAP Integration Suite as SAP’s strategic standard. Check out the updates regularly and learn about the most recent integration highlights.

Documentation and Consistency

Documentation: ISA-M is an invaluable open framework and toolset included even with the free plans of Integration Suite and helps in defining and standardizing integration strategies,
-styles and -practices. By providing a clear structure and methodology for SAP as well as non-SAP requirements and technologies, it ensures that all processes like integration governance, integration quality assurance- and responsibilities are defined and documented consistently and are backed by corresponding best practices and reference architectures.
Consistency, Governance and Monitoring: an integrated and complete suite of tools for centralized connection, mapping, transformation, management, monitoring and governance of integrations, providing a single pane that helps maintaining all styles of integrations and keep consistency across the enterprise landscape.

Efficiency and Cloud Compliance

Instead of just providing templates (which is the industry standard), the SAP Integration Suite provides curated out of the box content, for example in the form of more than 3’400 integration process flows. Let’s say you’re using one of those standard iFlows to easily filing your companies annual tax returns to the government and said government changes/adds requirements - either from a technical and/or compliance point of view, SAP is usually going to adapt to these changes and will refactor/change, test and update that iFlow at no additional cost.

Cloud-Native Integration: As a cloud-native solution, the suite facilitates modern cloud principles, ensuring that the core system is efficiently integrated with cloud services without requiring any modifications to the core. The Edge Integration Cell follows the same design principles and provides an on-prem runtime, usually at no additional cost

Keeping the Core Clean

Get started quickly with predefined process integrations for the most commonly used scenarios, including APIs, events, and well-documented integration flows to integrate SAP applications as well as third-party applications with minimal effort. Benefit from aligned domain models to synchronize master data objects between different LoB’s
Graph: Extending traditional API Management, Graph enables you to abstract the landscape, share data by removing and/or extending data sets for different use cases, connect all major SAP business objects out of the box while hiding the landscape complexity (replicated, distributed, or shared data).
Decoupling Extensions: By allowing businesses to build extensions and custom applications outside the core ERP side by side on the BTP, the suite ensures that the core remains unmodified, which is a key aspect of the clean core concept.

Conclusion

Preparing for the Future

The combination of cloud computing, a clean core strategy, and the move to SAP Integration Suite as one central, hybrid iPaaS positions businesses for future growth, market dynamics and innovation. It lays the groundwork for quickly adopting emerging technologies like AI, machine learning or event driven architectures as well as the next big thing to stay ahead in the digital race!

Links:

Your success is our mission. You are wondering when, what, and how to transform to be well equipped for your changing business needs? SAP is here to guide you through your transformation and to support you along the way. Download the Document

SAP Integration Solution Advisory Methodology (ISA-M)

Integration Software | SAP Integration Suite

Integration Assessment provided by SAP BTP

SAP Business Accelerator Hub.

Events

To get more insights, please also visit one of our BTP Innovation Days:

Innovation Day Switzerland: Bern 14-May-24 SAP | SAP BTP Innovation Day Switzerland
Innovation Day Germany Essen 16-May-24 SAP | SAP BTP Innovation Day

How to host static webpages through SAP CPI-Iflow

2024-04-22T15:26:00.691000+02:00

Before walking through the solution, We will glide through How it started.

Addressing the Integration community, We have a lot of systems to connect and indeed as an integration consultant we will be having POs and CPI systems to access them we will be using bookmarks and find it difficult to remember and open them at first glance.

As an enthusiastic integration consultant, I wanted to access the systems with in single click. I built a webpage with the help of Chat-GPT and wanted to host it but was not sure to host it on the internet and expose the domains.

Discussed the same with teammates and one of the teammates came up with a solution why can’t we do this with CPI, We will host it through CPI.

How to achieve this?

It is assumed that you have the HTML5 code in a single file already. You need to copy the HTML content and encode this to base64 (using an online tool) and copy the base64 encoded string to Notepad or any IDE of your choice.
Please save the Base64 code in a header as below.Content Modifier
COpy the below groovy script to decode the Base64 to HTML script.

import com.sap.gateway.ip.core.customdev.util.Message
import java.util.HashMap
import java.text.SimpleDateFormat
import java.util.Base64;
def Message processData(Message message) {
    
    def staticContent = message.getProperties().get("HTML_CONTENT");
    
    
    //Parse static content
    Base64.Decoder decoder = Base64.getDecoder();
	staticContent = new String(decoder.decode(staticContent));
   
    message.setBody(staticContent.getBytes("UTF-8"));
    message.setHeader("Content-Type", "text/html; charset=utf-8");
    return message
}

4.Deploy the iflow, copy the HTTPS URL, and hit it from the browser, you can access your webpage. 5. In case you're getting a CORS error, Please use API management to surpass it.

Let me know if you have any queries and please share your interesting findings as well! You can contact me on LinkedIn regarding the same! Until then stay tuned!

Supporting Multiple API Gateways with SAP API Management – using Azure API Management as example

2024-04-25T17:02:14.909000+02:00

Introduction

APIs are the cornerstone of modern business ecosystems and are crucial in today’s digital economy. The advent of action-based generative AI, which relies on accessible and well-defined APIs, underscores the importance of composable, API-centric software architectures.

Securing, governing, and managing APIs is essential. API Management has become a recognized discipline, supported by solutions from leading vendors such as SAP, Microsoft, Google, IBM, Salesforce, among others. API Management fosters an ecosystem where authorized developers can access and consume carefully curated and secured collections of APIs.

The essence of API management solutions lies in their ability to regulate access, authenticate and validate API calls through an API Gateway, a proxy solution deployed between API consumers and the service endpoints themselves.

Traditional API Management solutions relied on a single, central API gateway, set up in proximity to the APIs they safeguard. However, this simple architecture is less common today, due to the distributed nature of cloud software applications; customers deploy a growing number of distributed API gateways.

For example, SAP’s API Management solution, a capability of the SAP Integration Suite, provides API gateway functionality as a service available in over twenty regions around the world, as well as self-hosted options for on-premise or private-cloud deployments. This offers customers more flexibility on where to deploy API gateways.

Customers of SAP API Management may, additionally, use API gateways from other vendors and cloud providers like Microsoft Azure. But this presents a new challenge: while there may be multiple API gateways, customers still want to present the managed API information in a unified and centralized API catalog.

To address this, SAP and Microsoft have partnered, sharing programmatic interfaces to facilitate a cohesive API catalog.

This blog targets SAP Integration Suite customers utilizing the SAP API catalog (API Business Hub Enterprise) as their central repository for all APIs, accessible through a developer portal or directly via SAP Build development tools (SAP Build Apps, SAP Build Code, SAP Build Process Automation)

We introduce an extensible API import utility which streamlines and automates the process of importing, registering and publishing additional APIs into the central catalog, such as APIs managed by other vendors, or found in other external catalogs. Here, we focus on Microsoft’s Azure API Management as an information source, but the API import utility can be easily adapted to automate the import of APIs from any other source. For further details, please reach out to us.

A companion blog by our Microsoft friends details how APIs managed by the SAP API gateway can be imported to the Azure API Center, a new central catalog offering from Microsoft.

Automated API import

SAP API Management designates APIs that are not safeguarded by an SAP API gateway as “externally managed” or “unmanaged" APIs. Such APIs can be imported and listed in the API catalog and developer portal, and then optionally further enhanced or managed via API proxies, for instance to ensure that all APIs of the organization share the same security policies and common URL addressing.

While it is straightforward to manually specify a few individual unmanaged APIs and keep these specifications up to date, it becomes a daunting challenge for larger collections of APIs, especially those managed by a non-SAP API gateway.

This blog outlines an extensible API import utility that automates the process of importing, registering and publishing APIs into SAP API Management. The utility employs a “factory” design pattern implemented as an integration with Microsoft’s Azure API Management.

Available as a stand-alone open-source portable Java application, the API import utility can be executed from a desktop, but it is more likely that you will want to incorporate it into a regular workflow or CI/CD pipeline, in order to ensure that the API catalog remains up to date.

Accessing the API Import Utility

Essential tools for using the API Import Utility include:

Git
Java 11+
Maven 3.9+

The code is available here: https://github.com/SAP-samples/api-management-api-import-utility.

Overview

The API import utility was developed by our SAP colleagues Soumen Gosh and Bibin Thomas. It comprises two main components. The api-import code-tree contains the utility’s main class and entry point, in APIImportApplication.java, and the various functions for intefacing with the SAP API Management catalog.

The common interface (IRepositoryService) required by the “factory” in APIDiscoveryFactory.java is simple, and consists of three functions:

public List<API> getListOfApis()

public API getApi(String apiIdName)

public APIDefinition getApiDefinition(API api)

The implementation of these functions for Azure API Management is located in AAMApiRepository.java, in the AAM code-tree. The implementation adheres to the API service documented here: https://learn.microsoft.com/en-us/rest/api/apimanagement/api-management-service.

The following simplified illustration demonstrates the main flow:

The utility fetches the APIs from the Azure API Management and makes them available in SAP API Management as unmanaged APIs. In addition, by default, all imported APIs are added to a new product (a grouping of related APIs) called AAMProduct (you can change this default name in the AAM_product_description.json file in the conf folder).

Building the code

At the root of the code-tree, execute: mvn clean install
This creates a runtime folder: ./target/app with two subfolders, lib and conf.

Preparing Access to Azure API Management

Access to Azure API Management requires an Azure API Management account and the appropriate roles. You will need an Azure Entra ID (formerly known as Azure AD) service principal (for more information, see https://learn.microsoft.com/en-us/purview/create-service-principal-azure).

The command to create a service principal and configure its access to Azure resources is as follows:

az ad sp create-for-rbac --scopes /subscriptions/<subscriptionId> --role Contributor

For more information, see https://learn.microsoft.com/en-us/cli/azure/ad/sp?view=azure-cli-latest#az-ad-sp-create-for-rbac

The command response will be something like this:

Save this response in a file called AAM_connection_details.json, in the conf folder created in the build step above (replace the existing file placeholder).

Prepare access to the SAP API management catalog

Accessing SAP API management requires access to an SAP Business Technology Platform (BTP) subaccount, with an installed tenant of the SAP Integration Suite with activated API Management. You will need to generate a service key, which provides trusted access to the public APIs of SAP’s API Management. This process is explained here: https://help.sap.com/docs/integration-suite/sap-integration-suite/api-access-plan-for-api-portal . The resulting service key looks like this:

Save this result as a file called SAP_service_key.json, in the same conf folder created above (replace the existing file placeholder).

Running the API import utility

From the app folder, execute:

java -cp api-import.jar;lib/* com.apimgmt.gateway.APIImportApplication

The utility fetches the APIs and makes them available in SAP API Management as unmanaged APIs. In addition, by default, all imported APIs are added into a new product (a grouping of related APIs) called AzureAPIs.

It is up to you to decide if you want to take additional steps, such as adding an API proxy for any of the imported APIs.

Developers browsing the SAP API Management API catalog will see a new product tile representing this product grouping:

Conclusion

The API catalog of SAP API Management serves as a centralized listing for APIs managed across distributed and private-cloud API Gateways. The blog demonstrates how to seamlessly list “externally managed” APIs from various sources, enhancing them to conform to organizational security and compliance standards, and providing a consistent URL schema for all APIs.

The integration of APIs from SAP API Management with those from other gateways or repositories allows for the creation of intricate, distributed application architectures while preserving the vital role of a centralized API catalog.

Contacts

soumen.gosh@sap.com, chaim.bendelac@sap.com, mapankra@microsoft.com

Govern SAP APIs living in various API Management gateways in a single place with Azure API Center

2024-04-26T12:33:48.591000+02:00

Find the GitHub repos associated with this post on Azure API Center here.

Our engineering friends from SAP Integration Suite– in particular @Chaim_Bendelac – published a nice “sister blog” on supporting Azure API Management with the API Management capability of SAP Integration Suite here.

Dear community,

Many of you are heavily invested in APIs regarding your SAP ecosystem and the rest of your IT real estate. Given the integration specialization in the SAP space companies decide to use more than one integration tool to cater for SAP and non-SAP integrations. Gartner even says that 75% will use at least two different ones. For many of you that means SAP Integration Suite plus one for non-SAP.

Due to the fast-paced growth of APIs within organizations, inventory, governance, security, and management cannot keep up. The resulting fragmentation and inconsistency lead to adoption challenges, project delays, and security risks. Postman’s State of APIs report 2023 shows that API security incidents happen frequently.

These challenges are summed up under the term “API Sprawl” by the industry. Beware the API sprawl monster is upon you!

fig.1 Illustration of API Sprawl challenge

Key to survival is automatic discovery of available APIs and a single place to enforce guidelines from, or at least know these unmanaged APIs exist in your estate. Forgotten APIs are low hanging fruit for attackers. To drive home that argument: “Improper Inventory Management” made the OWASP top 10 list for API Security in 2023.

Besides that on the human side of things: Which developer likes to develop duplicate functionality just because of the lack of shared API inventory to discover existing stuff?

The API Sprawl monster🦖 much hungry! “Nomnom nomnom more food, yes more food!”.

Azure API Center embarked on the journey of taming the monster.

What API solutions can be registered to Azure API Center?

Azure API Center applies to any API and any API management solution out there. Always remember that API Center is not an API Gateway! It doesn’t expose the endpoints or apply policies to them. That stays with the API Management provider. API Center makes them discoverable and allows decorating APIs with additional info to improve governance.

Let that sink in.

My colleagues are building integrated experiences for the most interesting API and integration tool providers. However, API-based registration in API Center will always be possible.

Get it? APIs to register APIs to register APIs ... yah maybe to complicated for a joke.

fig.2 Azure API Center solution coverage overview

The focus of this blog post will be on inventorying APIs hosted by the API Management capability of SAP Integration Suite to mitigate SAP API sprawl. However, the approach described is applicable to all the other SAP APIs out there hosted on SAP Gateway, SAP Graph, SAP CAP, SAP RAP, CloudFoundry, Kyma, etc. too.

Another prominent SAP service would be SAP Cloud Integration (formerly CPI – Cloud Platform Integration). Many of you expose APIs internally or to business partners through SAP integration flows without fronting them with an API Management solution – you know who you are 😉. Those can be registered too. Unfortunately, there is no built-in option to retrieve the definition of such an endpoint. You may generate an API definition for your http trigger using payload samples for instance. I found this repo useful to get an overview on how to generate OpenAPI definitions from JSON payloads.

Even if you don’t, putting the available metadata on the Azure API Center inventory still improves discoverability and enterprise-wide governance by magnitudes.

But now on to SAP API Management.

Automagically registering SAP API Management APIs on Azure API Center

Our starting point is the SAP BTP service apimanagement-devportal. Check SAP’s docs on the setup process here. Make sure you don’t mistakenly choose apimanagement-apiportal.

The API “API Business Hub Enterprise - Discovery Service (CF)” enables querying all available APIs hosted on SAP API Management on that subaccount. It holds info about their OpenAPI definitions.

Authenticate on the service with any of the supported authentication mechanisms. I chose OAuth2 client credentials grant (instance secret – without payload).

See below response from “/apidiscovery/v1/apis” from my SAP BTP sandbox environment. Pay attention to the attributes of “apiDefinitions” and values for “oas-json”.

{
"@odata.context": "$metadata#apis",
  "value": [
    {
      "name": "GWSAMPLE_BASIC",
      "title": "GWSAMPLE_BASIC",
      "version": "1",
      "lastUpdated": "2024-01-24",
      "releaseStatus": "PUBLIC",
      "protocol": "ODATAV2",
      "entryPoints": [
        {
          "name": "GWSAMPLE_BASIC",
          "type": "PROD",
          "url": "https://msftapim.test.apimanagement.eu10.hana.ondemand.com:443/GWSAMPLE_BASIC"
        }
      ],
      "apiDefinitions": [
        {
          "type": "oas-json",
          "url": "https://eu10devportal.cfapps.eu10.hana.ondemand.com/odata/1.0/data.svc/APIMgmt.APIResourceDocumentations('2797A5F5-E18A-4FCC-826A-C833845303F5')/content/$value"
        },
        {
          "type": "edmx",
          "url": "https://msftapim.test.apimanagement.eu10.hana.ondemand.com:443/GWSAMPLE_BASIC/$metadata"
        }
      ]
}

For your convenience we have provided a sample repo that runs Infrastructure-as-Code scripting to register the SAP APIs using their OpenAPI definitions as highlighted above. On each SAP API definition we execute registration requests on Azure API Center.

You may also use Postman, or SAP Build Process Automation etc. to execute the REST API calls if you prefer. Find our collection here.

fig.3 Flow of automated API registration in Azure API Center

Discover all your APIs where you code – see VS Code and GitHub Copilot in action

We developers like to stay within our flow. So, having the API inventory available at my fingertips in VSCode is a good step into that direction. Also generating http requests to poke around the service and API clients is nice 😎Kiota supports a multitude of languages for SDK generation.

To get that going install the Azure API Center portal VSCode extension.

fig.4 Screenshot of VSCode extension with example OpenAPI definition

Please note that the authorize button (and respective authentication scheme) on the OpenAPI definition explorer is only available if present on the definition file. It looks like this for Basic Auth:

fig.5 Screenshot of auth definition in example OpenAPI spec for SAP OData service

When using the http file and the REST client extension of your choice, you may simply provide the authentication header with Bearer token etc.

Next to the Azure API Center extension view before, you can also use GitHub Copilot Chat to query available APIs from API Center. See Microsoft Learn for more samples. You may search for APIs by key words like so:

@apicenter /search business-partner

Cherry on the cake 🍰is the API Center portal for the classic developer portal experience across your whole registered API inventory wherever that is.

fig.6 Screenshot of Azure API Center portal API inventory view

So far so good on registering APIs and working off the info their definitions provide. But how about governance? I know how desperately everyone wants to plaster cost centers, line-of-business info, and security labels on your interfaces. 😏

Enforced API metadata is your second line of defense against API sprawl

In addition to simply registering APIs you may add custom properties to the object on Azure API Center. So, even if the info is not present on the API itself you can still govern it from Azure. See below sample that I created from the Microsoft Learn tutorial.

fig.7 Screenshot of Azure API Center metadata maintenance view

Knowing which APIs are public facing is useful, isn’t it?

For everyone looking for more sophisticated security with less human error surface, have a look at Defender for APIs. I like the alert rule for “un-authenticated APIs” and disabling endpoints that were not used in the past 60 days most – wait what? Those exist out there in the wild west of SAP on the Internet? 😲See the open-source automatic remediations repos here to mitigate for Azure API Management.

Defender for API integration with 42Crunch brings API security testing and hardening to your CI/CD pipeline.

API Linting gets you to the next level

OK, now let’s look at API style guide compliance. Is everyone playing by your rules? How do you make sure developers notice violations already during design phase rather than at later stages of deployment, release, or even months after the fact when audited?

Good automatic API linting creates much less hassle for everyone in the long run, less cost to fix API definitions after the fact, improved security posture, and a more rewarding experience for the people involved. See below video on the setup of the linting function for OpenAPI using Spectral linting engine.

Anyone aware of a great OData linter and would be curious to explore? Please share!

Get more details on API Linting for Azure API Center from this Microsoft Learn article.

Thoughts on production readiness

Azure API Center is in public preview but due for General Availability with the next wave of announcements, so completely ready for prime time. The same is true for the VS Code extensions and APIs used to orchestrate the integration between SAP API Management and Azure.

Intentionally registering APIs from SAP to Azure API Center improves API inventory management by magnitudes. However, shadow inventory thrives in places you don’t actively look. To mitigate even more effectively the team is building automated discovery from your GitHub org, Azure DevOps, and other popular sources.

SAP Fiori tools on VSCode provided by SAP SE enable usage of the approach described in this blog out of the box. The same is true for SAP CAP development in VSCode.

Final words

That’s a wrap🌯. You saw today how you can effectively counter API sprawl and its negative side effects that put your APIs and organizations at risk. A primary means to achieve that is creating a central API inventory hosted on all the different API Management solutions out there with Azure API Center.

This blog showed how to achieve that using the API Management capability of SAP Integration Suite as an example.

Furthermore, you learned about steps to improve API governance with custom properties and API linting. Eventually, you understood the difference between Azure API Center and an API Gateway.

Find the GitHub repos associated with this post here. It gets you started in no time.

Big #Kudos to Pascal van der Heiden – my brother in crime on this effort. And of course, last but not least to @UdoPaltzer and @vinayak_adkoli for the great collaboration! 🙌

Anyone curious to tap their toe into the waters where the API sprawl monster 🦖 lives, just reach out to me and Chaim or leave a comment.

Cheers

Martin

API Management: Unlocking OAuth Strategies

2024-04-30T15:30:43.947000+02:00

Introduction

In today's rapidly evolving enterprise landscape, the API-first approach has emerged as a cornerstone for organizations striving to stay competitive and relevant. At the heart of this approach lies API management, a central place for the orchestration, optimization, and security of APIs.

In this blog, I will elaborate the authorization considerations surrounding APIs, as well as the OAuth strategies I've investigated and encountered during my learning journey and professional experience.

If you are new to API management I highly recommend going through the help doc to get basic knowledge of API management capability before diving into this blog.

Through out the blog, I have added links to some learning journeys / blogs which you can refer. I thought this is better instead of rewriting the same content which is already well written.

I will structure the blog in below sections

Pre-requisites
Creating a simple integration flow
Securing integration flows
1. Exploring API Management OAuth Policy
2. Extending OAuth Beyond API Management
Testing steps to test both solution approaches.
Conclusion

Pre-requisites

SAP BTP account or trail account
Integration Suite Tenant with below capabilities
1. Cloud Integration
2. API Management (ensure you have proper roles assigned)
Process Integration Runtime service
Insomnia or Postman client

Creating simple integration flow

I created a simple integration flow and deployed it as a REST API in the cloud integration tenant. This integration flow does following things

1. Logs the incoming message as attachment

2. Persists the message in JMS queue

Note - This is the basic integration flow. Consider it as a mock iflow which can be replaced by any other iflow based on the business use case.

Figure-1: Integration Flow

Securing integration flows

In an enterprise landscape, you will always come across situations, that you have to expose your integration flows using API management. Ofcourse Integration suite provides API management capability which can seamlessly wrap the integration flows and create an API proxy.

One of the important question always comes up - How to secure your APIs/iflows? The obvious answer is OAuth 2.0 (Open Authorization 2.0).

Here I will showcase, 2 solution approaches to secure the API with OAuth 2.0.

Exploring API Management OAuth Policy: API Management provides security policies which can be used out of the box.

Create an API Proxy. Configure -- APIs -- OAuthService. This Service will be used to generate the token. Follow Step 1 (1 - Create the Token Endpoint) from this blog
Create another API - LogMessageAPI as a proxy to the iflow. We will add token validation in this proxy. Define the API by referring the Step 2: Define the API from this learning journey.

In the LogMessageAPI:

Add policy template to the LogMessageAPI as mentioned in Step 3, 4 and 5 of this learning journey

Add VerifyAccessToken policy as the first policy in the pre-flow of the ProxyEndpoint using OAuthV2 in the LogMessageAPI proxy.

<OAuthV2 async="false" continueOnError="false" enabled="true" xmlns="http://www.sap.com/apimgmt">
   <!-- this flag has to be set when you want to work with third-party access tokens -->
   <ExternalAuthorization>false</ExternalAuthorization>
   <!-- valid values are GenerateAccessToken, GenerateAccessTokenImplicitGrant, GenerateAuthorizationCode ,
    RefreshAccessToken , VerifyAccessToken , InvalidateToken , ValidateToken  -->
   <Operation>VerifyAccessToken</Operation>
   <GenerateResponse enabled="true"/><SupportedGrantTypes/>
   <Tokens/>
</OAuthV2>

Once you deploy the OAuthService and LogMessageAPI and publish the product to API Business Hub Enterprise, you will get the application key and application secret which can be used as client id and client secret to get the token.
In this way, you can use the inbuilt OAuth policy to generate the OAuth token and to validate the token for other API proxies.

Extending OAuth Beyond API Management: Let us dive deeper into another approach where we can use the process integration runtime OAuth server to generate the token through OAuthService API.
1. Create an API Proxy. Configure -- APIs -- OAuthService.
2. Import the policy template in the pre-flow of the ProxyEndpoint. I have exported my policy template and is available in GitHub - https://github.com/avinashvaidya09/apimanagementpolicytemplate
3. Each policy is listed and briefly described below -
  1. lookupOAuthToken - Using LookupCache policy, checks if access token is available in cache.
  2. extractRequestHeader - Using ExtractVariables policy, extracts the client id and client secret from the request headers.
  3. getBTPOAuthMetadata - Using KeyValueMapOperations policy, finds the BTP oauth token url saved in the key value map
  4. setAuthorization - Using BasicAuthentication policy, creates Authorization object.
  5. callBTPOAuthService - Using ServiceCallout policy, calls external BTP OAuth token url.
  6. raiseException - Using raiseException policy, raises exception if BTP OAuth token url returns exception.
  7. extractVariablesFromOAuthResponse - Using ExtractVariables policy, extracts token response.
  8. populateOAuthToken - Using PopulateCache policy, populates access token in cache which will be used by point 1.
4. Go to your BTP subaccount -- Create instance of Process Integration Runtime.
5. Create a service key and get the OAuth metadata
  1. client id
  2. client secret
  3. token url
6. Add the token url in the key value map in API configuration to make it externalized. This token url will be used in the service call out policy - callBTPOAuthService
7. Save and and deploy the OAuthService.
8. Ensure the integration flow is deployed. Get the endpoint URL.
9. Create another API - LogMessageAPI as a proxy to the iflow. Define the API by referring the Step 2: Define the API from this learning journey.
10. In this API, you do not have to define any access token validation policy, but the bearer token will be forwarded to the integration flow and will be validated directly by process integration runtime.

Test your APIs

Download any REST client like - Insomnia or Postman.
Deploy the API proxies and get the endpoints

Testing approach - 1:
1. Go to API Business Hub Enterprise. Create Application and add the product containing both the API proxies.
2. Get the application secret and application key after the application is created.
3. Create new HTTP request for API proxy OAuthService endpoint.
4. Add client id - client id will be the application key from point 2.
5. Add client secret - client secret will be the application secret from point 2.
6. Add grant type - client_credentials
7. Add Content-Type - application/x-www-form-urlencoded
8. Get the access token.
9. Create new HTTP request with API management LogMessageAPI endpoint.
  1. Add access token
  2. Add sample JSON payload
10. Execute the request.
11. Go to integration suite - Monitor - Integration & APIs. You should see a message in the queue. Click on the message id and you will land on the executed iflow with payload attached for reference.
Testing approach - 2:
1. Create new HTTP request with API management OAuthService endpoint.
2. Add client id - client id from process integration runtime service key.
3. Add client secret - client secret from process integration runtime service key.
4. Content-Type - application/x-www-form-urlencoded
5. Get the access token
6. Create new HTTP request with API management LogMessageAPI endpoint.
  1. Add access token
  2. Add sample JSON payload
7. Execute the request.
8. Go to integration suite - Monitor - Integration & APIs - Message Queues. You should see a messages in the queue. Click on the message id and you will land on the executed iflow with payload attached for reference.

Conclusion

Drawing from my experience, I must emphasize that these insights can serve as a starting point, though their applicability may vary based on specific scenarios.

This is just a glimpse of wide set of capabilities offered by SAP Integration Suite and API management. Stay curious! Keep learning!

To get more updates about this topic, please follow the below pages

Feel free to “like“, “Share“, “Add a Comment” and to get more updates about my next blogs follow me – avinash.vaidya@sap.com

SAP Pipeline Concept and B2B TPM testing

2024-05-06T07:30:00.023000+02:00

Abstract

With the introduction of the SAP Pipeline Concept we now have a second large use case apart from B2B-TPM which allows processing different types of messages with a set of predefined generic iflows. This blog will show a few ways how automated testing of such scenarios can be set up of the box with Int4 Shield - SAP Integration Suite testing platform and how SAP Integration Suite customers already use it for such scenarios.

SAP Pipeline Concept and B2B TPM - multiple iflows

In the pipeline concept, each step corresponds to an integration flow (generic integration flows and scenario-specific integration flows). The generic integration flows are used across all integration scenarios and must only be deployed once while scenario-specific integration flows handle the scenario-specific message conversions and mappings.

File Source: https://community.sap.com/t5/technology-blogs-by-sap/introducing-the-new-pipeline-concept-in-cloud-integration/ba-p/13639651

Similarly the B2B-TPM the exchange is divided into sender communication iflows, interchange processing and receiver iflows.

File source: https://community.sap.com/t5/technology-blogs-by-sap/use-tpm-ia-ci-to-efficiently-manage-and-run-complex-b2b-transactions/ba-p/13565068

Cloud integration is very flexible in terms of modeling and running your integration scenarios allowing the design of a rich variety of integration patterns on the other hand for some types of scenarios we may want to use a more "formal" way or processing and this is there SAP Pipeline Concept and B2B-TPM scenarios come in handy with some of it's common advantages:

a) Provide commonly used restart capabilities
b) Simplifies operations by separating errors into different generic queues
c) Require lower number of JMS queues to take into account the resource limits
d) Simplify monitoring operations
e) Allow reusability of artifacts across multiple flows by using generic (Pipeline or TPM) iflow concept

SAP Pipeline Concept and B2B TPM - testing

Since those two frameworks are going to be used more and more and they involve several iflows to be tested
is there any way to automate the testing of such integration processes? With Int4 Shield - SAP Integration Suite testing platform, there out of the box we have several ways to implement automated testing of the SAP Pipeline Concept and B2B TPM. Let me explain, how they work.

Step 1

In both SAP Pipeline Concept and B2B TPM we're working with multiple iflows so we may want to inject the test messages into a specific iflow. This can be the first iflows but does not have to be as we may want to skip testing the initial iflow in some cases.

Figure - Int4 Shield inject test message options

Step 2

Now we need to decide what do we want to test. What are the options? Basically two:

a) we can either test the whole framework (SAP Pipeline Concept and B2B TPM ) from start to finish

b) we may want to test specific iflows of the whole framework (SAP Pipeline Concept and B2B TPM)

For this purpose Int4 Shield automatically enables Trace monitoring level on tested iFlows to be able to introspect processing inside of these steps.
Thanks to this Int4 Shield can validate payload content at any single execution block of the processing steps.

Figure - Int4 Shield inject test message and trace start with validation options

Step 3

Scenario 1 (single automation object) - for simple black box testing, Int4 Shield injects the message in the initial step and awaits for logs and payload to arrive at the final processing step, capturing the output payload, as it would be sent to a target system. Single test case and single automation object is sufficient for test and validation.

Figure - Int4 Shield validation option with a single automation object

Scenario 2 (combination of automation objects - API workflows testing) - thorough testing is made possible with more test cases that execute more validation steps. In a typical scenario there is separate validation of Step 2 - to check if payload input was properly processed by Step 1 logic, and for Step 3 - to validate the output payload after mapping is correct and routed to the expected channel.

Figure - Int4 Shield validation option with a a combination of automation objects - API workflow testing

SAP Pipeline Concept and B2B TPM - framework support

Int4 Shied testing concept for SAP Pipeline Concept and B2B TPM supports:

a) Multiple adapter types : SFTP, JMS, HTTP, IDOC, ProcessDirect, SOAP
b) Enabling unit testing of specific flow components
c) Testing business flows with Inputs and Outputs from different iFlows
d) Test complete SAP Pipeline Concept and B2B TPM execution with one test case
e) Capture and test intermediate results from specific iFlow steps
f) Test complete SAP Pipeline Concept and B2B TPM execution, validating document flow through the iFlows
g) Massive and automated test case creation
h) Test case loader - mass load of test files
i) Robotic crawler - automatic capture of historical data from another integration platform
j) Test scenario builder - linking multiple test cases into test scenarios automatically based on message content (e.g. document numbers)

Additional resources

B2B/TPM on SAP BTP Integration Suite migration (SAP PO, Boomi, EDI Providers and home-grown apps)

Int4 Suite for SAP BTP Integration Suite testing fully integrated with SAP Cloud ALM

4 big waves for API led strategies and SAP BTP Integration Suite explosive growth

There is no AI without API - Integration is the backbone of digital transformations

Purchase Order via API_PURCHASEORDER_PROCESS_SRV - Example API-call

2024-05-14T14:44:51.633000+02:00

Application Programming Interfaces (APIs) allow developers to interact with SAP Gateway services and perform various operations, including creating, updating, and retrieving data. Through this practical scenario, we aim to shed light on the capabilities of the transaction /n/IWFND/GW_CLIENT and on how to leverage it effectively.

Transaction /n/IWFND/GW_CLIENT

Upon launching the t-code /n/IWFND/GW_CLIENT you will see a screen composed by three main sections. Above you have the HTTP Request URI where you can give the Service you wish to trigger. On your left side HTTP Request frame gives you the option to place your XML payload with the actual document or query. On the right side, you will see the response from the system after executing that payload.

In our example scenario, we wish to create a Purchase Order through the API service API_PURCHASEORDER_PROCESS_SRV. First the HTTP Method “POST” should be selected, then the Request URI /sap/opu/odata/sap/API_PURCHASEORDER_PROCESS_SRV/A_PurchaseOrder. As a last step, you will have to copy/paste your actual payload into the left frame blank spaces:

{

"CompanyCode": "0001",

"PurchaseOrderType": "NB",

"Supplier": "Your_TestSupplier",

"DocumentCurrency": "EUR",

"PurchasingOrganization": "0001",

"PurchasingGroup": "001",

"to_PurchaseOrderItem": [

{

"PurchaseOrderItem": "1",

"PurchaseOrderItemText": "OData API test",

"Plant": "0001",

"OrderQuantity": "1",

"OrderPriceUnit": "EA",

"AccountAssignmentCategory": "K",

"PurchaseOrderQuantityUnit": "EA",

"DocumentCurrency": "EUR",

"NetPriceAmount": "1",

"NetPriceQuantity": "1",

"Material": "Your_TestMaterial",

"to_AccountAssignment": [

{

"Quantity": "1",

"GLAccount": "Your_Test_GL",

"CostCenter": "Your_Test_CC"

}

]

}

]

}

Debugging the API-call

Just like in case of any other HTTP request, the ABAP Debugging of the API-call can be done through external breakpoints. Go to the place you wish to stop the code and place an external breakpoint on the user executing the test scenario.

In our example a good place to start is the method PO_PROCESS (class CL_PO_HANDLER_MM). This place will call the “normal” SAP Function MEPO_DOC_PROCESS. The include LMEPOF2I, PO_PROCESS will call the subsequent Functions MEPO_DOC_HEADER_PROCESS and MEPO_DOC_ITEM_PROCESS.
In case you have a Badi-specific problem, you could also stop the method IF_FLUSH_TRANSPORT_MM~START (class CL_PO_HEADER_HANDLE_MM). That place will call the BAdI-Functions MEPOBADI_PROCESS_HEADER (implementation IF_EX_ME_PROCESS_PO_CUST~PROCESS_HEADER ) and MEPOBADI_PROCESS_ITEM ( impl. IF_EX_ME_PROCESS_PO_CUST~PROCESS_ITEM ).

Creating test data for SAP cases

In case you wish to save an existing or successfully executed HTTP Request, you can simply click the “Save” button in the upper menu of the transaction. In the next selection screen, you can enter the Test group/Test case name to save your predefined set of data.

In case you already have a predefined test scenario, you can import it. On the main screen of the transaction /n/IWFND/GW_CLIENT right click in the “Test group” field and hit “Select Test case” or hit the F9 button. It will give you the same selection screen, where you can get your test HTTP request payload.

Complete XML files can also be added to the HTTP Request if you click “Add File”.