Mapping an SAP ECC IDOC to an SAP Business ByDesign A2X Service with Hana Cloud Integration

Business ByDesign comes with basic “out of the box” integration scenarios to SAP ECC. This includes for example master data integration for material and customer account data via IDOC XML, as described for example under the following link:

http://help.sap.com/saphelp_byd1502/en/PUBLISHING/IntegrationScenarios.html#MasterDataIntegrationwithSAPERP

While this enables very quick adoption of running integration scenarios, the lack of scenario extensibility can be a drawback, when larger data sets shall be integrated.

This blog describes step by step, how to realize an alternative approach for master data replication based on an ECC IDOC and a ByD A2X Service. The IDOC is sent from SAP ECC as an XML / SOAP message to Hana Cloud Integration (HCI). HCI maps the IDOC XML to the ByD web service XML format and invokes the A2X service interface.

The pure mapping of data structures is very similar to e.g. standard iFlows for master data replication between SAP ECC and SAP C4C. Specific care however needs to be taken of the web service response handling, due to the synchronous nature of A2X services. Adding additional field mappings to the project is then quite simple.

The material master replication based on the MATMAS05 IDOC Type serves as an example for the implemention of this communciation pattern.

The Eclipse project files that are required to run the example scenario are attached to this blog. The files need to be unzipped first, and then renamed from .txt to .zip. The resulting zip files can be imported as HCI Integration Projects into Eclipse.

ByD Communication Arrangement and WSDL File for A2X Service

To obtain a web service endpoint that can be invoked from an external system (in this case from HCI), a Communication Arrangement needs to be created in the ByD system (WoC view: Application and User Management –> Communication Arrangements). This in turn requires a Communication Scenario to be created, which contains the Manage Material In service, and a Communication System instance, which represents the calling system.

The WSDL file of the service endpoint can then be downloaded from the Communication Arrangement screen:

ALE Scenario Configuration and WSDL File for IDOC XML Message

Standard ALE Configuration is required to enable sending of IDOCs for material master records from ECC. This includes the following entities:

• Logical System that represents the receiving ByD system
• Distribution Model
• Change Pointer Activation
• Partner Profile
• ALE Port
• HTTP Connection

The ALE Port has to be of type XML HTTP, see transaction WE21:

The HTTP connection has to be of type “G” – “HTTP Connection to external Server”, see transaction SM59:

Here, the host name of the HCI worker node, and the URL path as configured in the HCI iFlow (see below), have to be maintained. The URL path has to have the prefix /cxf/. SSL needs to be active for the connection.

The WSDL file for the IDOC basic type (MATMAS05) or a related extension type can be created with ABAP report SRT_IDOC_WSDL_NS directly in the ECC system. The report progam is provided with SAP Note 1728487.

Integration Flow Project in Eclipse

The Eclipse plugin for development of HanaCloud Integration content needs to be installed, as documented for example under the following link:

https://tools.hana.ondemand.com/#hci

Then an Eclipse HCI project of type “Integration Flow” can be created via the project wizard:

The project will finally contain at least the following entities:

• iFlow definition
• Message Mapping definition
• WSDL files that describe the two XML signatures to be mapped

The following picture proposes an iFlow design to support the communication pattern that is discussed here:

This example iFlow contains the following elements:

1. Sender System

Named SAP_ECC in the example.

Specifies the credentials to be used for service invokation on HCI (basic authentication vs. client certificate based authentication).

2. Sender SOAP Channel

Specifies the protocol (plain SOAP), and the endppoint URL path for service invokation on HCI. This has to fit to the URL path maintained in the SM59 connection on ECC (see above).

The plain SOAP protocol is chosen instead of the IDOC SOAP protocol to be able to influence the response that is sent back to ECC based on the response received from ByD.

3. Content Modifier A

Reads the IDOC number from the IDOC XML payload through an XPath expression and stores it as a Property in the context of the iFlow execution.

4. Message Mapping

