Part 6: Simplify Integration of data from SAP S/4HANA Cloud to third-party applications

[divyamary]

SAP Cloud Platform Open Connectors simplifies and accelerates connectivity to third-party cloud applications. It provides robust, feature rich, pre-built connectors to an extensible library of over 160 of the most popular third-party cloud applications. SAP Cloud Platform Integration (Cloud Integration) supports end-to-end process integration across cloud-based and on-premise applications (cloud-cloud and cloud-on-premise integration) making cloud integration simple and reliable.

With SAP Cloud Platform Integration and Open Connectors, customers can drive innovation faster by painlessly integrating cloud and on-premises applications, whether from SAP or from third parties, using open standards-based Web services. In this blog, we would showcase a simplified integration of replicating billing and invoice documents from SAP S/4HANA Cloud to third-party file storage using SAP Cloud Platform Open Connectors and SAP Cloud Platform Integration.

Many a times, the billing documents like invoices or sales orders which is available as a PDF document needs to be copied to a file based shared location so that it can be made accessible to broader recipients within an organization. Using the OData APIs available in SAP S/4HANA Cloud, integrations patterns provided by SAP Cloud Platform Integrations and simplified connectivity to third-party document storage APIs provided by SAP Cloud Platform Open Connectors, such an integration can be very easily achieved.

For more blogs on SAP Cloud Platform Open Connectors , ref the blog series.

Prerequisites

• SAP Cloud Platform trial tenant


• SAP S/4HANA Cloud tenant


• SAP Cloud Platform Integration tenant 


• SAP Cloud Platform Open Connectors tenant


• Test or Sandbox tenant in Dropbox or any other third-party storage application that you would like to connect to from SAP Cloud Platform Open Connectors.

Discover, Explore and Consume SAP S/4HANA Cloud APIs

SAP API Business Hub is the central catalog of all SAP and partner APIs for developers to build sample apps, extensions and open integrations with SAP.  In this blog, we have used the Billing Document - Read, Cancel, GetPDF from SAP S/4HANA Cloud APIs.

• To Discover, Explore SAP S/4HANA Cloud APIs navigate to SAP API Business Hub(https.api.sap.com)


• Select the SAP S/4HANA Cloud APIs and search for GetPDF

 

 

• For this integration, service operation named GetPDF would be used. This API returns the document information in a PDF format. The document identifier needs to be passed as query parameter named BillingDoument in the format BillingDocument='document_id'.  To get all the billing document identifiers, A_BillingDocument resource can be called.

 

• For configuration on the SAP S/4HANA Cloud tenant, information about the communication scenarios and scope items is required. This information is available in the Details tab.

 

Configurations on SAP S/4HANA Cloud System

In this section, steps for creation of the communication system and user for Billing Document - Read, Cancel, GetPDF APIs is covered. The concept of SAP S/4HANA Communication, Integration and Authorization artifacts is explained in detailed in this blog.

Note:- The user should have the role Communication Management and Extensibility for this configuration.  This role can be assigned via Manage Business User Fiori application.

• Open SAP S/4HANA Cloud and then navigate to Communication Management tab.


• Create Communication user, Communication systems as described in this blog


• Create a Communication Arrangements for the Billing integration ( SAP_COM_0120). Details of creating a Communication Arrangement is available in this blog.

• This would create the Communication Arrangements required to access the Billing documents API and all the APIs which are part of the communication scenario SAP_COM_0120. Details of this is available in the Best Practices explorer.

 

Connect to Third-party application from SAP Cloud Platform Open Connectors

In this section, steps to seamlessly and securely connect to the third-party cloud applications via SAP Cloud Platform Open Connectors has been covered. SAP Cloud Platform Open Connectors is available for test, explore and try out in SAP Cloud Platform trial. If you have not enabled SAP Cloud Platform Open Connectors in your trial tenant, refer this blog to enable it.

Note:- In this blog, we have used a third-party application from the Document hubs which is Dropbox. You are free to use any other third-party application of your choice for this excercise

In the blog Simplified connectivity to third-party document storage applications, detailed steps to connect to Dropbox connectors has been covered.

• Logon to your SAP Cloud Platform trial and Navigate to the Neo Environment.

 

• From the services tab, search and select Open Connectors tile and click on the Go to Service link.

 

• You would be navigated to SAP Cloud Platform Open Connectors Home or Landing page.


