SAP API Management is made up of five components: the API Designer, the API portal, the API gateway (also called the API runtime), the Developer Hub, and API Analytics. Each plays a different role, and together they cover the full lifecycle of an API: designing it, building it, running it, letting developers consume it, and monitoring how it performs. We will go through each one, then see how they work together, and finally where you will actually spend your time.

1. API Designer: The Blueprint

The API Designer is where you need a blueprint how your API looks like: which endpoints it has, which HTTP methods it supports, which parameters it expects, and what its responses look like.

In the API Designer, you describe that API contract using the OpenAPI Specification. If you haven’t come across OpenAPI before, it is simply a standard format for describing REST APIs. You write the definition in YAML or JSON, and that definition becomes the single source of truth for your API.

Not every team uses the API Designer. Some jump straight into the API portal and start building proxies. But if you want a clean, well-documented API, starting with the design is the approach I recommend.

2. API Portal: Where You Build and Manage

The API portal is your main workspace as an API administrator, and it is where you will spend most of your time. Four things happen here:

• API proxies: you create the API proxy, the managed front door between the consumer and your backend that we looked at in the previous part.

• Policies: you attach security, traffic management, and mediation policies to that proxy.

• Products: you group APIs into products and publish them.

• Lifecycle and rate plans: you version, deploy, and undeploy your APIs, and configure rate plans if you want to monetize them.

A product is a bundle of one or more APIs that you publish together. For example, a “Sales APIs” product might contain your Sales Order API, your Customer API, and your Pricing API.

💡 Key takeaway

Developers don’t subscribe to individual APIs in SAP API Management. They subscribe to products.

If there is one component you need to know well as a developer, it is the API portal.

Read more

First, we will look at the API proxy and the path every request and response takes through it. Then we will look at policies, the configurable building blocks that actually enforce the rules, and the four categories they come in. After that, we will see exactly where inside a proxy those policies are attached. Finally, we will look at the engine running all of this, which SAP didn’t build from scratch.

The API Proxy: A Checkpoint Between Consumer and Backend

The architecture is actually very straightforward. When a developer, or any application, calls your API, the request doesn’t go directly to your backend. It goes to an API proxy first, and the API proxy sits in the middle, between the consumer and your backend system.

So the flow looks like this: consumer app → API proxy → backend API.

When a request comes in from the consumer, the API proxy intercepts it on the way in and applies your rules. It might check for a valid API key, or check whether the consumer has used up their quota. If everything looks good, it forwards the request to the backend.

When the backend sends back its response, the API proxy intercepts that too, on the way out. It can apply more rules at that point, for example converting the response from XML to JSON, or caching it for the next identical request. Only then does the final response go back to the consumer.

I find it easiest to think of the API proxy as a checkpoint. Every request passes through it on the way in, every response passes through it on the way out, and nothing reaches your backend without going through the proxy first.

Policies: The Building Blocks Inside the Proxy

Now, here is the important question. What are these “rules” the proxy applies? How do you tell it to check for an API key, limit traffic, or convert XML to JSON?

That is where policies come in. Policies are pre-built, configurable XML building blocks, and they are the core mechanism that makes API Management work. Instead of writing custom code for security or transformation, you attach a policy to your API proxy and configure it.

A few examples make this concrete:

• To make sure every incoming request carries a valid API key, you add the Verify API Key policy and configure which header or query parameter holds the key. The policy does the rest.

• To limit a consumer to 1,000 calls per day, you add a Quota policy and configure the limit and the time interval. The policy counts the calls and enforces the limit.

• To convert an XML response from your backend into JSON before it reaches the consumer, you add an XML to JSON policy and configure the conversion options.

Example Policy Code Block - Verify API Key

<!--Specify in the APIKey element where to look for the variable containing the api key--> 
<VerifyAPIKey async='true' continueOnError='false' enabled='true' 
xmlns='http://www.sap.com/apimgmt'>
	<APIKey ref="request.header.apikey"></APIKey>
</VerifyAPIKey>

This policy block expects the request to come with a valid API key in the header parameter. The name of the header parameter should be apikey.

In SAP API Management, you don’t write code to secure, throttle, or transform an API. You configure policies and attach them to the API proxy.

Policy Editor Sample in SAP APIM

Notice there are three policies added to the request flow, including the Verify API Key policy with the policy code block configured.

The Four Policy Categories

SAP provides more than 30 policy types out of the box, and the policy editor groups them into four main categories.

1. Security Policies

Security policies handle authentication, authorization, and protection against malicious requests and payloads. This is where you find Verify API Key, OAuth 2.0, Basic Authentication, and threat protection policies such as JSON Threat Protection.

In my experience, this is the category you will reach for most often.

2. Traffic Management Policies

Traffic management policies control how much traffic flows through your API. The two you will meet first are Quota and Spike Arrest, and they are easy to confuse, so let’s take them one at a time.

Imagine you give a developer access to your API and tell them they can make up to 1,000 calls per day. That is a Quota. Once they reach 1,000, the API returns an error for every further call until the quota resets the next day. It works like a prepaid data plan on your phone: once your allocation is used up, you wait for it to reset.

Spike Arrest solves a different problem. Let’s say your backend comfortably handles 10 requests per second, and suddenly a consumer sends 500 requests in a single second, maybe because of a bug or a runaway retry loop in their code. Spike Arrest lets only the configured rate through and rejects the excess requests with an error, so the burst never reaches your backend. The consumer isn’t locked out for the day the way Quota does it; their calls simply succeed again as soon as the traffic drops back under the limit.

3. Mediation Policies

Mediation policies modify the request or the response as it flows through the proxy. Three you will use constantly:

• Assign Message adds, changes, or removes headers, query parameters, and even the whole message body. For example, you can add an authentication header or a tracking ID before the request reaches the backend.

• XML to JSON converts the backend’s XML response into JSON on the fly, so a mobile app that expects JSON gets it without anyone touching the backend service setup.

• Extract Variables reads the payload, pulls out a specific value such as a customer ID, and stores it in a variable that other policies can use later in the flow.

4. Extension Policies

Sometimes the built-in policies don’t cover a very specific piece of logic. For those cases, extension policies let you write a short JavaScript or Python Script and attach it to the proxy like any other policy. The flexibility is there when you need it, but for most use cases the built-in policies are more than enough.

In this series of articles, we cover the most important policies from each of these categories, hands-on.

Where Policies Attach: Proxy Endpoint and Target Endpoint

So where exactly do these policies sit? Inside every API proxy, there are two main sections.

The ProxyEndpoint is the consumer-facing side. This is where the request comes in and the response goes out, so policies attached here deal with what happens between the consumer and the gateway.

The TargetEndpoint is the backend-facing side. This is where the gateway talks to your actual backend API, so policies attached here deal with what happens between the gateway and the backend.

Each endpoint has its own request flow and response flow. That gives you four points where you can attach a policy: the proxy request, the target request, the target response, and the proxy response.

This is what gives you fine-grained control over exactly when each policy runs. We will go much deeper into this in the chapter on proxy flow and policies; for now, the thing to remember is that policies are the building blocks, and the proxy flow is where you place them.

The Engine Underneath: Google Apigee Edge

One more thing worth knowing: under the hood, SAP API Management is built on an OEM version of Google Apigee Edge.

In other words, SAP didn’t build the API gateway engine from scratch. It licensed the technology from Google, integrated it into SAP Integration Suite, and added its own tooling, monitoring, and developer experience on top. When you work with SAP API Management, the gateway processing your API calls is Apigee underneath.

That matters to you for two reasons. First, the platform is enterprise-grade and proven at scale, not a new and untested technology. Second, and this is the one I find most useful day to day, when you search for help online and land on Apigee documentation or community posts, a lot of that knowledge applies directly to SAP API Management. The policy names, the XML configuration syntax, and the flow variables are largely the same, so you have a much bigger knowledge base to draw from.

Summary

The key concept is the API proxy: it sits between the consumer and your backend and intercepts every request and every response. Inside the proxy, you attach policies, pre-built and configurable building blocks for security, traffic management, mediation, and extension. You don’t write code; you configure policies. And the engine running all of it is Google Apigee Edge.

In the next article, we will look at the five components of SAP API Management, the tools you will actually use to design, build, run, publish, and monitor your APIs.

If you have any questions about API proxies, policies, or how the proxy flow works, please leave a comment below. I will be happy to help.

📚 SAP AIF Configuration Series - Guide #5

We are configuring default values on top of the iDoc interface we developed in our previous guides.

If you are new here and would like to see the previous articles, check out the following guides.

1. How to Configure your First IDoc Monitoring Interface in AIF.

2. How to Configure Fixed Values in SAP AIF

3. Implement a Single Value Mapping in AIF

4. Develop an SAP AIF Multi-Value Mapping

Default Value in SAP AIF Value Mapping

Introduction

In the previous chapter, we configured a multi-value mapping that determines a customer discount based on the ISO country code (E1SCU_CRE-E1BPSCUNEW-COUNTR_ISO) and customer type (E1SCU_CRE-E1BPSCUNEW-CUSTTYPE) of the incoming iDoc. That works perfectly as long as the incoming combination exists in the mapping table. But what happens when a customer arrives from a country that hasn’t been mapped yet?

By default, AIF will raise an error and the IDoc will not be processed. That’s the safe option, but it’s not always what the business wants. Sometimes you’d rather the customer gets created with a sensible fallback discount rather than failing completely.

This is exactly what a default value in SAP AIF is for. When a value mapping lookup fails to find a match, AIF can fall back to a predefined default value and continue processing the message successfully.

Get the full ebook!

Scenario

We are building on top of the II_FL_CUST interface in namespace ZDEMO and the multi-value mapping VM_DISCOUNT from the previous chapter.

The new requirement is simple: if an incoming customer’s country and type combination is not found in the VM_DISCOUNT mapping table, AIF should not raise an error. Instead, it should assign a default discount of 2 to the E1SCU_CRE-E1BPSCUNEW-DISCOUNT field and continue creating the customer.

This gives us a safe fallback that keeps the interface running even when new country codes appear in the data that haven’t been mapped yet.

Prerequisite

The multi-value mapping VM_DISCOUNT must already be configured as described in the previous chapter. The field mapping for E1SCU_CRE-E1BPSCUNEW-DISCOUNT referencing VM_DISCOUNT must be in place under Define Field Mappings for interface II_FL_CUST.

What Is a Default Value in AIF?

A default value in SAP AIF is a fallback that is applied to a destination field when the associated value mapping cannot find a matching entry for the incoming data. Instead of putting the message into error status, AIF uses the default value and marks the message as successful.

It is configured directly on the field mapping entry.

💡 Tip

Default values are particularly useful in interfaces where data quality from the source system is inconsistent. Rather than blocking every message with a missing mapping entry, you can apply a safe default and let the interface team clean up the mapping table without causing a backlog of errors.

Step 1 - Add the Default Value to the Field Mapping

Transaction: /AIF/CUST → SAP Application Interface Framework → Interface Development → Define Value Mappings

Navigate to Define Field Mappings for interface II_FL_CUST, namespace ZDEMO, version 1. Find the existing field mapping entry for the destination field E1SCU_CRE-E1BPSCUNEW-DISCOUNT - this is the entry we created in the previous chapter that references value mapping VM_DISCOUNT.

Alternatively, you can go to Interface Development → Define Value Mapping to access the value mapping directly.

Select the value mapping VM_DISCOUNT. Open the entry and set the Default Value field to 2.

Save your changes.

💡 Tip

The default value must be a valid internal value for the destination field; the same type and format as the values in the Internal Value column of your mapping table. For the DISCOUNT field, this is a numeric value, so entering 2 tells AIF to assign a discount of 2 whenever no matching mapping entry is found.

Step 2 - Test the Interface

Let’s create a customer from the country of France (FR). In our value mapping table, we do not have any entries maintained for country FR.

Step 3 - Verify the Customer Master Record

Notice that the default discount value of 2 is applied to the customer created.

First, we will look at the simplest concept of API Management: a layer that sits on top of the APIs you already have. Then we will go through its five core functions, Secure, Manage, Publish, Monitor, and Monetize, one by one. Finally, we will bring them back together and see how that layer actually works.

API Management Is a Layer on Top of Your Existing APIs

Here is the simplest way to think about it. You already have APIs. Your S/4HANA system exposes OData services. Your Cloud Integration (CPI) iFlows have HTTP endpoints. Your custom applications have REST APIs. They already work.

API Management is the layer you put on top of those APIs. It doesn’t replace them, and it doesn’t change how they work internally.

I like to explain it with a highway. Without API Management, your APIs are like an open highway: anyone can drive on it, at any speed, with no toll booths, no speed cameras, and no idea who is actually on the road. Everything works, but you have no control over any of it.

API Management adds that control. It sits between whoever is calling your API, the consumer, and the backend system that serves the response. Every single request passes through this layer, and that is where you apply your rules.

💡 Key takeaway

API Management is a governance layer between API consumers and your existing APIs. Every request passes through it, so that is where you secure, control, and observe your APIs without changing the APIs themselves.

The Five Core Functions of SAP API Management

API Management gives you five core functions. Let’s go through each one.

1. Secure

Secure is probably the most common reason organizations adopt API Management in the first place. You need to control who is allowed to call your API, so API Management verifies the caller’s identity before anything else happens. Depending on the scenario, that can be an API key, an OAuth 2.0 access token (including tokens in JSON Web Token (JWT) format), basic authentication credentials, or a client certificate.

If a request arrives without valid credentials, it is blocked right at the APIM gateway. It never even reaches your backend system, which is exactly what you want for an S/4HANA system sitting behind the API.

We will spend a lot of time on this later in the series, with hands-on parts on the Verify API Key, Basic Authentication, and OAuth 2.0 policies.

2. Manage

Now, even if a consumer is allowed to call your API, you still want to control how much they can call it. That is the job of the Manage function, and it comes down to these policies.

Quota limits the number of calls a consumer can make in a time window, for example 1,000 calls per day. Once a consumer exceeds that limit, API Management returns an error instead of forwarding the request.

Spike Arrest protects your backend from sudden bursts of traffic. Let’s say you normally receive 10 requests per second and suddenly 500 arrive at once. Spike Arrest smooths that burst out so your backend doesn’t fall over.

