Hi, I'm Alex

Building a custom web app with integration to SAP S/4HANA - part 2

project

by Alexander Roan on 8 Aug 2025

Building the integration flow details

If interested to experiment with SAP Integration Suite, I'd suggest working through the CodeJam. A lot of effort has been put into the instructions and reference information. It also includes additional mock servers and covers integration with other technologies.

SAP CodeJam

The instructions are on a GitHub repository.

In the following section I'll share some tips and recommendations from my own notes including the basics of the various tools involved.

Building this will involve encountering issues and require some debugging, just reference the documents and use google on errors.

Information sources & tools

SAP Accounts: BTP and Integration Suite

A trial account for business technology platform is required.

BTP trial

And a a trial for Integration Suite

Integration Suite trial

See the pre-requisites pre-requisites document in the CodeJam repository.

Containerisation & Docker

When running the S/4HANA business partner mock server locally, one option is to install the necessary JavaScript runtime environment and run it manually. Another option is to run it inside a container.

Containers are a key concept in Cloud architecture.

A container packages an app and all it's dependencies together so that it can run independently of the underlying computer (server, laptop, etc.).

This is a key concept for Cloud as it allows applications to run on different hardware and operating systems with minimal set up effort.

Docker is a platform to build and manage containers.

Docker and container features:

I'll come back to this in the section on running the BP mock server.

Data basics

The following data standards/formats are used in this exercise:

JSON (JavaScript Object Notation)

For example:

{
  "employee_id": "1234567",
  "employee_name": "Alexander"
}

XPATH

For example:

 //title[contains(text(), 'Programming')]

XML (eXtensible Markup Language)

For example:

 <book id="bk01">
      <author>Roan, Alexander</author>
      <title>Front end to S/4HANA</title>

HTML (HyperText Markup Language)

Terminal

I worked through this demo/test on Mac so I used Terminal, which is the Mac default command line interface (CLI).

The CLI is necessary for activities such as setting up and starting servers or working with docker containers.

Terminal basics

To run JavaScript servers, JavaScript runtime is required. It's easier to install and manage things like this using a package manager in Terminal. Homebrew is a popular package manager for Mac.

Homebrew

Java/JavaScript

To complete the demo/test a few different JavaScript things are needed.

Node.js

NPM

Java development kit (JDK)

API client (Bruno/Postman)

The CodeJam utilised Bruno for API testing.

For the CodeJam a folder of pre-configured settings for Bruno is provided. However I'd suggest to start experimenting without the pre-configuration to build a solid understanding of the basics.

I'll include more notes in later sections.

Building and testing an integration flow

Set up the S/4HANA business partner mock server

Start by setting up the S/4HANA business partner mock server

Run the server: option 1: use NPM

Node.js and the node package manager (NPM) can be used to run the server directly on a computer.

> bupa-mock-odata@1.0.0 start
> node server.js
Mock server started on port 3000 after 1 ms, running - stop with CTRL+C (or CMD+C)...

Terminal tells us which port the server is running on. Port "3000" is accesible in the browser or an API client via "http://localhost:3000".

To stop the server in terminal use ctrl+c.

For the curious, you can look at the files that make up the mock server in the above folder. Check out:

Theoretically you could use this Node.js server as a template to simulate other SAP Odata APIs with some adjustments to these files.

Run the server: option 2: use Docker

The mock server can also be run as a Docker container. This is a little more convenient as after the first run we can stop and start it from the Docker desktop app.

Note the server already has a Dockerfile, so it's already set up to run as a container.

If we run something inside a docker container we need to interact with it via ports on the container. The application is really running contained inside a container. When we run a docker container we provide a mapping between a local port on the computer and the container port. We can then access the docker application via this mapping.

To run as a Docker container:

Note if there wasn't already a dockerfile we would need to create one and build the app before running it.

A simple docker demo

This was my first time using docker, so I experimented by creating a simple "Hello, World!" style server from scratch. Here it is if you want to try:

{
  "name": "hello-docker",
  "version": "1.0.0",
  "main": "index.js",
  "scripts": {
    "start": "node index.js"
  }
}

FROM node:18

WORKDIR /usr/src/app

COPY package*.json ./
RUN npm install

COPY . .

CMD ["npm", "start"]

You can see Docker uses NPM, in the same way we would with a manual run, but it's installing and running NPM inside the container, not on the computer.

To build and run:

Testing with the web browser

The simplest way to test the API is running locally is to put the local address in the web browser.

The main domain should return the API details including the links such as:

"http://localhost:3000/sap/opu/odata/sap/API_BUSINESS_PARTNER" "http://localhost:3005/sap/opu/odata/sap/API_BUSINESS_PARTNER"

