In June 2020 we have launched a brand new documentation portal which consolidates all the knowledge, feature documentation, comprehensive guides, video tutorials, troubleshooting, release notes, API documentation and more. Please, use it as a single reference point about SAP Cloud SDK. From now on it's the most complete and up to date source of information about the product.
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.
The following steps will explain how to consume a business API from S/4HANA Cloud using the SAP Cloud SDK. If you want to follow this tutorial, we highy recommend checking out the previous parts of this series, especially the article about the Virtual Data Model for OData.
Note:
- This post is part of a series. For a complete overview visit the SAP Cloud SDK Overview.
- This tutorial requires access to an SAP ERP system.
Goal of this blog post
In this blog post we will develop an cloud app that consumes business partner data. We know the notion of business partner to be the central concept inside S/4HANA Cloud to represent customers, suppliers and other counterparties.
This app shall run in the SAP Cloud Platform and - to keep it simple in the beginning - display business partners in JSON format. Based on this data we could enhance our app later on with more functionalities,
Furthermore, we know that SAP publishes all APIs of S/4HANA Cloud on the
SAP API Business Hub where we can find a
suitable OData API to obtain business partner master data.
The remainder of this blog subsumes the following aspects:
- Discover the Business Partner API on the SAP API Business Hub
- Enable the Business Partner API within the S/4HANA Cloud system
- Make an example OData call to test the Business Partner API
- Develop our app to consume the Business Partner API using the SAP Cloud SDK
- Deploy and run our app on SAP Cloud Platform
Discover the Business Partner API on the SAP API Business Hub
When we access the
SAP API Business Hub and consider all APIs exposed in the context of
SAP S/4HANA Cloud, we can easily figure out which APIs are available to exchange data with S/4HANA Cloud.
The
OData Service for Business Partner enables you to create, read, update and delete business partners inside SAP S/4HANA Cloud.
The provided information tells us that the OData service is named API_BUSINESS_PARTNER and its current version 2 is available as of S/4HANA Cloud release 1708. This particular API is included in the communication scenario Business Partner, Customer and Supplier Integration (SAP_COM_0008).
Hint:
To learn more about Communication Scenarios and Arrangements, check out the respective deep dive.
We know that the OData protocol uses the notion of entity sets to distinguish different kinds of data, such as Customer, Supplier, and Business Partner. As our app should display business partners in the first shot, we are interested in the entity set that provides business partners stored inside S/4HANA Cloud. Investigating the entity sets of the service API_BUSINESS_PARTNER (check out section
RESOURCE), we can find the entity set named A_BusinessPartner.
Other entity sets exist for retrieving Customer or Supplier information which we will not touch upon in this blog post.
Enable the Business Partner API within the S/4HANA Cloud system
Why do we need to enable the API?
Before we can access this business partner API within the S/4HANA Cloud system, we need to enable it. By default, this API is not exposed and accessing it returns an HTTP response code 403 (Forbidden). We can enable this API by creating and activating a Communication Arrangement for its Communication Scenario within our S/4HANA Cloud system.
This business partner API is included in the communication scenario named Business Partner, Customer and Supplier Integration which has the identifier SAP_COM_0008.
How do we enable the API?
Create Communication System and Communication User
To create the Communication Arrangement, log on to the S/4HANA Cloud Fiori launchpad.
From there, find the Fiori tile
Communication Systems and open it.
Clicking
New we can create a new communication system for our purpose.
For now, we will consume the API from an app that runs on the local machine. That is why we name this communication system like this, e.g. MARCOS_LOCAL_MACHINE. Of course, you have to specify a meaningful name that represents your purpose.
After we clicked
Create, we see the Fiori interface that allows to enter the details of the new communication system.
Specify the host name as
localhost. When we later on run our app in the SAP Cloud Platform we will put the URL of our SAP Cloud Platform account here. Especially in productive scenarios you must not enter
localhost here.
We also enter
LOCALHOST as logical system (field named
Protokollsystem-ID here in this screenshot).
Additionally, we need an inbound user that we will use to authenticate to our S/4HANA Cloud system. This tutorial focuses on basic authentication (i.e. with user name and password). We will examine more sophisticated authentication flows in future blog posts.
You will see a plus symbol right to the headline
User for Inbound Communication that opens a screen to create a new inbound user. Here we click on
New User.
In the upcoming screen we enter the user name and an approriate description along with a secure password.
Hint:
The user you are creating is authorized to invoke all APIs within the communication scenario. Therefore, make sure that you choose a secure password that you handle carefully and secretly.
When clicking
Create the previous screen shows the user name we chose before. As we stick to basic authentication in this blog post, we can leave the authentication method as
User Name and Password.
We confirm this popup by clicking
OK.
We know that the communication scenario SAP_COM_0008 allows bidirectional communication. We will not make use of this feature in this blog post, however we cannot create the communication arrangement later on if we omit an outbound user here. Therefore, we create an outbound user following the same steps as for the inbound user. The only difference is that we choose the plus symbol right to the headline
User for Outbound Communication. You are done when your communication system shows two users, one for inbound and one for outbound communication.
Create Communication Arrangement
In the previous step we created a new communication system named e.g. MARCOS_LOCAL_MACHINE that has one inbound user (we neglect the outbound user in the remainder of this blog).
Going ahead we create a communication arrangement based on communication scenario SAP_COM_0008.
From the Fiori launchpad, we open the app
Communication Arrangements.
This app shows all communication arrangements already created in the S/4HANA Cloud system. We click on
New to create a new one.
This communication arrangement is named e.g. MARCOS_BUSINESS_PARTNER_API_APP and is based on scenario SAP_COM_0008. You are free to choose an arbitrary name for your communication arrangement. Of course, you have to give a meaningful name that explains your background. This is especially important in productive landscapes.
After clicking
Create we see the screen that asks for further input regarding the new communication arrangement. Here we choose the communication system we just created and additionally we select the inbound user.
When scrolling further down we can see that there are multiple outbound services, such as that S/4HANA Cloud can replicate data to other external systems. For our purpose we are not interested in this functionality. Therefore, let us turn off all these services by deactivating the respective checkbox.
After deactivating all outbound services and clicking
Save, S/4HANA Cloud tells us that it successfully activated this communication arrangement.
Summary
Let us recap what we have done so far:
- We found and examined the business partner API in the SAP API Business Hub.
- We identified the entity set we want to consume.
- We created a communication arrangement in the S/4HANA Cloud system.
In the subsequent step we are going to consume the business partner API from the local machine via Postman.
Make an example OData call to test the Business Partner API
We want to check out the business partner API in our S/4HANA Cloud system from the local machine. For this purpose this blog makes use of Postman. Postman is a simple and prominent HTTP client being available as extension to Google Chrome. You may use any other HTTP client you are familiar with.
We launch Postman and enter the target URL of the business partner API. Let us check out the metadata of our API at first.
As we are using basic authentication we enter the user name and password of the inbound user we created previously.
We click
Update Request in Postman to make sure that the credentials are really put in the request header.
When clicking
Send Postman sends an OData request (in fact, an HTTP request that follows the OData protocol) to the S/4HANA Cloud system and requests the metadata of the business partner API.
We can see the HTTP response code 200 which means OK.
The response payload is XML and contains all entity types.
Besides the metadata we can also check the real data, such as the retrieving business partner information. For this purpose we adjust the relative path of the URL.
Executing this request returns details about the first hundred business partners in our S/4HANA Cloud system serialized as JSON.
In the next step we are going to develop an app that executes the same OData call and displays the result.
Develop the app to consume the Business Partner API using the SAP Cloud SDK
Generate project skeleton
In the previous step we demonstrated that the business partner API is accessible. Going ahead we will develop an app that invokes this API and displays the first hundred business partners of the S/4HANA Cloud system in a simple HTML page.
The SAP Cloud SDK provides predefined maven archetypes. For this example we choose the Cloud Foundry environment on SAP Cloud Platform. We create a new directory on our file system and generate a project skeleton using the maven archetype mentioned in the blog post about
Hello World on Cloud Foundry. For this purpose you can execute the following on the command line:
mvn archetype:generate -DarchetypeGroupId=com.sap.cloud.s4hana.archetypes -DarchetypeArtifactId=scp-cf-tomee -DarchetypeVersion=LATEST
After following the instructions on the command line you receive a project skeleton which you can import into your IDE.
As you can read in the blog post about
Hello World on Cloud Foundry, the app resides in the
application folder. The
HelloWorldServlet is a simple servlet that listens to GET requests on the relative path
"/hello". In the following we are going to develop the OData call to our business partner API in the method
doGet.
We name our app
businesspartnerretrieval in the remainder of this blog post.
The SAP Cloud SDK provides a nice and simple virtual data model that eases the access to all OData services published on the
SAP API Business Hub. We have another
blog post that presents the advantages of our virtual data model.
Implement the OData call
Implementation
Let us continue with the method
doGet inside the
HelloWorldServlet which will contain the logic where we program the OData call. Let us firstly consider the entire code. Then we will examine it piece by piece.
@Override
protected void doGet( final HttpServletRequest request, final HttpServletResponse response )
throws ServletException, IOException
{
final PrintWriter writer = response.getWriter();
try {
final List<BusinessPartner> businessPartnerList = new DefaultBusinessPartnerService().getAllBusinessPartner().top(100).execute();
writer.write(new Gson().toJson(businessPartnerList));
response.setContentType("application/json");
} catch (Exception e) {
writer.write("Error: " + e.getMessage());
e.printStackTrace(writer);
}
}
Since this is a Java servlet, we can write output to the HTTP response which we access by its PrintWriter instance. Inside the try block we create a new
ErpConfigContext which points to the client 100 of the S/4HANA Cloud. As we use the SAP Cloud SDK, we can directly use the class
BusinessPartnerService which provides a method
getAllBusinessPartner. On its return type you call
top to restrict the output to hundred entries. Finally, the OData gets executed considering the
ErpConfigContext you created beforehand. As a result you retrieve a list having the row type
BusinessPartner. We use the GSON library to serialize this list as JSON and write it to the output.
Testing
In the class
HelloWorldServiceTest we adjust the integration test method as follows.
@Before
public void before()
{
RestAssured.baseURI = baseUrl.toExternalForm();
mockUtil.mockErpDestination();
}
@Test
public void testService() {
Response response = given().get("hello");
String body = response.body().asString();
assertThat(!body.isEmpty());
assertThat(response.getContentType().equals("application/json"));
}
Since we execute the test locally, we have to mock the resolution of the ERP destination. For this purpose, we call the method
mockErpDestination in the
before method.
In this test assertion we assure that the response body is not empty and its content type is application/json.
To make the above test work, we need to specify which S/4HANA system the app should talk to during the test runs. For this purpose we have to add two additional files under
integration-test/src/test/resources:
- credentials.yml
- systems.yml
The file
systems.yml describes which ERP system the app should talk to. In our example it looks as follows:
---
erp:
default: "XXX_100"
systems:
- alias: "XXX_100"
sapClient: "100"
uri: "https://mys4hanasystem.com"
XXX represents the three-letter acronym of the S/4HANA Cloud system. The URI must be adapted to the concrete URL of the S/4HANA Cloud target system.
The file
credentials.yml contains the credentials for the target S/4HANA Cloud system.
---
credentials:
- alias: "XXX_100"
username: "COMM_USER_BUSINESS_PARTNER_API"
password: "put_your_password_here"
Execute the respective maven command to execute the test.
mvn clean install
Check out this
blog article for more information about testing the functionality of your cloud app.
Deploy your app to Cloud Foundry
Execute this on the command line.
mvn clean install
cf push
Specify destination to S/4HANA Cloud system
SAP Cloud Platform uses destinations to allow the developer to specify the target URL and authentication information regarding external systems. In the Cloud Foundry environment on SAP Cloud Platform we specify destinations as environment variables.
You can set the environment variable on the command line as follows.
cf set-env businesspartnerretrieval destinations "[{name: \"ErpQueryEndpoint\", url: \"https://mys4hanasystem.com\", username: \"COMM_USER_BUSINESS_PARTNER_API\", password: \"put_your_password_here\"}]"
The parameters of this destination are as follows:
- name: This is the destination default name. Leave it unchanged.
- url: This URL points to your S/4HANA Cloud system. Do not specify any relative path. Just the protocol, the host name and the port (if applicable)
- username: This is the user name of the inbound user we created before.
- password: This is the password of the inbound user we created before.
Note that you have to escape the quotes surrounding the parameter values.
In order to update your app with that new environment variable, execute this command.
cf restart businesspartnerretrieval
Launch your app
Navigate to the URL of your app on Cloud Foundry, add the relative path
/hello and you will see a list of business partner names.
Conclusion
In this blog post we covered the end-to-end process from finding and examining a business API of S/4HANA Cloud in the SAP API Business Hub till the deployment and launch of an app in SAP Cloud Platform. During this we touched on enabling the business API by creating a communication arrangement in S/4HANA Cloud. The sample app we present here uses the
Virtual Data Model of the SAP Cloud SDK.
Stay tuned for upcoming blog posts about the SAP Cloud SDK.