⚠️ Quota vs Spike Arrest

Quota is about a consumer’s total allowance over a period. Spike Arrest is about protecting the backend from traffic arriving too fast.

Caching stores a response at the gateway. If your backend returns the same response for the same request, the next identical request is served straight from the cache without touching the backend at all. That reduces load and makes the API faster for the consumer.

3. Publish

The Publish function is about developer experience. Once an API exists, how do developers find it? How do they know which endpoints are available, which parameters to pass, and what responses to expect?

SAP API Management splits this into two sides:

• API portal: where you, the API admin/developer, work. This is where you build API proxies, attach policies, and bundle APIs into products.

• API business hub enterprise (previously called the Developer Portal): the self-service portal for API consumers. Developers browse your published APIs, read the documentation, try them out in a test console, subscribe to a product, and create an application to get their own API key, all without you creating credentials for each one by hand.

Put simply, the API portal is where you manage everything, and the API business hub enterprise is where your API consumers onboard themselves.

4. Monitor

Once your APIs are live, you need to know what is happening. How many calls are coming in? What is the average response time? Are there errors, and which consumers are generating the most traffic?

API Management gives you API Analytics: dashboards that show traffic patterns, errors, response times, and which APIs are being adopted and which are not. This matters for troubleshooting, but it matters just as much for business decisions. If one API gets ten times more traffic than another, that tells you something about what your consumers actually need.

5. Monetize

The fifth function, Monetize, is optional, and plenty of organizations never use it. But when you run an API program for external partners or developers, it lets you charge for API access.

You define rate plans, for example a price per API call, or a flat monthly fee that covers up to a certain number of calls, and you attach those rate plans to your API products. API Management then tracks usage and calculates the billing. That is how an API goes from being a cost center to being a revenue stream.

The Five Functions at a Glance

Here is a quick way to remember which function answers which question:

• Secure: Who is allowed to call this API? (API keys, OAuth 2.0, JWT, basic authentication, certificates)

• Manage: How much, and how fast, can they call it? (Quota, Spike Arrest, response caching)

• Publish: How do developers find and start using it? (API portal, API business hub enterprise, products)

• Monitor: What is actually happening with it? (API Analytics: traffic, errors, response times)

• Monetize: Can we charge for it? (Rate plans attached to products)

How the Layer Is Put in Place: API Proxies and Policies

Let’s bring it back together. At the bottom, you have your existing APIs: S/4HANA OData services, CPI endpoints, and custom REST APIs. At the top, you have the API consumers: mobile apps, web apps, partners, and third-party developers. In the middle sits the API Management layer, where Secure, Manage, Publish, Monitor, and Monetize all happen.

The consumers never talk to your backend directly. They talk to the API Management layer, and the layer handles everything in between.

The way you put that layer in place is by creating an API proxy.

The API proxy is the managed front door between the consumer and your backend, and inside it you attach policies: pre-built rules for security, traffic management, message transformation, and more. Verify API Key, Quota, and Spike Arrest, which we mentioned above, are all policies you attach to a proxy.

So, to summarize: API Management is a governance layer that lets you secure, manage, publish, monitor, and monetize your APIs, without changing the APIs themselves. In the next article, we will look at how this works under the hood: the architecture, the API proxy, and the policy engine.

Subscribe now

If you have any questions about what SAP API Management does or how these five functions fit together, please leave a comment below. I will be happy to help.

First, we will place API Management inside SAP Integration Suite and SAP Business Technology Platform (BTP). Then we will walk through each capability of Integration Suite, one by one, so you know what each tool is for.

SAP BTP, SAP Integration Suite, and API Management

SAP API Management is one capability inside a larger product called SAP Integration Suite. SAP Integration Suite is SAP’s integration platform as a service (iPaaS), and it runs on SAP Business Technology Platform (BTP). So when someone says “APIM on BTP,” what they actually mean is the API Management capability of Integration Suite, running in a BTP subaccount.

SAP API Management is one capability of SAP Integration Suite, which is SAP’s iPaaS running on SAP BTP.

I find it helpful to think of Integration Suite as a toolbox. Different integration problems call for different tools, and each tool in the box is what SAP calls a capability.

You activate only the capabilities you need in your Integration Suite tenant, so two companies running “Integration Suite” can be using very different parts of it.

The Capabilities of SAP Integration Suite

Let’s go through the toolbox. I have grouped these the way I think about them in practice: the core capabilities you will touch on in each and every project, and then the rest of the toolbox, which is more specialized.

Core Capabilities

1. Cloud Integration (CI) - Former Product CPI

Cloud Integration, which almost everyone still calls CPI, is the core engine of the suite and by far the most commonly used capability. This is where you build integration flows (iFlows) that move data between systems: mapping fields, transforming formats, and routing messages. If System A needs to send an invoice to System B and the formats don’t match, the iFlow that bridges them is built here.

If you are coming from SAP PI/PO, Cloud Integration is the closest thing to what you already know. This is one of the most widely used capabilities in SAP Integration Suite; I have always used SAP CI in every SAP S/4HANA implementation project where the integration platform was SAP Integration Suite.

2. API Management

API Management is the capability this entire series of articles is about. It sits as a governance and security layer in front of your APIs. It controls who can call an API, how often they can call it, and what happens to the request and response on the way through. It also gives API consumers a place to discover and subscribe to your APIs. We will go much deeper into each of these in the upcoming articles.

3. Event Mesh

Event Mesh handles event-driven communication. A system that needs to know about a business event (business document change) typically polls another system over and over, asking “has anything changed yet?” Or the sender system having to push the data to each and every receiver system.

With Event Mesh, the source system publishes the business event instead, for example, “a sales order was created,” and any interested system subscribes to that event and reacts in real time.

The result is communication that is decoupled and asynchronous.

4. Open Connectors

Open Connectors gives you prebuilt connectors to third-party cloud applications such as Salesforce, Slack, and Dropbox. SAP currently lists more than 160 of them. The useful part is that they all sit behind one unified REST API, so instead of learning each vendor’s authentication model, pagination style, and error format, you connect to all of them in one consistent way.

The Rest of the Toolbox (Capabilities)

5. Trading Partner Management and 6. Integration Advisor

I like to think of these two as the B2B EDI integration tools. They are usually used together.

Trading Partner Management (TPM) handles Electronic Data Interchange (EDI) communication with your business partners: storing partner profiles, agreements, and the technical details of how you exchange documents with each one. Integration Advisor uses machine learning to help you build message implementation guidelines and mappings for B2B standards such as UN/EDIFACT and ASC X12.

However, my experience is that although Integration Advisor helps to build mappings between EDI formats and iDocs for EDI integration with SAP S4 HANA. How you build mappings is a little bit different to the tradition graphical message mapping. Hence, there is a bit of a learning curve to use it.

However, if your company exchanges orders, invoices, or delivery notes with external partners over EDI, these two capabilities can come in handy.

7. Integration Assessment

Integration Assessment is a planning tool. Before you build anything, it helps you evaluate your integration landscape and recommends which integration technology fits each scenario. It is a decision support tool for architects and integration consultants.

8. Migration Assessment

Migration Assessment is aimed specifically at organizations moving from SAP Process Orchestration (PI/PO) to Integration Suite. It analyzes your existing PI/PO interfaces and tells you which ones can migrate easily, which need manual work, and roughly how much effort to expect.

9. Graph

Graph is actually part of the API Management capability rather than a separate tool. It connects your SAP landscape into a single, unified API with a semantic data layer on top. So instead of a consuming application calling a dozen different endpoints across different SAP systems, it queries one endpoint and gets the business data it needs.

10. Edge Integration Cell

Edge Integration Cell is a hybrid deployment option. It lets you run the integration runtime inside your own private infrastructure, on a Kubernetes cluster you manage, while design, management, and monitoring still happen from the cloud. This matters for companies that have strict data residency or security requirements and cannot let certain messages leave their own network.

Alongside these ten, SAP’s own capability list also includes a few smaller ones, such as OData Provisioning and Data Space Integration. You won’t need them to learn SAP API M, but it is good to know they exist when you browse the capability list in your tenant.

Which Capability Solves Which Problem?

Here is the rule of thumb I use when someone asks me, “which part of Integration Suite do I need?”

• Move and transform data between two systems: Cloud Integration (CI)

• Secure, throttle, and publish APIs for consumers: API Management

• Notify many systems when something happens, in real time: Event Mesh

• Connect to third-party SaaS apps in a simple way: Open Connectors

• Exchange EDI documents with business partners: Trading Partner Management + Integration Advisor + CI

• Decide which integration technology to use: Integration Assessment

• Plan a move from SAP PI/PO: Migration Assessment

• Expose many SAP systems through one business-data API: Graph (part of API Management)

• Keep the runtime inside your own network (On-premise): Edge Integration Cell

In real projects, these capabilities are rarely used in isolation. A very common pattern, and one we will discuss in a future article, is an iFlow in Cloud Integration that does the heavy lifting, with API Management sitting in front of it to secure and control who can call it.

Where API Management Fits

So, to bring it together: SAP Integration Suite gives you all of these capabilities under one toolbox, and API Management is the one we focus on in this series of articles. It sits alongside Cloud Integration, Event Mesh, and the others as the governance and consumer-experience layer for your APIs.

Cloud Integration answers the question “how do I connect these systems?”

API Management answers a different one: “now that this API exists, who is allowed to use it, how much, and how do they find it?”

In the next article, we will zoom in on API Management itself and look at what it actually does, the core functions it provides.

If you have any questions about the capabilities of SAP Integration Suite or where API Management fits, please leave a comment below. I will be happy to help.

📚 SAP AIF Configuration Series - Guide #4

We are configuring value mappings on top of the iDoc interface we developed in our previous guides.

If you are new here and would like to see the previous articles, check out the following guides.

1. How to Configure your First IDoc Monitoring Interface in AIF.

2. How to Configure Fixed Values in SAP AIF

3. Implement a Single Value Mapping in AIF

In the last article, we built a single value mapping in SAP AIF that translates a salutation code from an external system into the internal SAP value. That works fine when you only have one incoming field to look up. But sooner or later you’ll hit a requirement where the result depends on a combination of fields, and a single mapping can’t handle that.

That’s exactly the situation we’re solving here. The scenario is that the airline customer interface receives customer data from an external system via IDoc.

The business wants a discount assigned to each new customer automatically, based on the country of the customer and the customer type.

Here are the two fields in the incoming message,

• ISO country code (COUNTR_ISO) - full path E1SCU_CRE-E1BPSCUNEW-COUNTR_ISO)

• Customer type (CUSTTYPE) - full path E1SCU_CRE-E1BPSCUNEW-CUSTTYPE)

The discount determined for the customer gets written into the DISCOUNT field (E1SCU_CRE-E1BPSCUNEW-DISCOUNT).

The discount rules look like this:

Single Value Mapping vs. Multi-Value Mapping

A single value mapping has exactly one external source field. AIF looks up the incoming value in the mapping table, finds a match, and writes the corresponding target value to the destination field. The salutation mapping from the previous chapter is a good example of this: one external field (FORM) maps to one internal value.

A multi-value mapping has two or more external source fields, and AIF evaluates all of them together as a single combined key. The combination is what determines the result or the target value.

💡 Tip: "when field A equals X, the result is Y," a single mapping can handle. When the rule becomes "when field A equals X and field B equals Z, the result is Y," you need to use multi-mapping in AIF.

Configuration Steps for Multi-Value Mapping in AIF

🛑 This configuration builds on the II_FL_CUST interface from the base AIF IDoc interface chapter. The structure mapping and field mapping for that interface need to already be in place before you start.

Step 1: Define the Multi-Value Mapping

Transaction: /AIF/CUST -> Interface Development -> Define Structure Mappings -> Define Field Mappings

💡 Tip: The order of the source fields matters. AIF builds the lookup table by combining the values in exactly this order. When you maintain the mapping data later in /AIF/VMAP, the external value columns will appear in the same sequence —COUNTR_ISO first, CUSTTYPE second.

Since VM_DISCOUNT does not yet exist, AIF will prompt you to create it. If it does not, double-click the value mapping name to create it.

Step 2: Configure the Details of the Value Mapping

• Number of External Values - 2

• Single or Multiple Value Mapping - Multiple

• Customizing or Master Data - Master Data

Setting Number of External Values = 2 tells AIF to expect two source fields as the combined lookup key

💡 Customizing or Master Data?

This controls how and where the mapping values are maintained.

• Master Data - values are maintained at runtime directly in transaction /AIF/VMAP. They’re client-dependent, meaning each client manages has its own copy of mapping values.

• Customizing - values are maintained in the IMG and transported like any other Customizing entry. Use this when the mapping is stable and needs to be consistent across all clients through the landscape.

Save your entries.

Optional Step: Remove Any Conflicting Fixed Value

If a fixed value was previously configured for the DISCOUNT target field, you should remove it.

In the previous example, we defined a Fixed Value in AIF for the Discount field. In that case, fixed values take priority over value mappings, so the discount field would receive the fixed value instead of the target value from Value Mapping.

Step 3: Maintain the Multi-Value Mapping Data

Open transaction /AIF/VMAP, select namespace ZDEMO and value mapping VM_DISCOUNT.

You will see two external value columns, one for COUNTR_ISO and one for CUSTTYPE, in the order defined in Step 1. Create new data rows for each combination of incoming value and target.

⚠️ Warning: Both external values must match exactly for AIF to find a result. They are case-sensitive. If the IDoc sends COUNTR_ISO = US but CUSTTYPE arrives as lowercase p instead of uppercase P, the lookup will fail and the message will go into error.

Step 4: Test the Interface

Use transaction WE19 to create a test IDoc based on basic type FLCUSTOMER_CREATEFROMDATA01. In segment E1BPSCUNEW, populate the following fields and leave the DISCOUNT field empty. AIF will fill it in during preprocessing.

Test case - US Passenger customer (COUNTR_ISO = US, CUSTTYPE = P)

Verify that the discount was correctly determined by checking the message in /AIF/IFMON or /AIF/ERR and inspecting the customer record in table SCUSTOM.