Defines the mapping of the IDOC XML structure to the A2X service XML structure. The two corresponding WSDL files that have been extracted as described above, have to be uploaded to the message mapping for this purpose:

The mapping definition itself can mostly be done by dragging source elements to target elements in the graphical mapping editor.

The mapping definition that is part of the project file attached to this blog contains all element mappings provided by the standard material master inegration scenario, as described under the following link:

http://help.sap.com/saphelp_byd1502/en/ktp/Software-Components/01200615320100003517/BC_FP30/ERP_Integration/Subsidiary_Mapping_Info/WI_MD_Mapping_Info.html).

In addition, the gross weight is mapped to the quantity characteristic of the ByD material, which is a frequently requested feature.

5. Request-Reply Service Call

Is used to handle the response of the synchronous web service call and transfer it to subsequent processing steps of the iFlow.

6. Receiver SOAP Channel

Specifies the communication protocol that is used for the call to ByD (plain SOAP), the end point URL to be called, and the credentials to be used for authentication at the ByD system.

In this case, basic authentication with user and password is used. The credentials object is deployed to the tenant (see “Deployed Artifacts”).

7. Receiver System

Named SAP_ByD in the example.
Represents the target ByD system but doesn’t contain any additional relevant information.

8. Exclusive Decision Gateway

Defines the route to be chosen for further processing, depending on the web service response content.

The “Success” route is chosen by default.

The “Error” route is chosen if the ByD response contains a log item with severity code 3 (= error), which is the case if an application error has occurred. This information is extracted from the response payload through an XPath expression. Technical errors (e.g. due to wrong message payload syntax) are returned as SOAP faults with HTTP code 500. Such errors are directly handed back to the sender (i.e. here the ECC syystem) by the iFlow processing logic.

9. Content Modifier B

Assembles the IDOC XML response message in the success case. The IDOC ID (DOCNUM) in the sender system is read from the property, which has been set by Content Modifier A for this purpose.

10. Content Modifier C

Assembles an XML repsonse message for the error case. The message contains the IDOC number in the ECC sender system and error information as received in the web service response issued by the ByD tenant.

The IDOC number is read from the iFlow properties and written into a header variable of the content modifier entity, since the subsequent storage operation can only access header variables to fill the Entry ID, but no property variables.

The error text is again extracted from the web service response payload through an XPath expression.

11. Data Store Operation (Write)

Persists the error response message in the tenant’s data store. It is saved with the IDOC number as Entry ID.

12. Final “Channel”

Indicates that a response is sent back to ECC, but contains no additionally relevant information.

Value Mapping Project in Eclipse

Value mappings need to be defined in a separate Eclipse HCI Integration Project of type “Value Mappjng”.

The value mappings are then provided in the automatically generated file “value_mapping.xml”.

For the example project that is developed here, a value mapping is required only to map the ECC Material Group ID (MARA-MATKL) to a ByD Product Category ID. The respective mapping XML entry looks as follows:

…and can be accessed from the message mapping definition as follows:

Trigger Material Master Replication

Create / change material master in ECC (transaction MM01/MM02):

…including basic data text:

Trigger Replication (transaction BD10):

Check that IDOC has been transferred successfully (transaction WE05 or BD87).

Verify the replication result in the ByD tenant:

Check Error Handling

An application error on ByD application side can be caused e.g. by changing the value mapping from ECC Material Group Code to ByD Product Category to obtain a target value that doesn’t exist in the ByD system.

Based on the iFlow design that is discussed here, the IDOC processing will go into an error status on the ECC sender side in such a case. To obtain the error description, there are two options:

1. In ECC, transaction SRTUTIL, display the failed service call in the error log. The response message payload contains the error information as assembled by the iFlow in the “Error” route:

2. Access the tenant data store on Eclipse, and download the message that has been written into the data store:

To be able to download entries from the data store, the user must have the “ESBDataStore.readPayload” permission, which is part of the “Business Expert” user role.