To access the service to return the general data of all business partners we add A_BusinessPartner

"http://localhost:3005/sap/opu/odata/sap/API_BUSINESS_PARTNER/A_BusinessPartner"

In the browser, this should return a JSON document containing the list of business partners.

We can pick a business partner number from the list and use it with the path to select a specific business partner:

"http://localhost:3005/sap/opu/odata/sap/API_BUSINESS_PARTNER/A_BusinessPartner('1003764')"

Testing with an API client (Bruno)

Rather than just using the web browser to check the API an API client can be used, this has a few benefits:

To test with Bruno:

Create a request for all business partners

Run a request

Create a request for a single business partner (1003765)

Note as the params are entered the URL dynamically updates.

Basics on OData API URLs

Keep in mind the S/4HANA mock business partner server only includes limited functionality. The above filters and selects won't work.

Java SDK for SAP Cloud Connector

The next step is to set up SAP Cloud Connector

Recall Cloud Connector will provide a secure tunnel allowing SAP Cloud to talk to the S/4HANA business partner mock server.

Cloud Connector requires a full Java Development Kit (JDK).

It's likely you may run into version, compatibility, authorisation issues. These are all very common and a web search should help.

Install Cloud Connect

Next install Cloud Connector.

Cloud connector is listed under the SAP development tools page under Cloud.

I received authorisation issues on the first attempt to run it:

Install and set up SAP Integration Suite

To continue from here SAP Integration has to be installed and active as per the earlier instructions.

Connect SAP Cloud Connector to SAP Integration Suite

As Cloud Connector bridges between SAP Cloud and the S/4HANA business partner mock server we need to set it up to connect to SAP Cloud. We get the security/authentication data to do this from our SAP BTP trial account.

Double check the settings in the subaccount overview:

Cloud Connector to Mock BP Server

There's no security on S/4HANA business partner mock server so it is simply a matter of adding the address.

Replace the internal port name with the one your mock server is running on locally. You are free to choose the virtual host and port.

It's critical to select "Non-SAP system" and HTTP, not HTTPS.

A new entry will appear under 'Mapping Virtual to Internal Systems'

At this stage https://localhost:3005 is now mapped to https://s4-mock:3005 in the SAP Cloud.

You can also check in integration suite to see if Cloud Connector is connected.

Errors at this stage are likely related to

Design integration flow

Create an integration flow

The integration flow screen is read-only by default, click edit.

Set up the sender

Define an 'address' for the SAP Integration Suite endpoint.

Add flow elements

The CodeJam has excellent instructions for walking through different flow steps as per their exercises.

I will summarise a few elements I used in my design.

Router

Router

The route path we are looking at in this example is the one that returns a single business partner with address data.

Content modifier - case 1

Case 1:

JSON to XML converter

{
  "employee_id": "1234567"
}

<root>
  <employee_id>1234567</employee_id>
</root>

Content modifier - case 2

Content modifier

Request Reply

Request reply let's us send a request to a server.

To check deployment status go to Monitor > Integration and APIs. On this page the endpoint to access the service is shown:

"https://{your trial}-cpitrial03-rt.cfapps.ap21.hana.ondemand.com/http/request-business-partners"

Test Cloud Integration with API client

At this point we can test consuming the API through SAP Integration Suite.

Unlike testing the local mock server, we need to deal with authentication and security. The way this works is:

Accessing security details

For local testing we can hardcode these values in our test tools, but be careful not to upload or share these anywhere.

In production, never hardcode secrets or tokens. Use environment variables or a secure credential store.

Request a token with Bruno

In Bruno create a new request:

Send the request. This should return a JSON document with a long value in "access_token". There should also be a expiry time e.g. 4199 seconds.

When sending a request, if the token is not valid Integration Suite will return a 401 error code. This means we need to request a new token.

Within Bruno we can save this token value to a variable. This saves us from copying and pasting it into other requests.

Navigate to 'scripts' under the TOKEN request. Under Post Request enter:

if (res.status == 200) {
  const token = res.body.access_token;
  bru.setEnvVar("access_token",token); 
}

Save and run the TOKEN request. Goto the environment and click 'configure'. You should see the access_token variable updated with the value from the response.

Test the API with a request with for a single BP

{
  "employee_id": "1003764"
}

Building and testing a frontend

At this point a request to SAP Integration Suite should be successfully routed and transformed to the S/4HANA business partner mock server.

The next part would be building and testing the web app. However, there is too much to cover in building and testing the frontend to cover in this post. I may produce a video on this if anyone is interested.

Share, comment/discuss

Share to: LinkedIn, X