Disclaimer: This blog post is only applicable for the SAP Cloud SDK version of at most 2.19.2. We plan to continuously migrate these blog posts into our List of Tutorials. Feel free to check out our updated Tutorials on the SAP Cloud SDK.
In this blog post, we discuss how to set up a connection to SAP S/4HANA from your cloud application running on SAP Cloud Platform, Cloud Foundry.
Good news: your application source code is really simplified, when you use the SAP Cloud SDK components, which take care of a lot of technical details for setting up a connection for you. Due to several abstractions, it does not matter whether your S/4HANA runs on-premise or in the cloud - a single version of the source code works in both cases.
In case you have questions or suggestions, reach out to us on Stackoverflow with the sap-cloud-sdk tag. Our development team is actively monitoring this tag and is making sure that the questions and requests are addressed properly. You can use this opportunity to share your experiences and to get advice from a broader Stackoverflow community. Of course, we are happy to receive your questions and suggestions in the comments to our blog posts, as well.
Goal of This Blog Post
This blog post guides you through setting up a connection from your application, developed with the SAP Cloud SDK and running on SAP Cloud Platform, Cloud Foundry, to SAP S/4HANA systems. Although this blog post mainly focuses on the S/4HANA On-Premise connectivity, we also discuss how you can customize your application to access SAP S/4HANA Cloud.
You will see how the SDK abstracts SAP S/4HANA Editions and enables the communication with various S/4HANA editions using the same lines of code. This allows developers to focus on the business logic of their applications, rather than taking care of the infrastructure-related general problems.
In this blog post, I reference related Cloud Platform services, such as authorization & trust management, the connectivity service, and the destination service. For more information on these topics, please, consult the official SAP documentation. I also give references to related resources in the part Further Information and Related Reading.
For simplicity of the account setup, I cover only the basic authentication between a cloud platform application and SAP S/4HANA. In productive solutions, you would use principle propagation instead. However, this will affect only the configuration part, as the authentication approach is abstracted by the SDK.
To demonstrate the connectivity, we will retrieve data from S/4HANA using OData services. Therefore, it is recommended to work through the following tutorial steps of our series to be able to experiment with S/4HANA On-Premise connectivity, as described in the sections below.
As On-Premise connectivity from SAP Cloud Platform, Cloud Foundry is supported starting from the SDK version 1.7.1, please, make sure that you use this or later version, when executing these steps.
Make sure that you have access to On-Premise SAP S/4HANA. You may also check that business partner service is activated in your system using the transaction code SICF.
Beware that the destination service is currently Beta in SAP Cloud Platform, Cloud Foundry. Therefore, it is available only in a Trial landscape.
Quick Look at the S/4HANA Query with the SDK Virtual Data Model
After executing Step 3, 4, and 7 of SDK tutorials, you have created two projects: business partner application accessing OData service and approuter that secures your application.
Now, let us consider business partner query in BusinessPartnerServlet that we have created in the first application and that is explained in details in the Step 4 of our tutorial series:
final List<BusinessPartner> businessPartners =
The execute() method is exactly the method that hides details related to connectivity to SAP S/4HANA from the application developer.
It is does not matter whether you are talking to S/4HANA Cloud or S/4HANA On-Premise edition. You can still use exactly the same query and the SDK will handle all the connectivity magic for you behind the scenes.
This enables separation of concerns: developers write source code and cloud platform account administrators take care of the customizing of corresponding S/4HANA instances.
Running Business Partner Calls Against S/4HANA On-Premise
Now, let us see, what customizing is required to run the application against SAP S/4HANA On-Premise.
Set up Connectivity in Cloud Platform Account and Cloud Connector
1) You will create a connection from your cloud connector instance to your Cloud Foundry account, where you deploy business partner application. Here is the example of my configuration:
2) You will enable cloud to on-premise access for the given account to your on-premise system. Here is the example of my configuration:
Beware that the virtual host that you configure in the Cloud Connector will be referenced in the destination configuration, as shown below.
Step 2. Create service instances in Cloud Foundry Account
To be able to connect SAP S/4HANA On-Premise edition, you need to create an instance of the connectivity service that we will later bind to our business partner java application.
To create your instance of the connectivity service, you can use Cloud Foundry CLI and execute the command:
cf create-service connectivity lite my-connectivity
If you have executed the tutorial steps, mentioned in the prerequisites to this deep dive, you have already created the following service instances:
Instance my-xsuaa of the service Authorization & Trust Management
Instance my-destination of the destination service
You can check your service instances in your Cloud Foundry cockpit, as shown in the screenshot below:
Step 3. Configure S/4HANA destination
Destinations can be configured via Cloud Foundry cockpit. Configuration of destinations can be done in a subaccount level, when you select the menu Connectivity -> Destinations (Beta).
In the Business Partner query in our application, we use the method execute(), which runs the query against the destination with the default name ERPQueryEndpoint.
The screenshoot below demonstrates my configuration that corresponds to the previously described configuration of the Cloud Connector and default destination name. Please note that to connect to SAP S/4HANA On-Premise, you need to set the Proxy Type to "OnPremise":
This default destination name is defined by the SDK. You can use another name, however, as it is demonstrated in our GitHub example S4-Connectivity. It can be useful in case you have several destinations. You can then explicitly reference the destination by name when creating ErpConfigContext, as follows (for example, for the endpoint with the name "S4HANA"):
Bind Cloud Platform Services in manifest.yml of Your Business Partner Application
After the service instances are created and customized, we will need to bind them to our application.
Modify already existing manifest.yml file in your business partner application by adding a binding to the new connectivity service instance. manifest.yml looks as follows in my case:
Now, you can redeploy your business partner application in SAP Cloud Platform, Cloud Foundry and call the endpoint /businesspartners of your approuter to get a response from your On-Premise SAP S/4HANA system, as depicted below.
Let us take a look at the concepts of the inner working of the On-Premise connectivity and the SDK role in this scenario.
S/4HANA On-Premise Connectivity with the SDK: Under the Hood
What is actually going on behind the scenes, when you call the execute() method of the business partner query? Actually, several steps are executed that you even do not have to be aware of, as the SDK takes care of them for you.
When using the SDK, the steps, such as retrieving a Json Web Tocken (JWT) to connect to the destination service, retrieving a configuration of the destination, obtaining a JWT for accessing the connectivity service, sending a request to the connectivity instance are handled by the SDK.
Looking at the high level architecture depicted in the referenced blog post, the steps 4a, 4b, 5, and 6 are performed when you are calling the execute() method of your business partner query.
Abstracting SAP S/4HANA Edition with the SDK: S/4HANA Cloud Connectivity
So far, we have looked at what needs to be done to set up SAP S/4HANA On-Premise connectivity from your application running in SAP Cloud Platform, Cloud Foundry.
One of the nice features of the SAP Cloud SDK is the abstraction of S/4HANA editions. What does it mean from the development perspective? You can write your code for S/4HANA On-Premise and you can be sure that you will be able to run your application against S/4HANA Cloud edition without any changes in code. You just need to adapt the configuration of the S/4HANA endpoint.
Let us see that in action.
Set up Cloud Platform
All you need to do to read data from SAP S/4HANA Cloud is to adapt the default destination, changing it to the corresponding S/4HANA Cloud instance. This is how the destination for the Cloud system would look like:
Note: For S/4HANA Cloud communication, you can remove the binding of your application to the instance of the connectivity service in manifest.yml. It is only required in case of On-Premise connectivity.
Deploy and Test
Now, you can redeploy your business partner application in SAP Cloud Platform, Cloud Foundry and call the endpoint /businesspartners of approuter to get a response from SAP S/4HANA Cloud system, as depicted below.
We have just switched the S/4HANA edition that our application is talking to without changing a single line of code. As a developer, I like that! 🙂
Further Information and Related Reading
First of all, I recommend you to check out S4-Connectivity example on GitHub that demonstrates the usage of the same code line for various S/4HANA editions. Beware that you will need to configure two destinations in your account to run this example: ErpQueryEndpointCloud (S/4HANA Cloud endpoint)and ErpQueryEndpointOP (S/4HANA On-Premise). Also, do not forget to secure your application with an approuter before testing it.
In addition to that, here are some link to the related official SAP documentation, in case you are interested to research on this topic more and to get insight on the corresponding Cloud Foundry services: