Part 3: Posting Documents to SharePoint :Create Post File to SharePoint Integration Flow

[divyamary]

Many a times, the billing documents like invoices or sales orders which is available as a PDF document needs to be copied to SharePoint team site 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 Cloud Integration capability and simplified connectivity to SharePoint provided by Open Connectors of SAP Cloud Platform Integration Suite, such a business scenario can be very easily achieved.

In the blog series, posting of the billing documents from SAP S/4HANA Cloud to SharePoint is covered end-to-end and in this blog, configurations around creating an integration flow to post billing documents from SAP S/4HANA Cloud to SharePoint is covered in details.

Prerequisites

• SAP Cloud Platform ( Trial Environment)


• SAP Cloud Platform Integration Suite (Trial Environment)

Discover and Explore 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, Billing Document – Read, Cancel, GetPDF from SAP S/4HANA Cloud APIs has been used.

• To Discover, Explore SAP S/4HANA Cloud APIs navigate to SAP API Business Hub


• 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.


• Select /GetPDF resource and select Try out

• Enter '90000000' in BillingDocument field and select Execute.

• To consume this SAP S/4HANA Cloud API Sandbox from API Business Hub in Cloud Integration an API Key is required. Select Show API Key to get your own API Key.

• Select Copy Key and Close to copy this API Key. This API Key will be used from Cloud Integration to get the billing document.

Create Post File to SharePoint Integration Flow

Cloud Integration capability of SAP Cloud Platform Integration Suite makes cloud integration simple and reliable. It provides out-of-the-box connectivity across cloud and on-premise solutions. In this section usage of the rich integration patterns and features in Cloud Integration to model the business process of posting a billing document from SAP S/4HANA Cloud to SharePoint team site is showcased.

At a high level, Integration to post a billing document to SharePoint consist of the following steps: -

• A timer job to read billing document.


• Initialize values to call SAP S/4HANA Cloud APIs via API Sandbox of SAP API Business Hub


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


• Convert the response from SAP S/4HANA Cloud OData API into File format.


• Post file data to SharePoint via Open Connectors.

Integration Flow Design

SAP Cloud Platform Integration Suite is available for test, explore and try out in SAP Cloud Platform trial. If you have not enabled SAP Cloud Platform Integration Suite in your trial tenant, refer this blog to enable it.

• Logon to your SAP Cloud Platform trial


• Select Subscription and search and select Integration Suite. Click on Go to Application

• It will launch the Integration Suite launch pad in a new browser tab. Select Design, Develop and Operate Integrate Scenarios In case this option is not visible for you, you can click on Manage Capabilities and enable Cloud Integration capability.

• From the Cloud Integration workspace, Navigate to Design tab, click Create to create an integration package.

 

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

Name	SAP and Microsoft Azure Integration Scenarios
Short Description	Package showcasing SAP and Microsoft Azure integration scenarios

• 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 select OK.

Name	Post Billing Document to SharePoint
Description	Integration Flow showcasing posting of billing document files from SAP S/4HANA Cloud to SharePoint

• Select the newly created Integration Flow named Post Billing Document to SharePoint and then select Edit to start editing the integration flow.

• Since a timer-based integration flow will be used the default start message can be deleted. Select the default start message and select Delete.

 

• Select and add the Timer integration step. The default property of timer integration step is to execute the integration flow immediately after you deploy the integration flow. More about the available timer configurations is available in help documentation.

• To set values like API key and billing document id to read data from SAP S/4HANA Cloud API Sandbox from SAP API Business Hub, a Content Modifier can be used. Select Content Modifier integration step from the integration palette and drop it into Integration Process canvas.

• Select Start Timer integration step and then drag the arrow icon to point towards Connect Modifier step to connect the timer and content modifier integration step.

• Change the name of the content modifier step to Initialize S4HC Value from General tab to improve readability.


• Select Message Header Property and select Add. From the action drop down select Create, enter apikey as the Name of the property, select Constant from the drop down for Type and enter your copied API Key from SAP API Business Hub in the value field. This will set the request message header named apikey with the value set by you to be passed to API Sandbox from SAP API Business Hub.

• Select Exchange Property tab and select Add. From the action drop down select Create, enter doc_id as the Name of the property, select Constant from the drop down for Type and enter 90000000 in the value This will result in a property field named doc_id to be created which will be passed as the parameter to fetch the billing document for id 90000000.

• To read the billing document in PDF format, the Request Reply integration pattern with a HTTP Receiver adapter can be used. Select Request Reply from External Call integration palette and drop it into Integration Process canvas.

• Change the name of Request Reply step to Fetch Billing Document in the General tab to improve readability.


• Select and connect the Initialize S4HC Value integration step with Fetch Billing Document step.

• Add in Receiver integration step to invoke SAP S/4HANA Cloud OData API.

• Name of the Receiver can be set to S4HC to improve readability.

• Select and connect the Fetch Billing Document request reply step to the newly added Receiver. This would open the Adapter list, from the available Adapter select HTTP.

• Under the Connection tab, enter details as follows.
  
  
  
  1. Address :- https://sandbox.api.sap.com/s4hanacloud/sap/opu/odata/sap/API_BILLING_DOCUMENT_SRV/GetPDF
  
  
  2. Query :- BillingDocument=%27${property.doc_id}%27
  
  
  3. Method :- GET
  
  
  4. Authentication :- None
  
  
  
  

In the query parameter you can notice that property doc_id is referenced dynamically as ${property.doc_id}. Since the apikey is passed via the message header set in the Initialize S4HC Value integration step the authentication type is selected to None.

• GetPDF service operation of the SAP S/4HANA Cloud ODataAPI, returns the PDF document in the base64 encoded format.