• Navigate to the Connectors page and then search for the Dropbox connector. You can also explore and try out third-party connectors of your choice from the available connectors catalog.

 

• Hover over the Dropbox connector and select the option Authenticate to connect to your own Dropbox tenant.


• In the Create Authenticated Connector page, enter a name for your authenticated connector say mydropbox and click on the Create Instance button.


• On click on the Create Instance button, you would be automatically navigated to the OAuth based login page from Dropbox, where you would have to enter your Dropbox user details and credentials.

Note:- Based on your selected third-party application connector, the configuration options in this screen may vary.

• After the authenticated connection to your third-party application has been created successfully you would be able to test out the connection from SAP Cloud Platform Open Connectors. To try out the RESTFul APIs for the specific third-party application, click on the option Test in the API Docs.

 

• This would launch the integrated OpenAPI specification based API Documentation for your third-party applications so that you can test and try out the connectors from SAP Cloud Platform Open Connectors.


• Select any of the available Resources say files and click on Try it Out to test the connectivity to third-party applications and then click on the Execute Button


• This would show the CURL command with the harmonized RESTFul URIs to your third-party application and the normalized authentication token which can be used to securely and seamless connect to your third-party application.

 

The harmonized URIs from the CURL command and authorization token header value would have be noted down or copied as it needs to be provided in the SAP Cloud Platform Integration flow to securely connect to third-party applications via SAP Cloud Platform Open Connectors.

Creating a “Replicate Billing document” REST service in SAP Cloud Platform Integration

SAP Cloud Platform Integration makes cloud integration simple and reliable. Hence it is SAP’s strategic integration platform for SAP Cloud customers. It provides out-of-the-box connectivity across cloud and on-premise solutions. Using the rich integration patterns and features provided by SAP Cloud Platform Integration we can very easily model the business process of replication an billing document from SAP S/4HANA Cloud to third-party document storage application.

In this section, steps to create a simple REST services for replication of billing document has been captured. At a high level, this new REST API would perform the following integration steps :-

1. Read the Billing document Id provided by the user.


2. Call the SAP S/4HANA Cloud OData APIs to read the Billing document in PDF format.


3. Convert the response from SAP S/4HANA Cloud OData API into File format required by third-party document storage application.


4. Call the third-party document storage application using the simplified and harmonized third-party connectors from SAP Cloud Platform Open Connectors.

In this blog, the HTTPS sender adapter in SAP Cloud Integration has been used which allows you to accept incoming HTTP request on a specific address.

For more details on SAP Cloud Platform Integration refer Blogs.

Create Secure Credentials to connect to SAP S/4HANA Cloud OData APIs

To securely connect to the SAP S/4HANA Cloud OData APIs, a secure credentials to your Communication user created in the section Configurations on SAP S/4HANA Cloud System would be required. Creating secure credentials also enables the credentials to be re-used across multiple integration flows. In this section, steps to create a secure credentials to SAP S/4HANA Cloud system is captured.

• Logon to your SAP Cloud Platform Integration web application.


• Click on Monitor tab and then select Security Material to create a secure credentials to be used for SAP S/4HANA Cloud system.

• Click on the Add button and select User Credentials to create a new secure credentials

 

• Enter the name of User Credentials say S4Cred, the details of the SAP S/4HANA Cloud communication user and credentials created in the section Configurations on SAP S/4HANA Cloud System. This communication user allows you to securely connect to the Billing integration OData APIs from the integration flows. Select Deploy to persist the changes.

• The name of the User credentials would have to be noted down as it would have to be specified in the integration flow to securely connect to the Billing integration OData APIs to read the billing related PDF files.

Create Integration Package and Process Flows

In this section steps to create the integration package and process flows has been captured.

• Navigate to Design tab, click Create to create an integration package.

 

• Enter integration package details like name,  technical name, description as provided in the table below and click Save.

Name	S4HANACloudToThirdPartyStorage
Technical Name	S4HANACloudToThirdPartyStorage
Short Description	Simplified integration to publish billing documents (PDF) from SAP S/4HANA Cloud to Third-Party Storage

 

 

• Navigate to Artifacts tab, Select Integration Flow from Add action to add in a new Integration flow.

 

• In the Add integration flow artifact dialog enter integration flow name and click OK.

Name	PublishBillingDocToThirdPartyFileStorage
Description	Publishing billing document to third-party file storage

 