There are resources out there that explain what AIF is and what it can do, but when you actually start implementing AIF in a project, we noticed that resources on SAP AIF are scarce.

And perhaps one of the biggest challenges we faced during our projects was how do you explain to IT manager, SAP implmentation teams why AIF should be used and how it should fit into the overall integration architecture?

“We faced many of these challenges ourselves while working on different SAP implementation projects.”

So we decided to put what we have learned along the way into one place.

Introducing the SAP AIF Configuration Guide for SAP Consultants

This is a complete guide for SAP consultants who are already working with AIF, want to learn AIF, or are looking to newly implement AIF in their organizations.

We didn’t want to create another guide that only explains the theory.

Our goal was to create something practical that you can actually use when working on an SAP project.

There are currently more than 75 lessons covering different parts of SAP AIF.

And this is not the final version.

This Is a Living Guide

We will be regularly adding new AIF lessons and new topics to the guide.

So if there are areas of AIF that are not covered yet, there is more content coming.

And the important part is that all future lessons will be included for you when you get access now.

Our intention is to keep improving this guide and make it a most useful resource for SAP consultants working with AIF.

Get the eBook!

Who Is This For?

If you are an SAP technical and functional consultant who:

• Is currently working with SAP AIF

• Wants to learn SAP AIF

• Is involved in SAP S/4HANA implementation projects

• Needs to understand how AIF is configured and implemented

• Wants to implment SAP AIF for the first time

• Or is trying to understand where AIF fits into your overall integration architecture

Then this guide is for you.

We have tried to bring together the theory, configuration, implementation steps, practical examples, and lessons we have learned from working with AIF in real projects.

Get life time access!

The SAP AIF Configuration Guide is now available.

If you want to start learning SAP AIF or improve your understanding of how to implement it, you can get access using the link below.

And remember, as we add new lessons to the guide, you will get access to those future lessons as well.

👉 Get access to the SAP AIF Configuration Guide here.

Get the eBook!

What Is an API Proxy?

Let’s start with the concept, because it’s worth slowing down on this before touching the API Portal.

Say your backend is a service sitting at a real, callable address.

For this article, we’ll use a free exchange-rate API at https://open.er-api.com/v6/latest. If you called that URL right now, it would hand you back the latest currency exchange rates.

If we let every client app call that address directly, we have a problem: once a client knows your backend’s real address, you’ve lost control over who can call it, how often they can call it, and what they can do once they’re in.

So instead of exposing the backend itself, we put something in front of it.

That something is called an API proxy.

An API proxy is a facade for your APIs that you build and deploy in SAP API Management. The client app never talks to your actual API backend. It talks to the proxy, and the proxy forwards that call to the real backend on the client’s behalf.

Here’s an analogy for an API Proxy: think of a hotel front desk.

If you want to contact someone staying at the hotel, you never call a guest’s room directly, and you don’t even know the room’s extension number. Instead, every call goes through one number - the hotel’s front desk. You dial the front desk, the person at the desk figures out who you’re trying to reach, and connects you through internally. The guest never has to publish their extension to the outside world, and the hotel can move that guest to a different room tomorrow without anyone outside ever noticing, because the number you dial never changes.

The API proxy is that front desk. The backend system is the guest’s room. The client app is you, calling in from outside.

API Proxy URL vs. Target API URL

This is the part that trips up most people new to SAP APIM, so it’s worth being explicit about it.

🛑 Key distinction

The Target API URL is your backend’s real address - the room extension. The API Proxy URL is a brand new, published address that SAP API Management generates once you deploy the proxy - the front-desk number. Clients only ever call the API Proxy URL.

The Target API URL, in our case, is https://open.er-api.com/v6/latest. This address lives inside the proxy’s target configuration and is never given out to client apps.

The API Proxy URL is generated by SAP API Management once you deploy, something like:

https://3ed7f623trial-trial.integrationsuitetrial-apim.us10.hana.ondemand.com/3ed7f623trial/v1/exchangerates

This is the only address you ever hand to a client. Nobody outside needs to know, or should know, that open.er-api.com exists at all and know that is where the actual exchange rates are extracted.

Why Use the APIM (Proxy) Layer?

Three reasons, each mapping back to the hotel front desk:

• Decoupling. The hotel can move a guest to a different room, or even a different floor, and the number you dial never changes. If you later move your backend, or swap the exchange-rate provider entirely, the client’s API Proxy URL doesn’t change - you just update where the proxy points internally.

• Control. Every call is forced through the front desk - there’s no side door. This is the checkpoint where you attach policies like Verify API Key, Spike Arrest (protection againist bots), and Quota. None of that logic sits on the backend; it all sits at the proxy.

• Transformation. A front desk doesn’t just connect a call - it can take a message and pass it along in a cleaner form. A proxy can reshape the request before it reaches the backend, or reshape the response before it goes back to the client, without the backend ever needing to change.

Every API proxy has two sides: the ProxyEndpoint, which faces the client (the published front-desk number), and the TargetEndpoint, which faces your backend (the real room extension). We’ll go deeper on both of these in a later article - for now, just remember which side does what.

Demo Scenario Overview

For this walkthrough, we’ll wrap the same exchange-rate backend we just discussed:

• Target API URL: https://open.er-api.com/v6/latest

It’s a free, no-auth API, which makes it a good first target. There’s no credential handling to worry about yet, so we can focus entirely on the proxy mechanics.

Step 1: Create the API Proxy

Log in to the SAP API Portal and go to the Configure area. This is where all your API proxies live.

Click Create under the API Proxy tab. A wizard opens asking for some basic details.

Give it a name. Since this proxy wraps the exchange-rate backend, let’s name it exchangerates.

Below the name, set the base path. This is the part of the URL clients will use to reach the proxy once it’s deployed, effectively the front-desk number.

Set the API base path to /exchangerates.

Subscribe now

It is recommended to structure your API resources with a version ID. Therefore, let’s add the version as v1. If the version is configured, the base path of the API proxy will be automatically changed to reflect the version: /v1/exchangerates.

Step 2: Configure the Target Endpoint

Move to the next step, where you configure where the proxy should actually forward requests. Paste in the target URL: https://open.er-api.com/v6/latest.

This is the private room extension, or the backend service URL - the client will never see this address directly

We will select the target type as “URL” since the target API we configure is a pure URL.

Click Create, and you’ll see a summary of everything configured: the name exchangerates, the base path /v1/exchangerates, and the target URL https://open.er-api.com/v6/latest.

Click Save.

At this point, the API proxy has been created but it isn’t live yet. It will be in “Un Deployed” status. Creating the proxy only saves its configuration and proxy URL.

Step 3: Deploy the API Proxy

To make the proxy callable, you need to deploy it.

Click Deploy.

Wait for the deployment to finish. Once the status changes to Deployed, the proxy is live and reachable at its own published URL.

The API Proxy URL for trial accounts will be in this format:

https://<subaccount-id>–trial.integrationsuitetrial-apim.<region>.hana.ondemand.com/<subaccount-id>/<your-API-proxy-base-path>

That’s your front-desk number now. Nobody calling this URL needs to know that open.er-api.com exists behind it.

Testing the API Proxy

Grab the deployed proxy URL and open it in a new browser tab, or trigger it via Postman.

The response comes back with the latest exchange rates, exactly what the backend would have returned if called directly.

Nothing has been added or removed, because no policies have been attached yet. Right now, the proxy is doing exactly one thing: receiving the client’s request and passing it straight through to the backend, then passing the response from the backend straight back to the caller.

Notice the response from the backend you saw before - it should be identical to the proxy response. The same data, same structure, nothing lost in between.

That’s exactly what you want to confirm at this stage, before adding any logic on top.

Now you can add your policies on top of it. We will look at how to add policies in another article.

Tips and Tricks

• Keep the very first version of any proxy a bare pass-through, like we did here, before attaching any policies. It gives you a baseline to compare against once you start adding Verify API Key, Spike Arrest, or transformation policies. If something breaks later, you’ll know it’s the policy, not the underlying proxy configuration.

• Double-check the base path doesn’t collide with an existing proxy on the same environment. Since the base path is what routes incoming calls to the correct proxy, an overlapping path will cause deployment or routing issues.

This bare pass-through proxy is your starting point. In upcoming lessons, we’ll start attaching policies to it, and this is exactly where the ProxyEndpoint and TargetEndpoint structure we introduced above comes into play.

If you have any questions about creating or deploying your first API proxy in SAP API Management, leave a comment on the original post. I’ll be happy to help.

Full online course

Rather watch the lesson in video format?

Cloud Integration with SAP Integration Suite for Beginners — 200+ video lessons, direct support from me if you get stuck, no prior SAP experience needed.

See the full curriculum →

📚 SAP AIF Configuration Series - Guide #3

We are configuring value mappings on top of the iDoc interface we developed in our previous guides.

If you are new here and would like to see the previous articles, check out the following guides.

1. How to configure your first IDoc monitoring interface in AIF.

2. How to Configure Fixed Values in SAP AIF

Value mapping in SAP Application Interface Framework (AIF) is a mechanism used to translate incoming external values into internal SAP-compliant values during message processing. Or vise-versa from internal SAP values to external values.

It’s needed because different source systems often use different coding or naming conventions than SAP. Value mapping ensures that these external representations are converted into the correct internal values, so the data can be processed without errors and remains standardized across interfaces.

Scenario

In this example, let’s assume the external system sends us the passenger (customer) master information with the title as MISTER or MISTRESS.

However, when we create the customer master data, we don’t want to use these external values in the title; instead, we want to save them as Mr. and Mrs.

We’ll create a value mapping for the FORM field in the iDoc.

The external values are converted into standard internal SAP values as follows:

• MISTER → Mr.

• MISTRESS → Mrs.

This ensures that incoming data is normalized during processing, regardless of how the external system represents the salutation.

Step 1 - Define Value Mapping

Transaction: /AIF/CUST -> Interface Development -> Define Structure Mappings -> Define Field Mappings

In Define Structure Mappings -> Define Field Mappings, create a new entry.

Make sure the destination structure is mapped correctly. We created this mapping in the previous example for Fixed Values.

⚠️ Warning

Make sure the interface II_FL_CUST in namespace ZDEMO is already working before you start this step.

The value mapping you’re about to create sits on top of the structure mapping from the Fixed Values chapter, so that needs to be in place first.

Maintain the following values under Define Field Mapping:

• Field in Destination Structure: E1SCU_CRE-E1BPSCUNEW-FORM — the field you’d like to transform

• Field Name 1: E1SCU_CRE-E1BPSCUNEW-FORM — the field you’d like to transform

• Namespace: ZDEMO Value Mapping: VM_FORM — the name of the new value mapping table

💡 Tip

You can select the field from the drop-down.

Since the value mapping doesn’t yet exist, you’ll be prompted to create it.

Confirm the dialog.

Then define the value mapping with the following settings:

• Value Mapping Description: Map customer form (salutation)

• Data Element for INT: S_FORM

• Number of External Values: 1

• Single or Multiple Value Mapping: Single

• Customizing or Master Data: Master Data

💡 Customizing or Master Data?

This controls how and where the mapping values are maintained.

• Master Data - values are maintained at runtime directly in transaction /AIF/VMAP. They’re client-dependent, meaning each client manages its own set of mapping values. Use this when the mapping is likely to change over time or differs between clients (e.g. sandbox vs production).

• Customizing - values are maintained in the IMG and transported like any other Customizing entry. Use this when the mapping is stable and needs to be consistent across all clients through the transport landscape.

For most real-world interfaces, Master Data is the more practical choice because business users or support teams can update the values directly in /AIF/VMAP without needing a transport.

Our AIF eBook with a full collection of these guides is coming soon!

Read more

📚 SAP AIF Configuration Series - Guide #2

We are configuring the fixed values on top of the iDoc interface we developed in AIF previously. If you are new here and like to learn how to configure the namespaces and the iDoc Monitoring basic steps in AIF, check out the linked article first.

Introduction to Fixed Values in SAP AIF

Fixed values in SAP Application Interface Framework (AIF) allow you to assign predefined values to interface fields during message processing. This is particularly useful when a field must always contain a specific value, or when the incoming message doesn’t provide all the mandatory information required by the target application.

Scenario

In this example, we’ll use a fixed value mapping to populate the CUSTTYPE field during inbound IDoc processing. The CUSTTYPE field is mandatory and cannot be left empty. It also only accepts two valid values:

• P - Passenger

• B - Business

In our requirement, all customers created through this interface should initially be classified as passengers. We’ll configure a fixed value in SAP AIF that automatically assigns the value P to the CUSTTYPE field. This ensures that every IDoc processed through the interface contains a valid customer type and can be processed successfully, without requiring the sender system to provide this information. The sender system may send a blank value.

Sample IDoc segment showing the CUSTTYPE field left blank by the sender

In the following steps, you’ll learn how to configure a fixed value mapping in SAP AIF so that all customer master records created through the II_FL_CUST interface automatically receive the customer type P (Passenger) during preprocessing.

Step 1 - Configure the Interface for Preprocessing

Transaction: /AIF/CUST -> SAP Application Interface Framework -> Interface Development -> Define Interfaces

Go to Customizing for SAP Application Interface Framework (transaction code /AIF/CUST) and navigate to Interface Development -> Define Interfaces.

💡 Tip Pre-Processing must be enabled on the interface before AIF can apply any field mappings - including fixed values and value mappings at runtime. Without this flag set, the structure mapping configuration in the following steps will have no effect.

/AIF/CUST - Define Interfaces menu path

In the selection screen, enter your namespace (for example, ZDEMO) and choose Continue.

/AIF/CUST - namespace selection screen

Switch to Change Mode and open the existing interface II_FL_CUST.

/AIF/CUST - opening interface II_FL_CUST in change mode

Configure the following settings:

• Deselect Move Corresponding Structures

• Select Pre-Processing

• Maintain the source and destination structures

/AIF/CUST - interface settings with Pre-Processing enabled

Save your changes.

Step 2 - Define Structure Mappings

Transaction: /AIF/CUST -> SAP Application Interface Framework -> Interface Development -> Define Structure Mappings

While still in Customizing, navigate to Interface Development -> Define Structure Mappings.

/AIF/CUST - Define Structure Mappings menu path

