USING POSTMAN to test your i-Flow – read data from a tab-delimited source and posting into S/4 HANA Cloud.
You are required to develop an integration scenario (I-Flow) wherein data is to be read from a tab-delimited text file and the data is to be posted in the S/4 HANA Cloud system, through a white-listed API.
Example: Finance data is available in a text file from the customer’s source system, which is in tab-delimited format. This file (normally) will be stored at a SFTP location. We are developing an I-Flow to read this file and post the data in S/4 HANA Cloud, through the POST method of the Journal entry API - Journal Entry - Post (asynchronized). As a developer, you still don’t have the details of the SFTP file location, but you want to start building your I-Flow with the available information.
· You have access to the CPI tenant to develop the I-Flow
· You have access to the customer’s cloud system to make the requisite technical settings.
To build an I-flow from the scratch, perform the following steps:
1) Create the XML schema
Depending on the data available in your input (tab-delimited) text file, you will first need to create a relevant XML schema (.xsd file) for your input. This is important because before you can pass on the data to the S/4HANA Cloud system, you first need to ensure it is available to your I-Flow in the correct format. First, the input data needs to be converted into a standard XML format, and then it needs to be mapped to the relevant format which is desired by the whitelisted API.
A sample of the input file for this example is shown below:
As can be seen, the file consists of multiple fields (first row shows field headers). Some of the fields have empty values and the data is separated by tabs in the tab-delimited text file.
To create the XML Schema for this input, you can use any free online converter from tab to xml format first. In our example, I have used online conversion at http://convertcsv.com/csv-to-xml.htm.
The XML obtained for this input was as below:
Subsequently, you need the xsd file for this XML schema. Again, use any basic converter available online to do this. I used the online tool https://www.freeformatter.com/xsd-generator.html for converting the XML to XSD. Below is what the XSD will look like. You can of course edit the names of the tags and fields as well as the data types as desired:
Save this XSD file locally on your PC.
2) Download the WSDL
Now that you have the xml format for your input file, we now need to have the same for the output format. This can be done by downloading the WSDL for the whitelisted API that we are going to use to post data into S/4 HANA Cloud system. In order to do this, navigate to the following link on the SAP API HUB
Click on the “Details” section, and subsequently click on the “Download Specification”, followed by “WSDL” - Steps 1,2 and 3 as shown in the snapshot below:
Here is the downloaded WSDL
3) Build the Integration-Flow
Now is the time to start building your I-Flow.
In the CPI tenant, Design section, choose a package and in “Edit” mode, choose “Add -> Integration flow”
Provide a name , ID and description for the new Integration artifact.
Click to choose the integration flow created.
Choose the “Edit” mode
Since we need to first convert our text to XML format, a converter will come in handy here. Choose the CSV to XML converter as shown in the snapshot below.
Rename the Converter appropriately
Navigate to the “Processing” tab. Here you need to provide the XML schema (xsd file) along with other information.
Here, the XML schema is the .XSD file that you created and saved earlier. You can upload it from the local PC by clicking on the “Select” button. The “Path to Target Element in XSD:” specifies the XML tags which hold the data. In the XSD file that you created above, the tags were “Root/Row”. However, in my example, I renamed them to “glentry/Item”. Choose the “Field Separator” as “Tab”.
Remember to keep saving your Integration-Flow.
The next step is to have a mapping of our source message to the target WSDL that we downloaded from the API hub earlier.
To do this, add a Message mapping to your I-Flow.
Choose the “Create” option from the context menu of the Message mapping that you just added.
Provide a name for the message mapping and click on “Create”.
You now need to specify the source and target messages before you can start mapping.
Click on “Add source message” and specify the .XSD file. It should be available already, but if not, upload it from your PC.
Similarly, upload the WSDL file of the API downloaded earlier. Mapping will appear like in the screenshot below.
Now, you need to map the fields from the source structure (XSD) to the target structure (WSDL). After mapping the required fields, the mapping will look like below. Please note that detailed mapping for this API is not considered in the context of this blog.
Post this, you need to finish building your I-Flow. The data mapped to the target WSDL needs to be finally posted in the S/4 HANA Cloud system by specifying the URL of the API mentioned in this blog earlier. This is done by adding a “Request Reply” step to the I-Flow.
To do this, add a “Request Reply” step from the “Call -> External Call ->
Connect the message mapping to the “Request Reply” and subsequently connect the “Request Reply” to the final “Receiver” using a “SOAP” Connector. The details of the SOAP connector should be as below:
The “Address” is the URL of the API that is to be called from the SAP CPI tenant. The “Authentication” is basic using the credentials set up in the Communication arrangement (not covered as part of this blog).
Don’t forget to connect the “Request Reply” to the “End” step as well. This will complete the building of the I-Flow (pending the task of SFTP server configuration at source).
You are yet to get the SFTP server details to read the file. As a result, instead of testing with a real file, you need to test your I-Flow with data input manually.
While developing I-flows in the SAP Cloud Platform Integration, the CPI tenant does provide the option of using Content modifiers, wherein you can put the sample test data. However, the tool does seem to present a problem while working with tab-delimited input. In case of blank data fields being present, the CPI tool does not seem to recognize blank values. As a result, consecutive tabs are recognized as a single tab and values are treated accordingly. This presents a problem in mapping the input as per the correct and desired XML schema. Comma-separated inputs seem to work without a problem though.
While you still need to wait to get SFTP details to test out with a real file, here is something you can do to “quick-test” your integration flow. You can use the POSTMAN application to test out your integration flow. You can directly copy-paste your data and pass it to your I-flow from POSTMAN using a HTTPS connection.
To enable sending data from POSTMAN through HTTPS, add a sender to your I-Flow as shown below. You may want to remove the “Sender” created by default and add a new one.
Participants à Sender
Drag the connector from the Sender to the “Start” step.
Choose HTTPS as the Adapter type in the dialog box that follows
Mention the HTTPS adapter details as below:
Provide an address, which is basically the path to the integration artifact.
Your I-Flow is now enabled for passing data to it from a HTTPS source.
Save and Deploy your I-Flow.
Once deployment is successful, navigate to the “Operations” view in your CPI tenant instance.
Under “Manage Integration Content”, navigate to the tile which shows the I-Flows that have been started.
On the left-hand side, you can see the list of I-Flows that have been deployed. Successful deployment will show the status as “Started”. Find your I-Flow and click on it.
Upon clicking, the details of the I-Flow post deployment will be available on the right side.
Take note of the Endpoint URL (highlighted in screenshot above – details have been hidden but it should show you on your screen). Copy and paste it on a notepad or elsewhere as this will be used in the subsequent step.
Install “POSTMAN” App on your PC, if not already installed.
Once installed, open the POSTMAN app and create a new Request.
Since we are using a POST method of the API in our example, choose the “Post” Method.
Now paste the endpoint URL that was copied above in the previous step.
Click on the Authorization Tab to enter login credentials to the CPI tenant.
Click on the “Body” tab and paste your input data (tab-delimited) here.
Now, click on the “Send” button to send the data to the SAP Cloud platform (CPI).
The response will be shown in the relevant tab below.
This completes the basic flow of designing your I-Flow and testing it.
It may be noted that POSTMAN was able to recognize the tab-delimited data pretty-well, in contrast to the CPI tool which might still need some improvement when it comes to handling such data. It does not really recognize consecutive tabs which might mean empty fields of data. This (POSTMAN) presents a quick and easy way to test your mappings, along with its other capabilities. While working with the actual file read from SFTP location, this issue may not arise but quite often, the developers are unable to know the final SFTP location with the initial requirement and, in the interest of time, they want to start the development of their integration-flow. This kind of option gives them an easy and quick way to test their mappings and the I-flow in general.