• Add Filter steps to read this file content with XPath expression.

 

• Change the name of the Filter step to Read File Data in the General tab to improve readability.

• Select Processing Enter d:GetPDF/d:BillingDocumentBinary/text() in XPath Expression and select String from Value Type drop box.

• Select and connect Fetch Billing Document to Read File Data integration step.

• 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. Enter xmlns:d=http://schemas.microsoft.com/ado/2007/08/dataservices in Namespace mapping.

• SharePoint connector of Open Connectors requires the file content to be passed as the multipart form request . To create the required multipart form request a Groovy Script is leveraged.

• Change the name of Groovy Script step to Convert to File Format in the General tab to improve readability.

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

• Copy paste the below snippet to the created script page

/*

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("content-type","multipart/form-data; boundary=--------------------------" + id);



return message;



}



def ByteArrayOutputStream getMultiPartBody(payload, filename, id) {



String charset = "UTF-8";

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 );

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



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

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

return output;



}





def Message processData(Message message) {



String charset = "UTF-8";

def id = "238360769909770904663504";



def map = message.getProperties();

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



def payload = message.getBody(String.class).decodeBase64();

message.setProperty("byteSize",payload.length);



def ByteArrayOutputStream output = getMultiPartBody(payload,filename,id);

message = setHeader(message, id);

message.setBody(output.toByteArray());



return message;

}

In script shared the multipart format request is created from the incoming response data. For posting file to SharePoint, size of the uploaded documented is also required. The size of the incoming byte[] data is read and stored in property named byteSize.

• Select Ok to persist the script changes.

• Select and connect the Read File Data to Convert to File Format integration step.

• Add Content Modifier step to initialize the SharePoint connector instance authorization token and the SharePoint team sites where the document will be posted.

• Change name to Initialize SP Values in General tab to improve readability.

• Navigate to Message Header


• Select Add to add new message header. Enter Subsite in Name field and enter your SharePoint team site name in the format /sites/{your_teamsite}. In this blog, a team site named General was used therefore the value of Subsite field is /sites/General.

Note :- If your team site contains spaces , then enter the site name without any spaces in the Subsite field.

• Select Add to add another message header. Enter Authorization in Name field and enter your SharePoint connector instance authorization token from Open Connectors in the value field.

• Select and connect Convert to File Format and Initialize SP Values integration step.

• To post file document to SharePoint via Open Connectors a HTTP Receiver adapter can be used. Select Request Reply from External Call integration palette and drop it into Integration Process canvas.

• Change the name of the newly added Request Reply step to Post File to SharePoint to improve readability.

• Select and connect the Initialize SP Values and Post File to SharePoint integration step.


• To improve readability, select and drag the last Receiver from the integration canvas and place it below Post File to SharePoint integration step.

• Select and connect the Post File to SharePoint Request Reply step to the recently placed Receiver. This would open the Adapter list, from the available Adapter select HTTPS.

• Under the Connection tab, enter details as follows.
  
  
  
  1. Address :-  https://api.openconnectors.trial.eu10.ext.hana.ondemand.com/elements/api-v2/files
  
  
  2. Query :- size=${property.byteSize}&path=%2Fbilling_${property.doc_id}.pdf&overwrite=true
  
  
  3. Method :- POST
  
  
  4. Authentication :- None
  
  
  
  

In this query parameter you can notice the usage of the property.byteSize field set to the query parameter named size. This propery byteSize is set in the Groovy Script step. Name of the file is set using the path parameter which is set to in the formation billing_{document_id}. To dynamically set the document id, you can notice the usage of property.doc_id. The property doc_id is set in the Initialize SP Values integration step. The overwrite query parameter is set to true to override existing file in SharePoint. Setting it to false, will ensure that files are not overwritten and may result in 429 file already exists error.

• Select and connect the Post File to SharePoint to the End message to complete the integration process flow.

• Select Save and then Deploy button to deploy this integration flow to SAP Cloud Platform Integration tenant.

• With this an integration flow that queries for the billing document from the SAP S/4HANA Cloud system and saves the document into a SharePoint via Open Connectors has been successfully created.

Note, the first-time deployment might take some time before the changes are fully deployed.

• Navigate to Monitor to check the status of the deployed integration flow.


• Since the integration flow was designed as a Run immediate timer-based integration the flow will be executed as soon as it deployed. Select Completed Messages tile to view the successfully executed integration flows. In case of any failure it will appear under Failed Messages.

• Check the status of the newly created integration flow from the Monitor Message Processing. If status changes to Completed, then the billing document read from SAP S/4HANA Cloud system will be posted to your SharePoint team site.

• Navigate to Documents tab of your SharePoint site and check for the newly posted billing document.

With this you have successfully created and tested an integration flow that is reading a billing document from SAP S/4HANA Cloud and post it to SharePoint, created a team sites in SharePoint, leveraged the SharePoint connectors to connect seamless to SharePoint site.

More blogs on SAP Cloud Platform Integration Suite available in SAP Community.

[Saurabh]

I am getting error after the the deployment - All the time messages are failed.

 

Any ide - How to inspect such errros.

 

Error Details

org.apache.camel.component.ahc.AhcOperationFailedException: HTTP operation failed invoking https://api.openconnectors.trial.us10.ext.hana.ondemand.com/elements/api-v2/files?28491&path=%2Fbill... with statusCode: 400

[shrutijain04]

Hi divya.mary

In the below step, when we add the authorization from Open connector instance, the integration works well for a few days, but after that it fails with 500 error (token expired) and then the open connector instance gets disabled. It started working again after reauthenticating the open connector instance. How to resolve this issue? Should we generate access token before calling sharepoint APIs?

[Steentje]

The blog is nice but the getpdf returns an error like

Error message