Enter the following values:

• Namespace: ZDEMO

• Interface Name: II_FL_CUST

• Interface Version: 1

/AIF/CUST - structure mapping selection screen with namespace/interface/version fields

Choose Continue.

💡 Tip

Notice that in this example, the fixed value is created under the combination Namespace / Interface / Version (ZDEMO / II_FL_CUST / 1). As a result, this fixed value is specific to this interface version and cannot be reused by other interfaces within the same namespace. This approach is useful when the fixed value is only relevant to a particular interface and should not be available elsewhere. SAP AIF also allows you to create fixed values at the namespace level. Namespace-level fixed values aren’t tied to a specific interface and can therefore be reused across multiple interfaces within the same namespace. For example, if several interfaces in namespace ZDEMO require the same customer type, status code, company code, or any other constant value, it’s more efficient to create the fixed value directly under the namespace.

Select New Entries and create a mapping for the root node of your interface structure.

/AIF/CUST - New Entries for structure mapping

Select the root structure that was generated for your interface.

Save the entry.

💡 Tip

The source structure you select here should be the root-level DDIC structure that was generated for your IDoc basic type in the DDIC generation step. If you’re unsure of the name, you can look it up in SE11 or check the objects created during the /AIF/IDOC_GEN run.

Step 2.1 - Assign Destination Structure

Select the newly created source structure and double-click Assign Destination Structure.

/AIF/CUST - Assign Destination Structure option

⚠️ Warning

Make sure to first select the source structure and then the destination structure; otherwise, the configuration cannot be created properly.

Create a new entry with the following values:

• Number of Structure Mapping: 10 Destination Structure: Root structure of the interface

• Move Corresponding Fields: Selected

Save your changes.

Step 3 - Create a Fixed Value for Customer Type

Read more

Scenario Detail

In this scenario, we will set up an SAP AIF interface to process customer data received through an IDoc. The interface will be capable of creating and updating customer (passenger) master records.

We will use the following IDoc:

Message Type: FLCUSTOMER_CREATEFROMDATA

Basic Type: FLCUSTOMER_CREATEFROMDATA01

Step 1 - Define the Namespace

Transaction: /n/AIF/CUST -> SAP Application Interface Framework -> Define Namespaces

Navigate to transaction /n/AIF/CUST and create a new namespace. Alternatively, you can use an existing namespace. In this example, we will use the existing namespace ZDEMO.

💡 Tip

The namespace is the top-level container for all your AIF objects - interfaces, recipients, and value mappings all sit inside it. Using a consistent naming convention (e.g. Z + project abbreviation) makes it much easier to manage objects across a large system.

Step 2 - Generate DDIC Structure

Transaction: /n/AIF/IDOC_GEN

SAP AIF works with SAP Data Dictionary (DDIC) structures. However, IDoc basic types, which define the structure of an IDoc, do not have corresponding DDIC structures delivered by default. Therefore, before an IDoc can be monitored and processed through SAP AIF, a DDIC structure must be generated for the IDoc basic type.

Open the IDoc Structure Generator using transaction /n/AIF/IDOC_GEN and enter the details of the IDoc you want to monitor.

💡 Tip

This step only needs to be done once per IDoc basic type. If a DDIC structure has already been generated for your basic type by a previous project, you can skip to Step 2.1 and create the interface directly in /n/AIF/CUST without re-running the generator.

Step 2.1 - Create the Interface

You can create the interface directly during this step. Alternatively, you can create the interface later using transaction /n/AIF/CUST.

To create the interface as part of the IDoc Structure Generator process, select the Create Interface option and maintain the interface details as shown below.

💡 Tip

The IDoc Processing Scenario field controls how AIF hooks into the IDoc processing. The option “ALE runtime; AIF enabler writing application log” is the most common choice for inbound IDocs - it means AIF runs as part of the standard ALE inbound processing and writes errors to the application log so they appear in the AIF monitor.

Namespace: ZDEMO or the namespace created in Step 1

Interface Name: II_FL_CUSTOMER

Interface Version: 1

Interface Description: Customer Master IDoc Interface

IDoc Processing Scenario: ALE runtime; AIF enabler writing application log

Customizing Request: Your customizing request

After maintaining the required information, execute the generation process.

If the generation is successful, SAP AIF creates all required objects, including the DDIC structures and interface definitions. A confirmation popup is displayed showing the details of the generated objects.

If the objects are created successfully, you will have a log with all the objects like this.

Step 3 - Create Interface-Specific Single Index Table

Transaction: SE11

Go to transaction SE11 to create the index table. SAP provides a standard index table template that can be used as a reference. Copy the template table and create a new custom index table based on it. Make sure the new table follows the required naming conventions for your namespace and interface.

💡 Tip

To leverage the full capabilities of SAP AIF and to customize interface error handling and monitoring as required, an index table is typically needed. Therefore, it is recommended to always create an index table for your interfaces.

This index table is used by SAP AIF to enable message indexing and monitoring for the interface.

⚠️ Warning

You can switch the single index table later; however, messages stored in the old index table will no longer be visible in the Interface Monitor. Only new messages will be written to the newly assigned table.

You can use the AIF index template table /AIF/STD_IDX_TBL and select Copy. Then, enter the name ZIDX_IXIFL_CUSTO for the new table and select Continue. When prompted, enter the package name you created earlier.

🛑 Required

Make sure to activate the table in SE11 before moving on. Without activation the index table does not exist in the database and AIF will not be able to write messages to it. You will get a runtime error the first time an IDoc is processed.

Step 4 - Define Namespace-Specific Features

Transaction: /n/AIF/CUST -> SAP Application Interface Framework -> Error Handling -> Define Namespace-Specific Features -> Define Interface-Specific Features

Next, assign the index table to the interface. Go to transaction /n/AIF/CUST and navigate to SAP Application Interface Framework -> Error Handling -> Define Namespace-Specific Features.

Enter namespace ZDEMO and continue.

In Define Interface-Specific Features, choose New Entries and maintain the interface II_FL_CUST with version 1. In the Message Index Table field, enter the newly created index table ZAIF_IDOC_CUST and save your changes.

Step 5 - Create Recipient for Alerts

One of the main purposes of SAP AIF is to enable users to monitor interfaces through AIF monitoring tools. However, not all users should have access to all interfaces in the system. Therefore, users must be grouped into different categories so that access can be controlled based on business requirements.

In SAP AIF, these user groups are defined as Recipient for Alerts. Based on your organization’s requirements, you should create appropriate recipient groups.

For example, you can create one recipient group for users who should monitor all IDoc-related interfaces, and another group for users responsible for OData services.

💡 Tip

In a real-world scenario, access is typically restricted by functional areas. For instance, the Material Master team (PLM) may be given access to material-related interfaces, while the OTC team may be granted access to all sales-related interfaces.

Go to Customizing (transaction /AIF/CUST) and navigate to SAP Application Interface Framework > Error Handling > Define Namespace-Specific Features.

Enter or select your namespace ZDEMO and select Continue.

Navigate to Define Recipients by double-clicking it.

Select New Entries, enter a meaningful name for your new recipient.

Step 6 - Assign the Recipient to the Interface

Transaction: /AIF/CUST -> SAP Application Interface Framework -> Error Handling -> Define Namespace-Specific Features -> Define Interface-Specific Features -> Assign Recipients Without Key Fields

Now assign the recipient to the interface. Go to transaction /AIF/CUST and navigate to SAP Application Interface Framework -> Error Handling -> Define Interface-Specific Features.

💡 Tip

Use Assign Recipients Without Key Fields when all messages for this interface should be visible to the recipient group, regardless of any business key values (e.g. customer number or company code). If you want to restrict visibility to only certain key values, use Assign Recipients with Key Fields instead.

Enter namespace DEMO_1, interface FCUSTOMER, and version 1, then choose Continue.

Read more

The post Header and Exchange Property Parameters of SAP Integration Suite appeared first on SAP Integration Hub.

The post System Resources in SAP Integration Suite – Cloud Foundry Environment appeared first on SAP Integration Hub.

Message Validation in System Integration, Why It Matters

When it comes to system integration, one of the most important steps before message processing begins is ensuring that the incoming message is valid.

This means checking:

• Is the message format correct?

• Does it match the defined schema?

• Are all mandatory elements required for processing available?

• Do fields contain data with correct length and data type?

• Are there invalid characters?

• Do field values fall within an acceptable or expected range?

These are critical checks to perform before continuing with the pipeline. Without proper validation, you may encounter unexpected behavior during later stages of message processing.

Where Should Message Validation Take Place?

In an enterprise integration landscape, there is typically a middleware layer—such as SAP Integration Suite—between the sender and the receiver. If the receiver system is an ERP system like SAP S/4HANA, you could technically perform validation there using tools such as SAP AIF (Application Integration Framework).

However, it is important to assign responsibilities to the right components in your architecture. The receiver system should not be burdened with all validations, especially structural validations like checking XML format against schema. Doing such validations at the receiver means writing unnecessary and often complex backend logic.

Structural validation is best handled in the middleware, as it is the first line of defense.

On the other hand, business validations—such as checking whether an order type, warehouse code, or material exists—should ideally be performed in the receiver system, since that system owns the business data.

A balanced approach is recommended:

• Structural validations (XSD compliance, format, mandatory fields, data type, etc.)

  • Where to Validate: Middleware

  • Reason: Prevent processing of invalid payload early.

• Business validations (order type exists, material code valid etc.)

  • Where to Validate: Receiver system (e.g. S/4HANA)

  • Reason: Requires master data available only in backend.

Message Validation in SAP Integration Suite

SAP Integration Suite provides multiple ways to perform payload validation. You may use:

• XML Validator palette option

• EDI Validator

• Groovy scripts

• XPath expressions

• Filter step logic

• Other validation options depending on the scenario

The recommended first approach is to use standard palette steps. For structural validations, SAP Integration Suite provides XML Validator and EDI Validator out-of-the-box.

In this article, we will focus on the XML Validator, how to configure it, how it behaves, and how to handle payload validation results in your iFlow.

Prerequisites for Implementing XML Validator in SAP Integration Suite

It goes without saying that you need to have the incoming XML message format as well as the corresponding XSD schema for the XML.

For this example, I have created an XML format that sends order information, and based on that, I have created the corresponding XSD schema. The XSD defines all validation rules, and every incoming XML will be validated against it. We want to stop processing any XML that is invalid or does not comply with the XSD.

Incoming XML Format

<?xml version="1.0" encoding="UTF-8"?>
<SalesOrder>
    <!-- ===== Order Header ===== -->
    <Header>
        <CustomerID>VINET</CustomerID>
        <OrderDate>1996-07-04T00:00:00Z</OrderDate>
        <ShippedDate>1996-07-16T00:00:00Z</ShippedDate>
        <DocumentCurrency>EUR</DocumentCurrency>
        <PurchaseOrderNumber>PO-458922</PurchaseOrderNumber>
        <OrderStatus>Confirmed</OrderStatus>
    </Header>
    <!-- ===== Customer Information ===== -->
    <CustomerDetails>
        <CustomerName>Vins et alcools Chevalier</CustomerName>
        <ContactPerson>Jean Dupont</ContactPerson>
        <Email>contact@vins-chevalier.fr</Email>
        <Phone>+33-320-556-789</Phone>
        <BillingAddress>
            <AddressLine1>59 rue de l'Abbaye</AddressLine1>
            <City>Reims</City>
            <PostalCode>51100</PostalCode>
            <Country>France</Country>
        </BillingAddress>
    </CustomerDetails>

    <!-- ===== Shipping Information ===== -->
    <ShippingDetails>
        <ShipMethod>Express</ShipMethod>
        <ShipVia>3</ShipVia>
        <Freight>32.38</Freight>
        <ShipTo>
            <ShipName>Vins et alcools Chevalier</ShipName>
            <ShipAddress>59 rue de l'Abbaye</ShipAddress>
            <ShipCity>Reims</ShipCity>
            <ShipRegion></ShipRegion>
            <ShipPostalCode>51100</ShipPostalCode>
            <ShipCountry>France</ShipCountry>
        </ShipTo>
    </ShippingDetails>

    <!-- ===== Item/Order Lines ===== -->
    <Items>
        <Item>
            <LineNumber>1</LineNumber>
            <MaterialID>SKU-1001</MaterialID>
            <Description>Red Wine Premium</Description>
            <Quantity>50</Quantity>
            <Unit>EA</Unit>
            <UnitPrice>15.00</UnitPrice>
            <Discount>0.10</Discount>
            <NetAmount>675.00</NetAmount>
        </Item>

        <Item>
            <LineNumber>2</LineNumber>
            <MaterialID>SKU-2450</MaterialID>
            <Description>Champagne Brut</Description>
            <Quantity>20</Quantity>
            <Unit>EA</Unit>
            <UnitPrice>35.00</UnitPrice>
            <Discount>0.00</Discount>
            <NetAmount>700.00</NetAmount>
        </Item>
    </Items>

    <!-- ===== Order Summary ===== -->
    <Totals>
        <SubTotal>1375.00</SubTotal>
        <Tax>206.25</Tax>
        <ShippingCharges>32.38</ShippingCharges>
        <GrandTotal>1613.63</GrandTotal>
    </Totals>
</SalesOrder>

