How to Use User-Module for Conversion of IDoc Messages Between Flat and XML Formats
When we exchange messages with our external business partners, IDocs are often used. The IDocs would be sent in flat IDoc format to our business partner. Conversely, when we receive messages from our external business partners, they are also often in flat IDoc format. In this blog, we will take a look at how we can use PI to integrate directly with our external business partners through flat IDoc formatted messages. PI 7.11 introduced a new Java adapter user-module which can translate between flat IDoc formatted messages and IDoc-XML formatted messages. The IDoc-XML messages, once in PI, can easily be used for mappings and configurations. The new user-module will not only validate the metadata of the IDoc, it will also check the validity of the content. In order to do so, the user-module will connect to the SAP backend system and retrieve the metadata and application-related information and check them against the IDoc message. To connect to the SAP backend system, connection information are required. Instead of entering these information in the user-module, the user-module will access them through objects in the NWA. This gives us a “cleaner” management of entering information for the user-module and also allow us to re-use existing objects in the NWA. As a result, to use the user-module, we will need to go through the following steps: * Create a JCA Connection Factory in NWA for the SAP backend system. * Configure the user-module using the objects in the above 2 steps. *User-Module Configuration* For demonstration purpose, in this blog we will create two user-modules. One is to convert IDoc XML to Flat format. The other is to convert IDoc Flat to XML format. h4. 1. Create destination information in NWA. 1. Enter NWA using the URL: http://+:+/nwa 0.1. Navigate to: Configuration Management -> Infrastructure -> Destination 0.1. In Destination, click “Create”: 0.1. Enter a Destination Name, and select RFC in the dropdown. Click Next. 0.1. Select whether Load Balancing is used. In our case, without Load Balancing, we entered values for the Host server, System Number and System ID. Click Next. 0.1. Enter authentication information to logon to the server. Click Finish. 0.1. Do a ping test by clicking on “Ping Destination”. h4. 2. Create a JCA Connection Factory in NWA. 1. In NWA, navigate to: Configuration Management -> Infrastructure -> Application Resources 2. Filter on “SAPJavaResourceAdapter15” and click the “Filter” button. Select “SAPJavaResourceAdapter15” with the JCA Resource type. Click on the tab “Dependent JCA Connection”. Click on “Copy and Add New JCA Connection Factory”. 3. In the “New JCA Connection Factory Creation” screen, tab “Namespace”, enter a JNDI Name. In our case, I entered “CF_CU4_800”. *NOTE:* The JNDI name is the JCA Connection Factory name. 0.1. In the tab “Configuration Properties”, enter the server logon information and click “Save”. 0.1. You should receive the following message: h4. 3. Configure the user-module 1. IDoc XML to flat format conversion This is normally done when we send an IDoc to our external business partner. The IDoc is converted to flat file format. The user-module most likely is executed in the _receiver_ communication channel. The user-module can be used with any java adapter, e.g. file, JMS, JDBC, Mail, etc. To configure the user-module: 1. Go to the Module tab of the communication channel configuration in the Integration Directory. 2. Add a module name, *SAP_XI_IDOC/IDOCXmlToFlatConvertor*, before CallSapAdapter. Select from the dropdown for the Module Type: *Local Enterprise Bean*. 0.1. By default, the module key of *”1″* is assigned. You can rename it to any name. Create 3 Module Key entries in the “Module Configuration”, using the same key value. 0.1. For the Parameter Names and Parameter Values, enter the following: *SAPRelease:* SAP release of the system where the IDoc needs to be validated. *SourceDestination:* The destination name created in the NWA in step 1. *TargetJRA:* The connection factory name created in NWA in step 2. *Sample Test:* Add a module name, *SAP_XI_IDOC/IDOCFlatToXmlConvertor*, before CallSapAdapter. Select from the dropdown for the Module Type: *Local Enterprise Bean*. 0.1. By default, the module key of *”1″* is assigned. You can rename it to any name. Create 3 Module Key entries in the “Module Configuration”, using the same key value. 0.1. For the Parameter Names and Parameter Values, enter the following: *SAPRelease:* SAP release of the system where the IDoc needs to be validated. *TargetDestination:* The destination name created in the NWA in step 1. *SourceJRA:* The connection factory name created in NWA in step 2.