SAP ByDesign Inbound Files Integration with CPI

nerevar · ‎06-07-2021

Hello everyone !

Thats is my first blog post so I hope I'll be doing this right.

Introduction

I would like to share with you the fresh experience I have on integrating "Inbound/Incoming Files" in SAP Business ByDesign system. As there was not much documentation nor examples out there how to do so, and as it is in my opinion a very usefull feature, I decided that writting a blog on that subject could be relevant for the community. So let's start !

Context & UseCase

In most projects you are required to handle communications between different information systems. The frequency of thoses exchanges or their volumes are sometimes so high that performing the task manually is not possible for employees and you need to automate that process.

In my use case I had to integrate Clearing House Statements issued from a third party company (HiPay) that takes care of the payments occuring on the e-commerce website of my customer.

CPI Solution

Cloud Platform Solution is SAP solution to address those kind of requirements.

I will describe you step by step how it is working and how you can adapt/modify the solution to fit your specific needs.

Requirements

- You need to create and configure one Clearing House Account on the relevant company in SAP Business ByDesign.

- (optional) If you want to integrate Bank Statements instead you need to have at least one bank account set up on the relevant company.

- Of course you need a CPI licence on one of your Business Technology Platform Sub-Accounts.

- Also you need extended access to a SAP Business ByDesign environment

- if possible a Business User account dedicated to the task of processing files (with a dedicated password policy setting to avoid service disruption).

SAP Business ByDesign Manual Integration

To manually import Bank files in ByD you go to Liquidity Management > File Management > Inbound Files

Then you can create a new file entry and get to this screen :

Then you have to chose what kind of file you want to integrate and which company is related to it, and add the file attachment within the expected format.

To process the file click Start File Upload

(this might give you errors of formats or data if the system is having trouble integrating the file)

= > All those steps we described can be performed automatically as all business objects involved in the screen can be managed through an odata service.

Odata Service

Here is the Business Object Structure that is used to handle Incoming Files in Sap Business ByDesign :
As expected the BO can be used in an odata service as so :Object Hierarchy :
CompanyPaymentFileRegister
CompanyPaymentFileRegisterIncomingFile
CompanyPaymentFileRegisterIncomingFileAttachmentFolder
We can create/update entries for each of those objects.

Here I also added the Company and CompanyCurrentName Entities because we need to find out the technical ObjectID of the company to know which CompanyPaymentFileRegister entry we will use to create the IncomingFile entry.

Hint : you can also get those UUIDs from dev console holding ctrl+shift+alt+D from the adequate Business Object screen

The Start File Upload action is also available in odata as an import function :

We will describe in details how it works in the next section.

For the full service reference check out Service Configuration

Postman Unit Testing

As stated in previous part you first need to find out the company ObjectID that you are working on.

If you need to dynamically chose the company in your Integration process then this is a different and specific case that I will not cover here.

First call will be used to get the right CompanyPaymentFileRegister entry of your company and also getting the x-crsf-token to perform the other requests.

Take the ObjectID of the entry related to the CompanyUUID relevant for you and report it in the next step as the ParentObjectID:

Fill in the HouseBankUUID representing the third party system you are integrating.

The ContentTypeCode would be the type of entry you are expecting :

1 Bank Statement

4 Bank Advice

6 Clearing House Statement

7 Bank Transaction Status Notification

In my case it was "Clearing House Statement".
After that you can create an attachment File

The ParentObjectID would be the ObjectID created in previous step.

And Finally to process the file you need to call the import odata function like so

I recommend you use an environment set of variables in postman and declare the one used in the different requests and Tests scripts so that you can iterate easier through each steps.

If all those steps worked for you then you can use the same logic in a CPI Flow.

The full Postman collection

CPI solution

Now that we understand what are the different steps to create an inbound file we can use that in an iFlow !

The iFlow example is available in the Github, you can import it to your CPI instance and configure it or even customize it to meet your requirements.

The first step of the flow is very specific to your context, whether you have to integrate the files from an ftp service, webservice or any other way...

