Thursday, October 8, 2015

BizTalk Server: Receiving SAP IDOC Messages


Introduction

"Intermediate documents (IDOCS) are standardized EDI-like documents supported by SAP for asynchronously communicating with both SAP and non-SAP systems. IDOCS are used to send and receive business documents like sales orders to or from a trading partner’s SAP system or external program."
The below is a sample file of IDOC message







In this post, I will explain how to receive and process IDOC message using BizTalk.
Note that I supposed that you installed sap client and sap-wcf adapter in your development machine.

Problem

You have a new request that in your integration middle-ware that using BizTalk server needs to integrates with SAP ERP system which will generate outbound messages for external system using IDOC messages over file system or ftp..etc. As a role of BizTalk developer you need to know how to parse this message and process it into your internal business process.

Solution

BizTalk Server provides a nice wcf-sap adapter to connect to SAP and generate a meta data (schema) of related IDOC messages.
First, when you check the structure of IDOC message, you will notice that it is a flat file content
which means you need to have a flat file schema as shown in previous sample message image.

IDOC messages are complicated messages, so you don't need to build schema manually because it will take a lot of time to build such kind of schema instead you can use wcf-sap adapter to generate schema for you.

There are some tricks and tips you need to consider to generate a proper IDOC schema which I will explain in the followings steps:

  1. Create a new BizTalk Project è  right click project è  select Add è  Add Generated Item
  2. In Add Generated Item Window select Consume Adapter Service è  Consume Adapter Service
  3. In Consume Adapter Service windows select sapBinding in Select a binding drop down list è  click configure button
  4. In Configure Adapter window security tab select User Name in Client credential type drop down list è  enter User name and password as provided by SAP admin
  5.  Select URI Properties tab then set Application Server Host è  Set System Number è   Set Client è   Set Connection type as provided by SAP team è  Click Ok button.  Note these are the minimum requirements you may need to fill other properties in case there are some special configuration in SAP server side
  6.  In Consume Adapter Service window click connect buttonè   select Service (Inbound operations) from select contract type drop down list è  Select IDOC node

      Note: you may receive the following error when you try to search for a message type without selcting IDOC node
  7. Let's say that you interested in Address Master message which is is ARDMAS when you try to search on ADRMAS* you will find this
  8. When you try to select message you will get the following error 
  9. Tip: Don't try to search for SAP IDOC message using search feature, search for message manually using your eyes instead, you are lucky because messages ordered alphabetically :)
  10. Let's Say SAP team informed us to use ADRMAS03.V3(731) which is the latest version  è select the message è    Select Receive then click Add button then click ok button 

  11. Now you can see the generated files which contain 4 scehmas and Binding files. 
  12. Note: IDocOperation.ADRMAS03.731.3.Receive is the main schema that you want to deal with , IDoc.ADRMAS03.731.3 is schema used by previous schema, IDocSharedTypes which is datatype schema imported by IDoc.ADRMAS03.731.3 schema. You can ignore IDocOperation.ADRMAS03.731.3.ReceiveResponse schema and Binding file  because we only receiving file over file system
  13.  When you check IDocOperation.ADRMAS03.731.3.Receive schema you will find out there is no a flat file tab and child delimiter  0xd 0xa which means it is expecting file that generated from Windows system which is Carriage Return Line feed (CR+LF), however in my case SAP in Linux os that generates file with 0x0A Line Feed (LF) delimiter inside the file content
  14. We need to change Schema Editor Extensions to Flat File and we need to replace child delimiter 0xd 0xa with  0x0A in IDocOperation.ADRMAS03.731.3.Receive.xsd and IDoc.ADRMAS03.731.3.xsd , open files using xml editor then replace. The question what if you receive IDOC messages from different SAP providers one using window and other using Linux then you need to use a customer pipeline to replace new line delimiter instead of updating schema manually.

  15. You can test your IDOC message by validating message using schema editor and setting Validate Instance Input type to Native and Input Instance Filename with path of your sample file 
  16. Now you need to create receive pipeline and add Flat file disassembler to Disassemble component and set Document Schema to IDocOperation.ADRMAS03.731.3.Receive schema data type 
  17. Now you are ready to receive idoc message from any File system, ftp, sftp ...etc , create related adapter and set your receive flat file pipeline then you can convert flat file file to idoc xml document

Conclusion 

In this post I walked-throughed how to use wcf-sap adapter to generate IDOC schemas and I highlighted some tips and tricks for working IDOC message which I hope you will help you in any future works