XSD Schama of the XML

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           elementFormDefault="qualified">

    <!-- ========= Root Element ========= -->
    <xs:element name="SalesOrder">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="Header" type="HeaderType"/>
                <xs:element name="CustomerDetails" type="CustomerDetailsType"/>
                <xs:element name="ShippingDetails" type="ShippingDetailsType"/>
                <xs:element name="Items" type="ItemsType"/>
                <xs:element name="Totals" type="TotalsType"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>

    <!-- ========= Header Segment ========= -->
    <xs:complexType name="HeaderType">
        <xs:sequence>
            <xs:element name="OrderID" type="xs:string"/>
            <xs:element name="CustomerID" type="xs:string"/>
            <xs:element name="OrderDate" type="xs:dateTime"/>
            <xs:element name="RequiredDate" type="xs:dateTime" minOccurs="0"/>
            <xs:element name="ShippedDate" type="xs:dateTime" minOccurs="0"/>
            <xs:element name="DocumentCurrency" type="xs:string"/>
            <xs:element name="PurchaseOrderNumber" type="xs:string" minOccurs="0"/>
            <xs:element name="OrderStatus" type="xs:string" minOccurs="0"/>
        </xs:sequence>
    </xs:complexType>

    <!-- ========= Customer Info ========= -->
    <xs:complexType name="CustomerDetailsType">
        <xs:sequence>
            <xs:element name="CustomerName" type="xs:string"/>
            <xs:element name="ContactPerson" type="xs:string" minOccurs="0"/>
            <xs:element name="Email" type="xs:string" minOccurs="0"/>
            <xs:element name="Phone" type="xs:string" minOccurs="0"/>
            <xs:element name="BillingAddress" type="BillingAddressType"/>
        </xs:sequence>
    </xs:complexType>

    <xs:complexType name="BillingAddressType">
        <xs:sequence>
            <xs:element name="AddressLine1" type="xs:string"/>
            <xs:element name="City" type="xs:string"/>
            <xs:element name="PostalCode" type="xs:string"/>
            <xs:element name="Country" type="xs:string"/>
        </xs:sequence>
    </xs:complexType>

    <!-- ========= Shipping Details ========= -->
    <xs:complexType name="ShippingDetailsType">
        <xs:sequence>
            <xs:element name="ShipMethod" type="xs:string" minOccurs="0"/>
            <xs:element name="ShipVia" type="xs:int"/>
            <xs:element name="Freight" type="xs:decimal" minOccurs="0"/>
            <xs:element name="ShipTo" type="ShipToType"/>
        </xs:sequence>
    </xs:complexType>

    <xs:complexType name="ShipToType">
        <xs:sequence>
            <xs:element name="ShipName" type="xs:string"/>
            <xs:element name="ShipAddress" type="xs:string"/>
            <xs:element name="ShipCity" type="xs:string"/>
            <xs:element name="ShipRegion" type="xs:string" minOccurs="0"/>
            <xs:element name="ShipPostalCode" type="xs:string"/>
            <xs:element name="ShipCountry" type="xs:string"/>
        </xs:sequence>
    </xs:complexType>

    <!-- ========= Line Items ========= -->
    <xs:complexType name="ItemsType">
        <xs:sequence>
            <xs:element name="Item" type="ItemType" minOccurs="1" maxOccurs="unbounded"/>
        </xs:sequence>
    </xs:complexType>

    <xs:complexType name="ItemType">
        <xs:sequence>
            <xs:element name="LineNumber" type="xs:int"/>
            <xs:element name="MaterialID" type="xs:string"/>
            <xs:element name="Description" type="xs:string"/>
            <xs:element name="Quantity" type="xs:decimal"/>
            <xs:element name="Unit" type="xs:string"/>
            <xs:element name="UnitPrice" type="xs:decimal"/>
            <xs:element name="Discount" type="xs:decimal" minOccurs="0"/>
            <xs:element name="NetAmount" type="xs:decimal"/>
        </xs:sequence>
    </xs:complexType>

    <!-- ========= Totals ========= -->
    <xs:complexType name="TotalsType">
        <xs:sequence>
            <xs:element name="SubTotal" type="xs:decimal"/>
            <xs:element name="Tax" type="xs:decimal"/>
            <xs:element name="ShippingCharges" type="xs:decimal" minOccurs="0"/>
            <xs:element name="GrandTotal" type="xs:decimal"/>
        </xs:sequence>
    </xs:complexType>

</xs:schema>

Basic Configuration of XML Validator

Let’s create an iFlow and validate the incoming XML against an XSD using the default configuration of the XML Validator. We will leave Prevent Exception on Failure unchecked.

Upload the XSD file to the configuration option XML Schema option of the XML validator.

Test Scenario 1: Valid XML

When a valid XML is sent, the validator passes successfully and the message continues. Since we are not performing additional operations here, the same payload is returned as the response.

Test Scenario 2: Invalid XML

Now let’s remove a mandatory field (e.g., OrderID) and send the XML again.

This time the iFlow throws an exception, and the sender receives an HTTP 500 error with a generic MPL error response. It does not clearly indicate what went wrong.

However, the message monitor shows detailed information stating exactly which field failed and why the validation did not pass.

To improve the experience, we should send a meaningful validation response back to the sender indicating:

• Whether validation succeeded or failed

• If failed, the exact reason

This helps the sender correct the payload and resend it. We will look at two variations of iFlows to do the same.

iFlow Variation 1 – XML Validation without Raising an Exception for Invalid XML Messages

Now, let’s enable Prevent Exception on Failure. With this option active, even if the XML is invalid, it will not throw an exception, allowing the message to continue through the iFlow.

Integration Suite will store the Validation results in the header parameter: SAP_XmlValidationResult

• If the XML is valid → SAP_XmlValidationResult = null that means XML is valid.

• if validation fails → this header contains the failure reason. Hence, the parameter SAP_XmlValidationResult will not be null.

Using a Router with an expression such as: ${header.SAP_XmlValidationResult} != null we will create two routes to process valid XMLs and invalid XMLs.

Now let’s configure the response back to the message sender. We will use content modifiers to set the response payload and return the status of the message validation.

In case of failure, it is recommended to return an appropriate HTTP status code to the message sender, preferably one from the 4xx series. For this example, if the message validation fails, we will return HTTP status code 400 (Bad Request) to clearly indicate that the incoming request was invalid.

We can use the CamelHttpResponseCode header parameter to set the HTTP status code in the response message.

Now, let’s test the iFlow with both a valid and an invalid XML message.

Test Scenario 1 – Valid XML

Test Scenario 2 – Invalid XML

Learn how to implement payload validation in SAP Integration Suite iFlows using the XML Validator. This guide covers setup, configuration options, best practices for handling invalid XML messages, returning validation responses to senders, and even a workaround for validating JSON payloads. Perfect for integration developers looking to improve data quality and message reliability.

Notice that the message status in the message monitor will still appear as Successful or Completed even if the XML is invalid. This is because we prevented an exception from being raised for invalid XML messages and explicitly ended the processing using the End Message event.

If you’d like to learn SAP integration step by step, join my SAP Integration Suite course for Beginners, and start building real-world integration skills today.

Learn SAP Integration with me!

This behavior is acceptable since, in end-to-end synchronous scenarios, it is the responsibility of the message-sending system to correct the payload and resend the request. We have already returned the error details to the sender, enabling them to take corrective action.

iFlow Variation 2 – Raise an Exception for Invalid Message and Handle them in the Exception Sub Process

Now let’s uncheck the Prevent Exception on Failure option. This will allow the XML Validator to throw an exception if the incoming message does not comply with the XSD. Once an exception is raised, no further processing of the message will take place, and the exception must be handled in the Exception Subprocess.

We will now handle invalid XML messages in the Exception Subprocess. Therefore, we need to set the response body and the appropriate HTTP status code for the error response within the exception subprocess.

Notice that we will now use the header parameter CamelExceptionCaught instead of SAP_XmlValidationResult. When the exception originates from the XML Validator, CamelExceptionCaught will contain the validation error details, similar to the information previously available in SAP_XmlValidationResult in iFlow Variation 1.

In the main flow, you can continue processing the message for valid XML payloads.

If you test the flow, you will notice that the response sent back to the message sender is the same as in Variation 1. The response body and the HTTP status code are returned to the sender as expected.

If you’d like to learn SAP integration step by step, join my SAP Integration Suite course for Beginners, and start building real-world integration skills today.

Learn SAP Integration with me!

How to Easily Identify Messages Where XML Validation Failed?

As you may have noticed, even when XML validation fails, the message status in the Message Monitor still appears as Successful or Completed.

This is unavoidable if you want to send a custom rbody of the message in the response back, such as a meaningful HTTP status code. To achieve this, you must end the message processing with an End Message event, which in turn sets the message status in the monitor to Completed.

This means you cannot rely on the standard status field to differentiate between valid and invalid messages.

So, how can users easily filter messages that failed XML validation?

In such cases, you can make use of the Custom Status feature in SAP Integration Suite. By setting a meaningful value to the parameter SAP_MessageProcessingLogCustomStatus, you can mark messages where validation failed and later filter them in the Message Monitor.

In this example, we will set the value of SAP_MessageProcessingLogCustomStatus to: XMLValidationFailed

Once configured, you can simply use the Custom Status filter in the Message Monitor to quickly identify messages where XML validation did not pass.

What Kind of Payload Validations Can be Done?

You can validate incoming XML files against the XSD, as all the validation rules are defined within the schema. An XML Validator checks the incoming message against the XSD to determine whether it is valid and suitable for processing.

Below are some examples of the types of validations that can be performed using a properly defined XSD:

Optional / Required Elements

Here the order ID element is mandatory, you know that because minOccurs attribute is not set as zero on this field. While elements such as RequiredDate and ShippedDate are optional as both elements have minOccurs=”0″.

So if any of the madatory fields are not avilable validation fails.

    <!-- ========= Header Segment ========= -->
    <xs:complexType name="HeaderType">
        <xs:sequence>
            <xs:element name="OrderID" type="xs:string"/>
            <xs:element name="CustomerID" type="xs:string"/>
            <xs:element name="OrderDate" type="xs:dateTime"/>
            <xs:element name="RequiredDate" type="xs:dateTime" minOccurs="0"/>
            <xs:element name="ShippedDate" type="xs:dateTime" minOccurs="0"/>
            <xs:element name="DocumentCurrency" type="xs:string"/>
            <xs:element name="PurchaseOrderNumber" type="xs:string" minOccurs="0"/>
            <xs:element name="OrderStatus" type="xs:string" minOccurs="0"/>
        </xs:sequence>
    </xs:complexType>

    <!-- ===== Order Header ===== -->
    <Header>
        <OrderID>0001</OrderID>
        <CustomerID>VINET</CustomerID>
        <OrderDate>1996-07-04T00:00:00Z</OrderDate>
        <DocumentCurrency>EUR</DocumentCurrency>
        <PurchaseOrderNumber>PO-458922</PurchaseOrderNumber>
        <OrderStatus>Confirmed</OrderStatus>
    </Header>

This is valid although ShippedDate and RequiredDate are not available.

    <!-- ===== Order Header ===== -->
    <Header>
       <CustomerID>VINET</CustomerID>
        <OrderDate>1996-07-04T00:00:00Z</OrderDate>
        <DocumentCurrency>EUR</DocumentCurrency>
        <PurchaseOrderNumber>PO-458922</PurchaseOrderNumber>
        <OrderStatus>Confirmed</OrderStatus>
    </Header>

This is inavlid because the mandatory element OrderID is missing

Data Type Validation

You can check values in each element is in the correct type. For example, OrderDate should be of type dateTime. Order data like this <OrderDate>2025-07-04</OrderDate> would fail because it should a timestamp format with data and time like <OrderDate>2025-07-04T00:00:00Z</OrderDate>.

Here is the exact error raised from XML validator, <OrderDate> does not match the required simple type. Invalid dateTime value “2025-07-04” (Too short).

Here are some of the other Built-in types: xs:string, xs:int, xs:decimal, xs:date, xs:dateTime, xs:boolean, etc.

Message Structure

Notice that each segment under the SalesOrder element must appear in the defined sequence.
If any segment is placed in the wrong order, an error will be raised.

<xs:element name=”SalesOrder”>
<xs:complexType>
<xs:sequence>
<xs:element name=”Header” type=”HeaderType”/>
<xs:element name=”CustomerDetails” type=”CustomerDetailsType”/>
<xs:element name=”ShippingDetails” type=”ShippingDetailsType”/>
<xs:element name=”Items” type=”ItemsType”/>
<xs:element name=”Totals” type=”TotalsType”/>
</xs:sequence>
</xs:complexType>
</xs:element>

For example, if I move the Totals segment to an incorrect position, you will see this validation error.

In content of element 
 <SalesOrder>: The content model does not allow element 
 <Q{}Totals> to appear immediately after element 
 <ShippingDetails>. It must be preceded by 
 <Q{}Items>. 

Following are other types of structure rules you can apply in the XSD.

• <xs:all> → all elements present in any order

• <xs:sequence> → elements must appear in order

• <xs:choice> → only one element out of many

Pattern Validation

Lets say you want to make sure the email is a valid email. You can make assign a pattern in the XSD.

<xs:element name=”Email” minOccurs=”0″>
<xs:simpleType>
<xs:restriction base=”xs:string”>
<xs:pattern value=”[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}”/>
</xs:restriction>
</xs:simpleType>
</xs:element>

Then if the email is not in the expacted pattern with @ sign, it will though an error. Such kind of data that should adhere to a defined pattern like a address, email, phone number, etc can be defined in the XSD.

Enumeration

Using Enumeration rules, you can check if the data is valid againist a list of values allowed for that element.

Now lets check if the OrderStatus value comply with the list of allowed statuses.

<xs:simpleType name="OrderStatusEnum">
    <xs:restriction base="xs:string">
        <xs:enumeration value="New"/>
        <xs:enumeration value="Pending"/>
        <xs:enumeration value="Processing"/>
        <xs:enumeration value="Shipped"/>
        <xs:enumeration value="Delivered"/>
        <xs:enumeration value="Cancelled"/>
        <xs:enumeration value="Returned"/>
        <xs:enumeration value="On Hold"/>
    </xs:restriction>
</xs:simpleType>

<!-- ========= Header Segment ========= -->
<xs:complexType name="HeaderType">
    <xs:sequence>
        <xs:element name="OrderID" type="xs:string"/>
        <xs:element name="CustomerID" type="xs:string"/>
        <xs:element name="OrderDate" type="xs:dateTime"/>
        <xs:element name="RequiredDate" type="xs:dateTime" minOccurs="0"/>
        <xs:element name="ShippedDate" type="xs:dateTime" minOccurs="0"/>
        <xs:element name="DocumentCurrency" type="xs:string"/>
        <xs:element name="PurchaseOrderNumber" type="xs:string" minOccurs="0"/>
        <xs:element name="OrderStatus" type="OrderStatusEnum" minOccurs="0"/>
    </xs:sequence>
</xs:complexType>

If you send a value that is not the list it will error out. Allowing you to check for valid values

<OrderStatus>Confirmed</OrderStatus>