• Select the newly created Integration Flow named PublishBillingDocToThirdPartyFileStorage and then click on the Edit button to start editing the integration flow.

 

• From the Sender box drag the connecting arrow to connect to Start action.


• From Adapter type dialog select HTTPS.

• In Connection tab, enter the Address or URL details ( say /publish/documents/*  ) . Specifying wild chars like * would enable us to listen to the path parameters passed by the customer. This query parameter can be the billing document identifier which needs to be replicated from SAP S/4HANA Cloud system to third-party applications.

 

• To read the path parameters, a Content Modifier can be used. The path parameters passed by the end user can be read from the CamelHttpPath header value and this can be assigned to a flow variables named doc_id.

 

• Select the Exchange Property tab, click on the Add button. From the action drop down select Create, enter doc_id as the Name of the property, select Header from the drop down for Type and enter CamelHttpPath in the value field.


• To improve the readability, under the General tab, name of the Content Modifier step can be specified as Read Path

• The document identifier passed by the end user is no longer required in the integration flow and therefore it can be removed from the process flow using a Content Modifier step.

• To remove the CamelHttpPath header, select the Message Header tab and Click on Add button.


• From the Action select Delete, Click on the Select button for the Name and then Specify the header name as CamelHttpPath and select the Data Type as Constant.


• To improve readability, under the General tab , name of the Content Modifier can be set as Remove Path.

• To read the billing document in PDF format, the Request Reply integration pattern with an HTTP Receiver adapter can be used.

• To improve readability, the name of the Request Reply step can be set to Call S/4HANA Cloud in the General tab.

 

• To invoke SAP S/4HANA Cloud OData API, add in a Receiver.


• To improve readability, name of the Receiver can be set to SAPS4HANACloud

• Select and connect the Request Reply step to the newly added Receiver. This would open up the Adapter list, from the available Adapter select HTTPS.


• Under the Connection tab, enter the details about the SAP S/4HANA Cloud Billing Document Get PDF service operation as detailed in the section Discover, Explore and Consume SAP S/4HANA Cloud APIs. 


• To dynamically pass in the document identifier, the doc_id property which was read in the Read Path content modifier steps can be used.


• To securely pass in the credentials, the User credentials named S4Cred created in the section Create Secure Credentials to connect to SAP S/4HANA Cloud OData APIs can be used

 

1	Address	https://{your_s4_hana_cloud_tenant_host}/sap/opu/odata/sap/API_BILLING_DOCUMENT_SRV/GetPDF
2	Query	BillingDocument='${property.doc_id}'
3	Proxy Type	Internet
4	Method	GET
5	Authentication	Basic
6	Credential Name	S4Cred

 



 

• GetPDF service operation of the SAP S/4HANA Cloud OData API, returns the PDF document in the base64 encoded format. Response data returned iss shown in the screenshot.

• To read this file content, Filter steps with XPath expression can be used.

 

• To improve readability, the name of the Filter step can be set to Read Billing Document Data in the General tab.


• Under the Processing tab, XPath Expression can be set to d:GetPDF/d:BillingDocumentBinary/text() and Value type set to the String field

 

• Since the XPath Expression uses XML namespaces, this namespace needs to be defined or declared at the Integration flow.


• To declare the namespace, click anywhere within your integration flow and then select Runtime Configuration tab. Declare the Namespace mapping as xmlns:d=http://schemas.microsoft.com/ado/2007/08/dataservices & Allowed HTTP headers as Content-Type.


• The allowed HTTP headers needs to be specified so that required HTTP header set in the subsequent steps can be passed to the target Receiver.

 

• The third-party document storage application requires the file content to be passed in the Multi Part Form request. In order to create the required multi part form request and also to set the required header for the third-party document storage integration with SAP Cloud Platform Open Connectors, a Groovy Script can be used.

 



 

• To improve readability, the name of the Groovy Script step can be set to Convert to File structure in the General tab.


• Click on the + button in the newly added Groovy script step to create a new script file.

 

• The generated script is modified to set message authorization header to normalized authorization to the third-party document storage application like Dropbase. Steps to get the normalized authorization token is described in details in this blog.


• Copy paste the below snippet to the created script page and replace the authorization header value your_third_party_authorization_token_from_sap_cloud_platform_open_connectors to your normalized authorization token from SAP Cloud Platform Open Connectors.

/*

The integration developer needs to create the method processData 

This method takes Message object of package com.sap.gateway.ip.core.customdev.util 

which includes helper methods useful for the content developer:

The methods available are:

public java.lang.Object getBody()

public void setBody(java.lang.Object exchangeBody)

public java.util.Map<java.lang.String,java.lang.Object> getHeaders()

public void setHeaders(java.util.Map<java.lang.String,java.lang.Object> exchangeHeaders)

public void setHeader(java.lang.String name, java.lang.Object value)

public java.util.Map<java.lang.String,java.lang.Object> getProperties()

public void setProperties(java.util.Map<java.lang.String,java.lang.Object> exchangeProperties) 

public void setProperty(java.lang.String name, java.lang.Object value)

*/

import com.sap.gateway.ip.core.customdev.util.Message;

import java.util.HashMap;



def Message setHeader(Message message, String id) {



message.setHeader("authorization", "your_third_party_authorization_token_from_sap_cloud_platform_open_connectors");

message.setHeader("content-type","multipart/form-data; boundary=--------------------------" + id);



return message;



}



def ByteArrayOutputStream getMultiPartBody(payload, filename, id) {



String charset = "US-ASCII";

def LINEFEED = "\r\n";



def output = new ByteArrayOutputStream();

output.write(("----------------------------"+ id).getBytes(charset));

output.write(LINEFEED.getBytes(charset));

output.write(("Content-Disposition: form-data; name=\""+filename+"\"; filename=\""+filename+"\"").getBytes(charset));

output.write(LINEFEED.getBytes(charset));



output.write("Content-Type: application/pdf".getBytes(charset));

output.write(LINEFEED.getBytes(charset));

output.write(LINEFEED.getBytes(charset));



output.write( payload.decodeBase64());

output.write(LINEFEED.getBytes(charset));



output.write(("----------------------------"+ id + "--").getBytes(charset));

output.write(LINEFEED.getBytes(charset));

return output;



}





def Message processData(Message message) {



String charset = "US-ASCII";

def id = "238360769909770904663504";



def map = message.getProperties();

def filename = "billing_" + map.get("doc_id") + ".pdf";



def ByteArrayOutputStream output = getMultiPartBody(message.getBody(String.class),filename,id);

message = setHeader(message, id);

message.setBody(output.toByteArray());



return message;

}

• Click on the Ok button to persist the script changes

 

• Finally to invoke the SAP Cloud Platform Open Connectors harmonized APIs, connect the end message to your Receiver and then from the drop down select HTTPS adatper.


• Under the Connection tab, enter the details about the harmonized URIs to third-party document storage files API from SAP Cloud Platform Open Connectors. 


• The query field would have to adjusted based on your third-party application folder structure, for this integration, in the Dropbox tenant we had the folder named demo pre-created and each billing document was stored using the doc_id appended to the filename in the format billing_{document_id}.pdf

1	Address	https://api.openconnectors.ext.hanatrial.ondemand.com/elements/api-v2/files
2	Query (Note this field would have to be adjusted based on your Dropbox folder path. For our integration we had a folder named demo created in the Dropbox tenant	path=/demo/billing_${property.doc_id}.pdf
3	Proxy Type	Internet
4	Method	POST
5	Authentication	None

 



 

• With this we have successfully created an integration flow that queries for the billing document from the SAP S/4HANA Cloud system and then using SAP Cloud Platform Open Connectors saves the document into a third-party document storage. The full integration flow screenshot is provided below.


• Click on the Save and then Deploy button to deploy this integration flow to SAP Cloud Platform Integration tenant. Note, for the first time deployment it might take some time before the changes are fully deployed. The status of the deployed application can be checked using the Monitor tab.

 

 

Testing the Integration Flow

• The newly created integration flow can be invoked by using https://{your_sap_cloud_integration_iflow_map}/http/publish/documents/{your_s4_hana_cloud_document_i... from any Browser or test console application like Postman.


• You would be prompted for user credentials, when prompted enter the user credentials which has the the role ESBMessaging.send on the SAP Cloud Platform Integration tenant.


• This integration flow might take some time to complete the processing of fetching the billing document from your SAP S/4HANA Cloud tenant and then saving it to your third-party document storage application.


• Once completed you would see the success full response in the Browser.

 

 

 

• You can also navigate to your third-party document storage application and then view the replicated billing document under appropriate folder ( in this blog, we had used the folder named demo)

 



 

More blogs on SAP Cloud Platform Open Connectors available in SAP Community.