The second step is the mapping between the data structure (that relies on the first step) and the data structure expected for SAP Business ByDesign. In a case of a "Clearing House Statement" file this is the expected format :

<?xml version="1.0" encoding="utf-8"?>

<PaymentOrderProcessingStatementNotification>

 <!-- ID du clearing, à incrémenter à chaque chargement  -->

 <ID>1</ID>

 <!-- Clearing House  > Clearing House   -->

 <ClearingHouseAccount>

  <CompanyClearingHouseID>1334553</CompanyClearingHouseID>

 </ClearingHouseAccount>

 <!-- Constant  -->

 <TypeCode>1568</TypeCode>

 <!-- Constant  -->

 <FormatCode>01</FormatCode>

 <!-- Number of items within clearing house   -->

 <ItemTotalNumberValue>2</ItemTotalNumberValue>

 <!-- Sum € of items.PaymentAmount  -->

 <TotalAmount currencyCode="EUR">160</TotalAmount>

 <!-- Clearing house date (used for easy bank compensation ) -->

 <Date>2021-03-23</Date>

    <!-- item 1 -->

    <PaymentOrderProcessingStatementItem>

            <!-- Constant  -->

          <TypeCode>350</TypeCode>

            <!-- used to clear post in customer account  -->

          <PaymentReference>

           <ID>EXTERNALREFERENCE_106</ID>

            <!-- constant  -->

           <TypeCode>23</TypeCode>

          </PaymentReference>

            <!-- direction of payement (+ 66 = mvt 1 or - 66 mvt 2)  -->

          <PropertyMovementDirectionCode>1</PropertyMovementDirectionCode>

            <!-- Amount  -->

          <PaymentAmount currencyCode="EUR">80</PaymentAmount>

            <!-- I think it goes into another account  -->

          <FeePercent>0</FeePercent>

          <PaymentExecutionDate>2021-03-23</PaymentExecutionDate>

          <ExternalTypeCode></ExternalTypeCode>

            <!-- used to clear post in customer account  -->

          <ExternalPaymentReference>

           <ID>HIPAY126</ID>

          </ExternalPaymentReference>

            <!-- Ref card  -->

          <PaymentCardProviderReference>j75a4ad4-7492-4183-96d6-ee6cef00f182</PaymentCardProviderReference>

     </PaymentOrderProcessingStatementItem>

    <!-- item 2 -->

  <PaymentOrderProcessingStatementItem>

      <TypeCode>350</TypeCode>

      <PaymentReference>

       <ID>EXTERNALREFERENCE_102</ID>

       <TypeCode>23</TypeCode>

      </PaymentReference>

      <PropertyMovementDirectionCode>1</PropertyMovementDirectionCode>

      <PaymentAmount currencyCode="EUR">80</PaymentAmount>

      <FeePercent>0</FeePercent>

      <PaymentExecutionDate>2021-03-23</PaymentExecutionDate>

      <ExternalTypeCode></ExternalTypeCode>

          <ExternalPaymentReference>

           <ID>HIPAY123</ID>

          </ExternalPaymentReference>

      <PaymentCardProviderReference>j75a4ad4-7492-4183-96d6-ee6cef00f183</PaymentCardProviderReference>

 </PaymentOrderProcessingStatementItem>

</PaymentOrderProcessingStatementNotification>

I made a quick video to explain the iFlow in details, hopefully that will be more digest than a sequence of screenshots and descriptions...

Conclusion

Hope this helped. We used this iFlow to integrate with HiPay Payment Service and we are planning to do something similar with Paypal and Stripe.

Let me know in the comments If you have any questions, I'll try to answer them if I can.

The following Resources:

- odata service definition

- postman collection

- iFlow sample

are available in this Github public repository

SAP ByDesign Inbound Files Integration with CPI

Requirements

SAP Business ByDesign Manual Integration

Odata Service

Postman Unit Testing

CPI solution

Conclusion

IDoc Basics For Functional Consultants

LSMW for Functional Consultants in simple step-by-step way

Pricing procedure Steps and Details in SAP MM

1	Bank Statement
4	Bank Advice
6	Clearing House Statement
7	Bank Transaction Status Notification