The content "Confirmed" of element <OrderStatus> does not match the required simple type. Value "Confirmed" contravenes the enumeration facet "Returned, New, Delivered, On H..." of the type Q{}OrderStatusEnum

Min/Max Values (Numeric or Length)

The following rules allow you to check whether numeric values fall within an allowed range, such as a minimum or maximum value. You can also validate the length of a string value in a similar way.

• Numeric:

  • xs:minInclusive, xs:maxInclusive

  • xs:minExclusive, xs:maxExclusive

• String length:

  • xs:minLength, xs:maxLength

<xs:element name="Quantity">
    <xs:simpleType>
        <xs:restriction base="xs:decimal">
            <xs:minInclusive value="1"/>
            <xs:maxInclusive value="1000"/>
        </xs:restriction>
    </xs:simpleType>
</xs:element>

Workaround to Validate JSON and Other Message Formats

The XML Validator works only for XML. So what is the incoming message is a JSON payload?

Although there is no native palette step for JSON structure validation, as a workaround you can:

1. Convert the JSON to XML using the JSON → XML Converter

2. Create an XSD that represents the structure of the message

3. Validate the converted XML using the XML Validator

This approach allows you to validate JSON messages using the same mechanism as XML.

Now let’s send an JSON message to the iFlow.

You can also write a Groovy script for JSON validation but custom logic should be implemented. Advantage of using the XML validator for JSON messages is that you can use standard features witout creating complex Groovy Scripts.

The downside of this workaround is that the error details will be displayed as XML elements.

Summary

Message validation is a crucial part of any integration flow. Implementing it correctly ensures quality, prevents runtime issues, and helps sender systems quickly correct and resend bad messages.

• Use middleware for structural validation

• Use the receiver for business validation

• SAP Integration Suite provides XML and EDI validators out of the box

We explored the configuration options in the XML Validator and different variations for using the XML Validator palette options. You can handle invalid XML messages either in the Exception Subprocess or by using an appropriate Router Exception. We also looked at some of the rules you can define in the XSD to validate the incoming XML.

In addition, we also looked at how to use a Custom Status to indicate which messages have failed, as well as a workaround for validating incoming JSON messages.

Hope you enjoyed the article! If you’d like to learn SAP Integration with me, check out my Online Course on SAP Integration Suite.

Learn SAP Integration with me!

The post How to Validate Incoming Messages with XML Validator in SAP IS appeared first on SAP Integration Hub.

What Is Idempotency? Definition and Explanation

In computing and system integration, an operation is called idempotent if performing it multiple times produces the same result as performing it once.

In other words, even if the operation is repeated, intentionally or due to retries, network issues, or user error, the final state of the system remains unchanged beyond the effect of the first execution.

To make this concept clearer, let’s look at a simple real-world scenario.

Imagine an e-commerce application that sends sales orders to a backend database or ERP system.
In the ideal or “happy” flow, the e-commerce portal sends the order, the receiver successfully creates the order in the backend system, and then sends an acknowledgment back to the e-commerce application.

In this perfect situation, everything works exactly as expected.

But what happens if the acknowledgment is not received by the sender, even though the backend system actually received and created the order?

In this situation, the sender has no way of knowing whether the order was created successfully or not.
As a result, the sender will naturally try to send the message again.

Now imagine a frustrated user repeatedly clicking the Submit button because they think the order didn’t go through, simply because they never received a confirmation. If each of those clicks creates a new sales order in the backend system, the outcome would be a complete disaster.

And this issue isn’t limited to user actions; many systems have automatic retry mechanisms.
When they fail to receive the expected response, they will resend the message, often multiple times.

This is why it is essential to detect and handle duplicate messages.
This is exactly what we mean when we talk about making a process idempotent: the Backend system should not create new sales orders after the first operation. The interface should identify duplicate messages and prevent them from being processed again.

Only the first valid message should be processed. Any subsequent duplicates should be safely ignored.

Which HTTP Methods Are Idempotent?

When working with HTTP calls, it’s important to understand which methods are idempotent, meaning which methods do not change the result even if they are executed multiple times.

GET Method

Take the GET method, for example. If you send a request to retrieve sales order information from a database, the sender provides the order ID and receives the corresponding order details. Even if the same GET request is sent repeatedly, nothing in the database changes; you are just reading the data, not altering the data. The data in the backend system remains exactly the same. That’s why the GET method is considered idempotent; multiple identical requests do not alter the result of the system.

POST Method

Now, let’s look at POST. A POST request is typically used to create a new resource, in our scenario, a new sales order in the backend system or database. If the same POST request is sent multiple times, it creates multiple orders, changing the system each time. Therefore, POST is not idempotent.

DELETE Method

On the other hand, DELETE is idempotent. You can only delete a resource once. The first DELETE request removes the order; any subsequent DELETE requests for the same order do not make further changes to the database. The system state remains the same after the first deletion.

The same principle applies to other HTTP methods that do not alter the system after their initial execution; they are considered idempotent, because repeated calls do not lead to additional changes.

What Is an Idempotent Receiver?

So, what if the message receiver system itself can identify duplicate messages?

For this to work, each message must include a unique identifier. In our example, this could be the Sales Order ID, which is unique for every order.

The Sales Order ID is assigned by the sender system. When the message reaches the receiver, the receiver can check this ID for uniqueness. If the ID has never been processed before, the receiver processes the order and saves it to the database. It should also store that ID in memory or in a table, so that it can compare future incoming messages against it.

If a message arrives with an ID that has already been processed, the receiver simply ignores it. In this way, the receiver behaves as an idempotent receiver, capable of safely handling duplicate messages.

However, not all receivers are built this way. Some systems cannot handle duplicates and are considered non-idempotent. In such cases, the middleware must take responsibility for ensuring idempotency.

This is where the Idempotent Process Call feature in SAP Integration Suite comes into play. It allows the middleware to detect and handle duplicates before they even reach the backend system, ensuring reliable and consistent processing.

When to Use the Idempotent Process Call in SAP Integration Suite

In cases where the backend system is non-idempotent, it cannot detect or manage duplicate messages on its own. Or if the HTTP method used is non-idempotent. That’s where the middleware must take responsibility.

As discussed earlier, a unique ID is required to identify duplicates. In our scenario, the unique reference is the Sales Order ID included in the order XML.

This ID serves as the key for the middleware to check whether a message has already been processed. If the middleware encounters this Sales Order ID for the first time, it allows the message to pass through to the backend system.

If the same ID appears again, whether due to network retries, system errors, or users clicking “Submit” multiple times, the middleware can safely ignore the duplicate message.

By implementing this check, the middleware ensures that the backend system receives each order only once, even if the message has been sent multiple times.

Prerequisites for Using the Idempotent Process Call in SAP Integration Suite

One of the prerequisites for using the Idempotent Process Call in SAP Integration Suite is that we must have a unique ID to identify each message (or iteration). This ID is then used to detect duplicates and ignore any subsequent duplicate messages associated with that same ID.

This unique ID can be taken from the payload, or it can be a technical ID generated by the sender adapter — such as a UUID, GUID, Transaction ID, etc.

In simple terms, it just needs to be unique for every incoming request.

Example: Idempotent Process Call Flow in SAP Integration Suite

Now let’s look at a real-life example with the sales order scenario we looked at earlier.

Here is the incoming message format.

<?xml version="1.0" encoding="UTF-8" ?>
 <Order>
     <OrderID>10250</OrderID>
     <CustomerID>VINET</CustomerID>
     <EmployeeID>5</EmployeeID>
     <OrderDate>1996-07-04T00:00:00Z</OrderDate>
     <RequiredDate>1996-08-01T00:00:00Z</RequiredDate>
     <ShippedDate>1996-07-16T00:00:00Z</ShippedDate>
     <ShipVia>3</ShipVia>
     <Freight>32.38</Freight>
     <ShipName>Vins et alcools Chevalier</ShipName>
     <ShipAddress>59 rue de l'Abbaye</ShipAddress>
     <ShipCity>Reims</ShipCity>
     <ShipRegion></ShipRegion>
     <ShipPostalCode>51100</ShipPostalCode>
     <ShipCountry>France</ShipCountry>
 </Order>

Our unique ID is the Sales Order ID. We should process each sales order only once, meaning it should be sent to the backend system only a single time. Any subsequent messages with the same Sales Order ID should be ignored.

For the receiver system, I created a webhook on Beeceptor, which sends back an acknowledgment whenever it receives an order. It works as a ready-to-use mock server that requires no setup or signup. You can use Beeceptor to tailor response payloads, adjust status codes, reuse request parameters, and shape mocks from your OpenAPI specifications. This is the fastest way I have found to validate message flows before connecting to real downstream systems.

As you can see, the webhook does not check for duplicate orders; it simply accepts every message that arrives. We can imagine that it would create a new order each time a message is received.

Therefore, the middleware must handle duplicates and safely ignore them, ensuring that no duplicate messages are sent to the webhook receiver.

Develop an iFlow with an Idempotent Process Call in SAP Integration Suite

Create a Local Integration Process that sends the message to the receiver. In this case, the sales order message is sent to the webhook. This Local Integration Process will be called by the Idempotent Process Call.

Extract the unique ID, which is the sales order ID, using an XPath expression from the payload.

Configure the Idempotent Process Call using the Local Integration Process and Unique Message ID options.
For this scenario, let’s keep Skip Process Call for Duplicates enabled. This means that when the message reaches the Idempotent Process Call, if it is identified as a duplicate based on the Message ID, the local integration process will not be triggered.

Now, let’s test the interface.

Send a unique message, for example, a new sales order.

Lets send a duplicate message, the same order.

Notice that the Idempotent Process Call skips the local Process Call being executed.

Use of CamelDuplicateMessage and Customize Duplicate Handling

In the previous flow, we explored the Idempotent Process Call with the option “Skip Process Call for Duplicates” enabled. Notice that when this option is selected, the local process call is not executed for duplicate entries.

If you’d like to learn SAP integration step by step, join my SAP Integration Suite course for Beginners, and start building real-world integration skills today.

Learn SAP Integration with me!

However, you can also deselect the “Skip Process Call for Duplicates” option and handle duplicates manually by using the exchange header property CamelDuplicateMessage. When this option is deselected, the local integration process will be executed even for duplicate messages, which means you must implement your own duplicate-handling logic.

If the Idempotent Process Call detects that a message is a duplicate based on the unique Sales Order ID, the CamelDuplicateMessage header will be set to true. If it is not a duplicate, the value will be false.

In this example, I will use a Router to check whether the message is a duplicate. If it is, I will return a message to the sender stating: “Order ID XXX was already processed and will be ignored.”

Additionally, we will send a meaningful HTTP 4XX response back to the sender to indicate that the message is a duplicate using the header parameter CamelHttpResponseCode. For this scenario, I will use the HTTP response code 409 (Conflict) to clearly signal that the request conflicts with an already processed order.

Now let’s test the interface with the customized behavior.

First, we send a new sales order.

Then, let’s try sending the same sales order again.

Notice that the response body is meaningful, and the 4xx HTTP status code clearly indicates a bad request due to a conflict. Of course, you can use other 4xx HTTP response codes based on your design preference.

If you’d like to learn SAP integration step by step, join my SAP Integration Suite course for Beginners, and start building real-world integration skills today.

Learn SAP Integration with me!

Idempotent Repository and Validity Period

The Idempotent Process Step identifies whether a message is a duplicate by storing the unique Message ID (configured under the Message ID option) in the tenant’s Idempotent Repository, in our example, this is the Sales Order ID.

When a new request arrives, SAP Integration Suite checks whether this ID already exists in the repository. If it does, the message is considered a duplicate, and the Local Integration Process is skipped.

Keep in mind the 90 days rule!

However, note that the idempotent repository data is retained for 90 days only. After 90 days, the stored Message IDs are removed, meaning duplicate checks can only be performed within a 90-day window from the first message execution. In most real-world scenarios, this time frame is more than sufficient — just keep this in mind when designing your interfaces.

I hope you learned something new from this article. We explored the concept of Idempotency in system integration, compared idempotent vs non-idempotent HTTP calls, and discussed when it’s necessary to handle duplicate requests in the middleware. Especially when the receiver system is not idempotent.

Additionally, we walked through an end-to-end iFlow example, covering how to build an iFlow using the Idempotent Process Call, along with its configuration steps. We also looked at how to send a meaningful response back to the sender when a duplicate or invalid request occurs, using appropriate 4xx HTTP response codes.

If you would like to learn SAP Integration Suite with me, I’ve created an online course with 200+ video lessons. Check out the syllabus and sign up to become a confident SAP Integration Consultant.

Learn SAP Integration with me!

The post How to Implement Idempotent Process Call in SAP Integration Suite appeared first on SAP Integration Hub.

Of course, SAP provides some standard search parameters such as Message ID, Correlation ID, and even the option to filter messages by a specific time period. However, these parameters are mostly technical and not directly connected to the business context.

For example, how can you search for all Sales Order messages, all Delivery Documents, or even find messages based on a specific Sales Order Number or Delivery Number? What if you need to filter by sender or target system names? These kinds of business-friendly searches are not possible without customization in SAP Integration Suite.

This is where standard and custom header parameters come into play. By leveraging them, you can enrich your monitoring capabilities with business-relevant information, making message tracking and troubleshooting much more efficient.

Standard Header Parameters Available to Filter Messages

SAP provides a standard set of header parameters in the exchange envelope. Some of these standard parameters can be leveraged to add custom filter options in the Message Monitor.

Here are the standard parameters you can use:

• Message ID – The unique identifier that is associated with the message processing log (MPL).

• Correlation ID – The identifier used to correlate different messages with each other that are processed jointly in the context of an integration scenario.

• Application Message ID – Identifier set by a dedicated header (SAP_ApplicationID).

• Sender – Identifier set by a dedicated header (SAP_Sender).

• Receiver – Identifier set by a dedicated header (SAP_Receiver).

• Custom Status – Identifier set by a dedicated exchange property (SAP_MessageProcessingLogCustomStatus).

• Application Message Type – Identifier set by a dedicated header (SAP_MessageType).

Message ID and Correlation ID are quite technical and form the basis of the message processing log, so we will leave them as they are. Of course, you can still use these two values to filter messages.

You can assign values to any of these header parameters during integration processing at runtime, and later use those values to filter messages in the Integration Monitor.

Sample Integration Scenario to Demonstrate Message Monitoring Customization

To demonstrate this, let’s imagine we have an interface that processes product master data from your PLM system to SAP S/4HANA. For example, you may want to filter messages based on the Product ID, Catagory ID, Supplier ID or other business-related data. That is the information that is part of the actual message payload.

For demonstration purposes, we will simply save the product information in a data store, using the data store entry ID as the Product ID.

{
    "value": [
        {
            "ProductID": 51,
            "ProductName": "Gravad lax",
            "SupplierID": 20,
            "CategoryID": 9,
            "QuantityPerUnit": "12 - 500 g pkgs.",
            "UnitPrice": 26.0000,
            "UnitsInStock": 11,
            "UnitsOnOrder": 50,
            "ReorderLevel": 25,
            "Discontinued": false
        }
    ]
}

Here is the incoming JSON message from the PLM system.

In the integration flow, we will first convert the JSON message to XML, and then extract the Product ID from the payload to use as the entry ID in the data store.

Now let’s process some messages through the interface. If you go to the Message Monitor, you will notice that in the Properties section you only see the Message ID and Correlation ID, and nothing else.

But what if you need to search for messages based on the Product ID? In this case, we want to filter messages using the Product ID that comes in the incoming payload.

Using Standard Header Parameter to Filter Messages

To filter messages based on the business object ID, we need to set its value in the standard header parameter SAP_ApplicationID. We can achieve this by extracting the Product ID from the payload and assigning it to this parameter.

Use a Content Modifier step to set the value of the header parameter SAP_ApplicationID.

Now, let’s process another product and see the message monitor.

Now you can not only view the business document number processed by the message without digging into the payload, but also use this value to filter messages. In the standard filter “ID”, you can now enter this value to quickly find the relevant messages.

Not just SAP_ApplicationID, let’s set all the other standard parameters as well, such as;

• SAP_Sender

• SAP_Receiver

• SAP_MessageType

We will set the sender system as PLM, the receiver system as S/4HANA, and the application type as “Product Master”.

Now process a message and notice that all the values we set using the Content Modifier in the iFlow are visible in the Properties section of the Message Monitor.

Now you can use any of these filter criteria to filter messages.

For example, let’s filter the messages for Product ID, 40. You can use the ID field in the Message Monitor to do this. In the same way, you can use all other standard parameters.

Now, imagine having many interfaces and needing to filter messages based on sender system, target system, document type, etc. All of this is possible if you set the values correctly for these standard parameters during runtime.

Using Additional Filter Criteria with Custom Header Properties

⚠️ Warning

Now we have used all the standard parameters available for additional filtering.

Let’s imagine we have another key data field we want to use to filter messages in SAP Integration Suite.

For example, suppose we want to filter messages by the incoming payload’s data field “CategoryID”.

We will add a new custom header parameter with the value of CategoryID extracted from the payload.

To set a custom header parameter, we need to create a Groovy script.

First, we will extract the required information from the payload, in this example, the CategoryID.

We will use an XPath expression with a Content Modifier to achieve this.

Then we have to set a new custom header property with the value of the category ID.

Now, from this Groovy script, we will set a custom header property named “productCategory” with the value of the exchange property “productCategory” that we set earlier using the Content Modifier.

Let’s process another product and see how the custom header property appears in the Message Monitor.

How do we now filter messages in the Integration Suite based on a custom header property?

In this example, let’s filter messages with Category ID 9.

To do this, add the Custom Header filter criteria by specifying the header property name and the corresponding value.

To summarise, filtering and monitoring messages in SAP Integration Suite can be challenging when dealing with multiple interfaces and large volumes of data. While standard search parameters like Message ID and Correlation ID provide basic filtering, they are often too technical for business-oriented monitoring. By leveraging standard header parameters such as SAP_ApplicationID, sender system, receiver system, and application type, you can add meaningful business context to your messages and enable more effective filtering in the Message Monitor.

💡 Tip

For scenarios requiring additional business-specific criteria, custom header parameters offer a great solution. By extracting values from the message payload and setting them as custom headers using Groovy scripts, you can filter messages based on business attributes, such as Order Number, Invoice Number, Article ID, etc.

This approach transforms the Integration Suite’s Message Monitor into a more intuitive and business-focused tool, allowing for faster filtering of messages, improved monitoring, and more efficient message tracking across your interfaces.

The post Message Filtering with Standard & Custom Headers in SAP Integration Suite appeared first on SAP Integration Hub.

In greenfield SAP S/4HANA implementations, it’s common to see the backend SAP system using either SOAP or OData APIs for integrations instead of iDocs. However, there is a significant difference in how messages are monitored and reprocessed in iDoc-based interfaces compared to those using SOAP and OData APIs.

The key differences between iDocs and SOAP/OData APIs in SAP S/4HANA lie in their communication patterns and technical behavior.

Key Differences Between iDocs and OData/SOAP APIs in SAP S4 HANA

Asynchronous iDocs vs Synchronous API

iDocs are asynchronous in nature, while OData APIs are synchronous. SOAP services can operate in either asynchronous or synchronous mode, depending on how they are configured.

Another important distinction is that iDocs are stateful, whereas web APIs like OData and SOAP are stateless. In simpler terms, OData APIs require an external request to be triggered, and there is always a request-response interaction. On the other hand, iDocs do not require an external trigger, SAP can push data out asynchronously without waiting for a request.

Interface Message Persistence in SAP S4 HANA

A major difference is in message persistence. iDoc messages are stored in the SAP system in database tables such as EDIDC, EDID4 and other EDIC tables, regardless of whether they result in success or failure. This means both successful and failed iDocs are persisted and can be monitored and analyzed at any time, as long as they are not archived. SAP customers can configure how long iDocs remain in the system, providing flexibility in message retention.

In contrast, for OData calls, only error messages are logged. Successful API calls are not persisted in the standard SAP system. For example, if a sales order is created in SAP S/4HANA using an OData API, only failed calls will appear in the error logs; successful messages are not visible in standard monitoring tools. To the best of my knowledge, there is no standard option to enable monitoring of successful OData calls in SAP S/4HANA.

However, for SOAP API calls, both successful and error messages are available in SAP S4 HANA, and you can monitor the messages using the transaction SRT_MONI.

Monitoring of OData/SOAP APIs vs iDocs in SAP S4 HANA

Due to the way messages are persisted, monitoring iDocs is straightforward. You can use transactions such as WE02 and WE05 to monitor iDocs easily. In many organizations, iDoc messages are retained for several months before older records are archived and removed from the system. As a result, monitoring iDoc-based interfaces in SAP is generally not a concern.

However, when it comes to OData APIs, the situation is different. Unfortunately, you can only see messages that end in error. If an OData call fails, it is logged and can be viewed in standard transactions /IWFND/ERROR_LOG, /IWFND/TRACES.

OData Message Selection Screen – Transaction IWFND/ERROR_LOG

But what if you want to check successful OData API calls? At the moment, this is not supported by standard SAP S4 HANA tools. There is no built-in way to trace successful OData API calls using standard monitoring transactions.

Only the erroneous OData calls are logged in SAP S4 HANA. You can see the error code, HTTP response code, time stamp, error description and other details related to the message in this transaction.

Select an OData message to drill down to further detail.

If you need to monitor successful API calls, one option is to leverage the Application Interface Framework (AIF). By building an AIF interface on top of the OData service, you can add logging and monitoring capabilities for both successful and failed calls but this requires custom development.

SOAP APIs you have the option of monitoring message directly in SAP S4 HANA using transaction SRT_MONI.

Here you can find the information such as processing statuses, interface or the SOAP API name, messages ID, and the timestamp of the SOAP messages processed. Notice, unlike the OData messages, both successful and error messages are available in SRT_MONI.

Automatic Message Reprocessing Limitations for OData API Based Interfaces

There are scenarios where an interface message fails due to an issue within the SAP S/4HANA system. For example, missing master data, incomplete configuration, document locked by another user at the time of message processing (locking issue), or other application-level errors relevant to SAP. In such cases, we are accustomed to fixing the root cause in SAP and then reprocessing the message directly within the SAP S4 HANA system.

However, due to the stateless and synchronous nature of OData services, it is not possible to simply reprocess failed OData messages automatically within SAP itself.

In iDoc-based scenarios, it is common to have scheduled background jobs that regularly scan for failed iDocs and automatically reprocess them. This kind of built-in, automated recovery mechanism is a standard feature of iDoc handling.

Unfortunately, this option does not exist for OData services. There is no native way to automatically reprocess failed OData messages via a background job in SAP periodically. Instead, you have to rely on other methods, which we will discuss later in the article.

However, for SOAP API based messages, you can reprocess messages using a batch job directly in SAP S4 HANA.

Workarounds for Monitoring Limitations in SAP S/4HANA

There are a few ways to overcome the message monitoring limitations in SAP S/4HANA, especially when it comes to tracing successful messages for OData and SOAP APIs.

Leverage SAP Application Interface Framework (AIF)

The first option is to leverage SAP Application Interface Framework (AIF) in S/4HANA. You can build an AIF interface for each API-based integration to log and monitor both successful and failed messages. However, this approach requires custom development. That said, it’s a good option when business users need visibility into interface processing from within SAP.

Monitoring capabilities of SAP Integration Suite

Another approach is to use the monitoring capabilities of SAP Integration Suite. In most SAP S/4HANA landscapes, a middleware is involved for managing integrations, and SAP Integration Suite (SAP IS) is often the preferred platform. You can use the message monitoring features of SAP Integration Suite (or any other middleware in use) to trace and log both successful and failed messages. You can also choose to store message payloads for high-priority interfaces.

If you’d like to learn SAP integration step by step, join my SAP Integration Suite course for Beginners, and start building real-world integration skills today.

Learn SAP Integration with me!

Access the SAP Integration Suite message monitor and you can find an overview of all the interfaces.

From there, you can drill down to each interface for further analysis.

Here you can find the request and reply payloads of the OData call.

Leverage SAP Cloud ALM (CALM)

Additionally, you can also leverage SAP Cloud ALM (CALM) for end-to-end interface monitoring, regardless of the technology used. CALM provides centralized monitoring and traceability across different systems. However, it’s important to note that message payloads are not logged in CALM. Only certain metadata and trace parameters are available for analysis.

How to Handle Message Reprocessing Requirements for OData and SOAP

When it comes to overcoming message reprocessing challenges in SAP S/4HANA, let’s look at the available options.

SOAP API Message Reprocessing

The easiest scenario to handle is with SOAP APIs. For both inbound and outbound interfaces; that is, messages coming into SAP as well as those going out, and for both asynchronous and synchronous SOAP APIs, you can reprocess messages directly in SAP using a standard program.

Even if the error originates in SAP Integration Suite, the SOAP error log still captures the message details in SAP S/4HANA. These logs are accessible via transaction SRT_MONI, which allows you to view and reprocess failed messages.

How to automate SOAP message reprocessing?

Because of this logging, it is also possible to automate the reprocessing of failed SOAP messages periodically within SAP via a batch job. You should be able to use the program “SRT_UTIL_RESTART” to set up a batch job to reprocess errornous messages automatically.

How to Reproceses OData APIs for Inbound Interfaces?

Let’s consider a scenario where the interface is inbound, and we are using an OData API to post data into SAP S/4HANA. In this case, messages are sent from an externally connected system, which acts as the message sender.

Since OData follows a request-reply pattern, the sender system must use the appropriate method, such as POST or PATCH to call the OData service and send the request along with the payload. SAP processes the request and returns a response, which includes the status of the message (success or failure), error codes in case of failure, and, if successful, the business document number (e.g., sales order number).

However, if there is an error on the SAP side, for example, due to missing configuration or master data, the failure is still communicated in the response. Because OData is stateless and synchronous, SAP S4 HANA independently reprocessing the erroneous message does not make sense, and reprocessing must be triggered from the sender system.

Alternatively, you can also implement a queue-based approach in SAP Integration Suite using JMS queues, allowing you to reprocess failed messages directly from the Integration Suite once the issue in SAP has been resolved.

Even though the root cause of the failure lies in SAP, there is no standard way to reprocess the message within SAP once the issue is resolved. The only option is to resend the request from the sender system or SAP Integration Suite.

Manually Reprocess Erronous OData Messages in SAP S4 HANA

However, there is an option to manually reprocess OData calls on the SAP S/4HANA side. You can use the “Replay” option in transaction IWFND/ERROR_LOG.

Note: The payload of the request can be edited, meaning the user can modify the data without any restrictions. This approach is not suitable for a production landscape, as users would be able to post data without proper control mechanisms.

Additionally, the response from the OData call will not reach SAP Integration Suite or the connected system, which can disrupt end-to-end integration scenarios.

Moreover, the view itself is quite technical, and you need to manually define the JSON message structure. This option may be appropriate for support users, system administrators, or specially authorized users for exceptional cases.

I hope this gave you a clear overview of how monitoring and automatic error reprocessing for SAP OData and SOAP APIs differ from iDoc-based interfaces. Due to the nature of API-based integrations, it’s important to design your interfaces thoughtfully, keeping these limitations and capabilities in mind.

If you’d like to learn SAP integration step by step, join my SAP Integration Suite course for Beginners, and start building real-world integration skills today.

Learn SAP Integration with me!

The post OData/SOAP API Message Monitoring and Reprocessing in SAP S4 HANA appeared first on SAP Integration Hub.

For example, imagine a scenario where you are connected to a database system and need to insert or update data records, where the order of SQL statements is important. This could be for order processing, delivery tracking, or financial document posting. In such cases, it is critical to maintain the correct sequence of message processing.

Messages should be processed in the order they are received. If a particular message fails, any subsequent messages should not be processed until the failed message is successfully retried and completed.

In this article, we will explore:

1. How Exclusive JMS queues in SAP Integration Suite enable EOIO processing

2. A step-by-step implementation and configuration guide using the JMS Exclusive queue option

Understanding EOIO and Other Message Processing Methods

Let’s understand the difference between EOIO and other message-processing techniques when it comes to SAP or system integration.

Best Effort (BE) – Messages are processed as they arrive, with no guarantee of order.

Exactly Once (EO) – Ensures a message is processed only once, avoiding duplication but without enforcing order.

Exactly Once In Order (EOIO) – Ensures that messages are processed in the exact sequence they were received and that no subsequent message is processed until the previous one is completed.

Can an Exclusive JMS Queue in SAP Integration Suite Achieve EOIO?

As of now, SAP Integration Suite provides two types of JMS queue options: Exclusive and Non-Exclusive.

JMS queues of type Exclusive cannot be processed by multiple worker nodes or multiple consumers. Messages in an Exclusive JMS queue can only be processed by a single node, ensuring in-order processing. The JMS sender adapter picks up and processes messages sequentially, from the oldest to the newest, in the exact order they were received.

If a message in the JMS queue fails to process, the messages that come after it will not be processed until the failed message is successfully retried and completed. This makes the Exclusive JMS queue a viable option for scenarios where message order is crucial or where EOIO (Exactly Once In Order) processing is required.

While Non-Exclusive JMS queues allow messages to be processed by multiple nodes or consumers, they do not guarantee the order of processing.

Sample iFlow with Exclusive and Non-Exclusive Queues

To demonstrate the difference in behavior between Non-Exclusive and Exclusive queues, I created the following integration flows:

Message Producer iFlow

• Flow 1 produces messages and places them in two queues: one in an Exclusive Queue (ProductQueueExclusive) and the other in a Non-Exclusive Queue (ProductQueue_NonExclusive).

Message Consumer iFlow(s)

• There are two JMS listeners (consumer iFlows): one retrieves messages from the Exclusive Queue, and the other retrieves messages from the Non-Exclusive Queue.

iFlow that Consumes Messages from JMS Exclusive Queue

iFlow that Consumes Messages from JMS Non-Exclusive Queue

Testing the Behavior of Exclusive vs Non-Exclusive JMS Queue Consumption

I have pushed the same 3 messages to both JMS queues. They are now waiting to be picked up and processed by the respective iFlows.

JMS Non-Exclusive Queue Consumer

In the Non-Exclusive queue, you will notice that the consumer picks up all the messages from the queue. In this example, all three messages are picked up and attempt to process them.

Hence, you see all messages in failed status as they cannot be moved to the target Cloud HANA DB, as the receiver system is offline.

JMS Exclusive Queue Consumer

However, in the Exclusive queue, only the first message that entered the queue is picked up for processing.

Other Considerations when Working with JMS Exclusive Queues

Header Parameter SAPJMSRetries is Not Available for Exclusive Queues

💡 Tip

We usually use the JMS header parameter SAPJMSRetries to determine how many times a message has been attempted for processing by the JMS sender adapter. Based on this, we can build logic to set a maximum number of retries and send the message to a Dead Letter Queue (DLQ) if SAPJMSRetries exceeds the defined limit. This is typically done to prevent endless message processing.

⚠️ Warning

However, the SAPJMSRetries header parameter is only available for Non-Exclusive queue consumers. If you are using an Exclusive queue, you cannot use the SAPJMSRetries header parameter.

What If the Adapter and Message Producer Do Not Support EOIO?

In my view, even if you use JMS Exclusive queues, EOIO in SAP Integration Suite cannot be guaranteed if the message producer does not ensure EOIO processing.

For example, if messages are produced by SAP S4 HANA and are being sent by the SOAP adapter, XI adapter, or HTTP adapter, and the sender-side adapter or SAP system does not guarantee that messages are received in the correct order to SAP Integration Suite, then we cannot ensure EOIO behavior for the end-to-end (E2E) scenario just by using a JMS queue.

Do Not Use Exclusive Queue for Everything.

⚠️ Warning

Notice that in exclusive JMS queues, if a message fails, all other messages that come afterward in the queue are not picked up for processing. One failure in a message can disable the processing of all subsequent messages.

That means a total failure of the entire message pipeline. Imagine you use an exclusive queue for delivery processing. Would you want to hold the processing of all deliveries just because one delivery fails to process?

Summary of EOIO Processing with JMS Queues in SAP Integration Suite

Unlike in SAP PI/PO, SAP Integration Suite did not initially have a standard mechanism for processing messages in EOIO (Exactly Once In Order) mode.

However, with the introduction of the “Access Type” feature in the JMS adapter, we now have the option to process messages in a FIFO sequence. By using an “Exclusive” JMS queue, messages can be picked and processed sequentially, from the first arrived to the last.

However, ensure that the message producer can guarantee EOIO; otherwise, maintaining the correct sequence may not be possible when you take the E2E integration.

The post EOIO Processing with JMS Exclusive Queues appeared first on SAP Integration Hub.

However, in the past, when consuming an API via the HTTP adapter, if the call failed, there were no built-in options to automatically retry the request. Instead, you had to rely on other techniques like asynchronous decoupling with JMS queues to retry failed messages in the HTTP receiver adapter.

That said, there are certain cases where an automatic retry from the adapter itself would be beneficial. For example, in a high-available system (HA), message failures can sometimes be temporary. In such cases, it would be advantageous for the adapter to automatically retry the request, improving reliability without additional manual intervention or overcomplicating the integration scenario. Additionally, you might be able to save some JMS resources in your tenant.

How the Retry Mechanism Works in HTTP Receiver Adapter

If an HTTP request fails with an unsuccessful status, such as 500, 404, or 420, and the retry option is not enabled, the message enters a failed status in SAP Integration Suite, and message processing ends there.

However, with the retry option enabled, if an HTTP request through the HTTP adapter fails, iFlow can automatically retrigger the message a certain number of times. When configuring the adapter, you can specify for which status codes you want the retry mechanism to activate.

The advantage is that for scenarios such as the receiver is temporarily unavailable, the business process will not be affected. The message can be automatically delivered with the next retry.

For example, HTTP status codes between 300 to 599 are considered error statuses. However, in the adapter settings, you can filter specific status codes for which the retry mechanism should be triggered.

The retry mechanism works as follows: If the initial message delivery fails, the message enters a “Processing” status, which you can see in the Message Monitor.

Then, based on the “Retry Interval (in seconds)” configured in the HTTP Receiver Adapter, the first retry attempt will be triggered after the specified interval. If that retry also fails, the mechanism will continue attempting to resend the message if you have configured “Retry Iterations” as more than 1.

The maximum number of retries can also be configured in the adapter. Currently, the maximum number of automatic retries is 3.

For example, if you set the “Retry Interval (in seconds)” to 10 seconds and “Retry Iterations” to 2, the message will be automatically retried every 10 seconds, for up to 2 times, after the initial failure.

Configuring the Retry Option in HTTP Receiver Adapter

One of the prerequisites for the Retry option is that you must have “Throw Exception On Failure” enabled in the adapter. This setting ensures that the message status in SAP Integration Suite goes into a failure state when the remote receiver (server) returns a failed response. Generally, this option allows you to receive all HTTP response codes from the remote server, regardless of their status.

Retry Failed Requests

This option enables automatic retries for failed messages in the HTTP adapter. By default, this option is disabled. When you enable it, the corresponding adapter configuration options, such as “HTTP Error Response Codes,” “Retry Interval (in seconds),” and “Retry Iterations” are also enabled.

In this example, I want the messages to be automatically reprocessed only if the response contains HTTP status codes 500, 404, or 420.

HTTP Error Response Codes

Here, you can provide a comma-separated list of HTTP error codes that should trigger the retry mechanism in the integration flow. The retry will not start for any other error statuses not specified in the configuration.

Retry Interval (in seconds)

This setting defines how long the integration flow must wait after each failed message delivery before retrying. The maximum retry interval is 60 seconds.

Retry Iterations

This option allows you to set the maximum number of retries for message delivery. The highest number of retries you can configure is 3.

Testing HTTP Automatic Retry Mecanisum in Action

When the interface is start processing for the first time, If an error status is received from the receiver, the message processing status changes to ‘Processing’.

Then, based on the configuration of the HTTP adapter, automatic retry starts. The first retry occurs after 60 seconds. Thereafter, the processing will restart every 60 seconds.

Once the interface processing reaches the maximum number of retries, in this example, 3, the message goes into error if the error still persists in the last retry.

Other Considerations When Implementing the HTTP Retry Mechanism

What if you have an exception subprocess in your iFlow?

If you use an exception subprocess, it is invoked only after all retry iterations configured in “Retry Iterations” are exhausted and the error continues to persist.

What if the retry instruction comes from the response of the target system?

If the target system provides reprocessing instructions in the “Retry-After” header parameter, the retry configuration set in the HTTP adapter is overwritten with the values received from the target system.

Keep these factors in mind when designing your iFlow with HTTP automatic retry enabled.

I hope you learned something new. To become confident in all the features of SAP Cloud Integration feature of SAP Integration Suite, join my online course.

The post Retry Failed Requests in HTTP Receiver Adapter – BTP IS appeared first on SAP Integration Hub.

This post will explain what a query is, how you can identify and use queries, and provide a list of commonly used OData query parameters along with examples.

What Is a Query?

A query is a mechanism that allows an API consumer to request specific data, filtering, sorting, and formatting the result set according to certain parameters. Instead of receiving all the data at once, you can use a query to retrieve just the information you need, which makes interactions with the API more efficient and tailored.

You pass queries as query string parameters. These parameters are attached to the end of the URL and modify the API response.

This allows you to:

• Filter the data by a specific condition (e.g., “show only products in the ‘Electronics’ category”).

• Sort the data by a particular field (e.g., “order products by price in descending order”).

• Select specific fields to include in the response (e.g., “only return product names and prices”).

How Can I Find the Query?

A typical SAP OData request URL looks like this:

https://<server>:<port>/sap/opu/odata/sap/<service_name>/Products?$select=Category,Name

• https://: The protocol used for communication (HTTPS ensures data security).

• <server>:<port>: The address of the SAP server hosting the OData service.

• /sap/opu/odata/sap/<service_name>: The path to the OData service (in this case, <service_name> is the name of your OData service).

• /Products: This is the specific entity set or resource being requested (in this case, a collection of products).

• ?$select=Category,Name: This is the query string, which modifies the request to return only the Category and Name fields from the Products entity set.

The query string begins with a ? and consists of key-value pairs separated by &. Each pair represents a query parameter and its corresponding value.

The Query String Explained

An example query string might look like this:

code$filter=Category eq 'Electronics'&$orderby=Price desc&$top=10

• Key: The name of the query parameter (e.g., $filter, $orderby).

• Value: The instruction or condition for the parameter (e.g., Category eq 'Electronics').

• Multiple query parameters can be used in a single request, each separated by an ampersand (&).

Common Query Parameters in SAP OData

Here is a list of common OData query parameters, their functions, and examples of how to use them:

1. $filter

   • Used to filter results based on specific criteria.

   • Example: ?$filter=Name eq 'John' and Age gt 25

   • This filters the data to return only records where the Name is “John” and the Age is greater than 25.

2. $orderby

   • Used to sort the results by one or more properties.

   • Example: ?$orderby=Name asc

   • This orders the data by the Name field in ascending order.

3. $top

   • Specifies the number of records to return from the top of the result set.

   • Example: ?$top=10

   • This returns only the top 10 results from the dataset.

4. $skip

   • Skips a specified number of records before returning the result set (useful for pagination).

   • Example: ?$skip=5

   • This skips the first 5 records and returns the rest.

5. $select

   • Restricts the response to include only specific properties of an entity.

   • Example: ?$select=Name,Age

   • This returns only the Name and Age fields of the entity.

6. $expand

   • Expands related entities inline, allowing navigation properties to be included in the response.

   • Example: ?$expand=Orders

   • This includes the related Orders entity in the response.

7. $count

   • Returns the total number of entities in the collection.

   • Example: ?$count=true

   • This returns the count of entities alongside the actual data.

8. $format

   • Specifies the format of the response data (e.g., JSON or XML).

   • Example: ?$format=json

   • This requests the response data in JSON format.

9. $search

   • Performs a full-text search on the data.

   • Example: ?$search='Product123'

   • This performs a search for the term 'Product123' across relevant fields.

10. $inlinecount (now often replaced by $count)

    • Returns the count of items in the result set along with the data.

    • Example: ?$inlinecount=allpages

    • This includes the total number of entities in the response, which is helpful when paginating.

11. $batch

    • Used for batch processing of multiple requests in a single call.

    • Example: /sap/opu/odata/sap/your_service/$batch

    • This combines multiple requests into a single HTTP call for efficiency.

12. $skiptoken

    • Used for paging through large result sets by retrieving the next set of records.

    • Example: ?$skiptoken=<token_value>

    • This retrieves the next “page” of results, starting from where the last request ended.

Example SAP OData Query in Action

Let’s say you want to retrieve the top 5 products in the “Furniture” category, ordered by their release date in descending order. You also only want to see the ProductName and ReleaseDate fields in the response.

Your request might look like this:

https://<server>:<port>/sap/opu/odata/sap/ZPRODUCT_SRV/Products?$filter=Category eq 'Furniture'&$orderby=ReleaseDate desc&$top=5&$select=ProductName,ReleaseDate

Breaking it down:

• ?$filter=Category eq 'Furniture': Filters the products to only return those in the “Furniture” category.

• &$orderby=ReleaseDate desc: Orders the products by release date in descending order.

• &$top=5: Limits the results to the top 5 products.

• &$select=ProductName,ReleaseDate: Only includes the ProductName and ReleaseDate fields in the response.

Conclusion

Understanding SAP OData queries is essential for efficiently working with large datasets and APIs. By mastering the use of query parameters, you can tailor the API responses to meet your exact needs, retrieving just the right data in the right format.

Whether you’re filtering by specific conditions, ordering your results, or expanding related entities, queries allow you to control how the data is returned, making your interactions with the API both precise and powerful.

Pro Tip: Always check your SAP OData service documentation to ensure the available query parameters and their supported values for specific entities.

I hope you learned something new. To become confident in all the features of SAP Cloud Integration feature of SAP Integration Suite, join my online course.

The post Understanding SAP OData Query Parameters: A Guide for SAP API Consumers appeared first on SAP Integration Hub.