Receiving IDOCs From SAP by Using BizTalk Server

7/30/2019 Receiving IDOCs From SAP by Using BizTalk Server

1/13

http://msdn.microsoft.com/en-

us/library/cc185169(v=bts.10).aspx

Receiving IDOCs from SAP by UsingBizTalk Server

0 out of 1 rated this helpful - Rate this topic

Receiving an IDOC involves the SAP adapter to act as an RFC server to receive aspecial RFC call from SAP. The SAP adapter can receive IDOCs acting as an RFCserver or a tRFC server. For more information about receiving an IDOC with theadapter behaving as a tRFC server, see Receiving IDOCs from SAP in a

Transactional Context by Using BizTalk Server.

The SAP adapter surfaces two different operations to receive IDOCs:

Receive operation enables adapter to receive IDOCs having astrongly-typed schema.

ReceiveIdoc operation enables adapter to receive IDOCs having aweakly-typed schema. This operation receives IDOCs as a string in an XMLmessage under the tag.

On the adapter side, you can specify a value for the ReceiveIDocFormat bindingproperty to specify the format of IDOC the adapter would receive.

Typed specifies the adapter will receive IDOCs with strongly-typedschema. This yields an XML IDOC.

String specifies the adapter will receive IDOCs with weakly-typedschema. This yields an XML message with the tag.

Rfc specifies the adapter will receive IDOCs in any format.

For receiving IDOCs, the SAP adapter also supports a set of message contextproperties that adapter clients can use in the orchestrations. For the list ofproperties, see Message Context Properties for Receiving IDOCs.

For more information about how the SAP adapter supports receiving IDOCs from anSAP system, see Operations on IDOCs. For more information about the structure ofSOAP messages for receiving an IDOC, see Message Schemas for IDOC Operations.

BizTalk Scenarios for Receiving IDOCs from an

SAP System
http://msdn.microsoft.com/en-us/library/cc185169(v=bts.10).aspxhttp://msdn.microsoft.com/en-us/library/cc185169(v=bts.10).aspxhttp://msdn.microsoft.com/en-us/library/cc185169(v=bts.10).aspx#feedbackhttp://msdn.microsoft.com/en-us/library/cc185265(v=bts.10).aspxhttp://msdn.microsoft.com/en-us/library/cc185265(v=bts.10).aspxhttp://msdn.microsoft.com/en-us/library/cc185543(v=bts.10).aspxhttp://msdn.microsoft.com/en-us/library/cc185261(v=bts.10).aspxhttp://msdn.microsoft.com/en-us/library/cc185177(v=bts.10).aspxhttp://void%280%29/http://void%280%29/http://msdn.microsoft.com/en-us/library/cc185169(v=bts.10).aspxhttp://msdn.microsoft.com/en-us/library/cc185169(v=bts.10).aspxhttp://msdn.microsoft.com/en-us/library/cc185169(v=bts.10).aspx#feedbackhttp://msdn.microsoft.com/en-us/library/cc185265(v=bts.10).aspxhttp://msdn.microsoft.com/en-us/library/cc185265(v=bts.10).aspxhttp://msdn.microsoft.com/en-us/library/cc185543(v=bts.10).aspxhttp://msdn.microsoft.com/en-us/library/cc185261(v=bts.10).aspxhttp://msdn.microsoft.com/en-us/library/cc185177(v=bts.10).aspxhttp://void%280%29/http://void%280%29/


2/13

The following table provides key BizTalk scenarios for receiving IDOCs from an SAPsystem:

Input to

Adapter from

SAP

BizTalk Processing

IDOC (via tRFC

interface)

Metadata Design Time

1. Set the binding property GenerateFlatFileCompatibleIdocSche

2. Generate the schema for the Receive operation for a specific

3. Set the binding property ReceiveIdocFormat to Typed.

Orchestration Design Time

1. Receive XML IDOC.

2. Use flat-file assembler to convert XML IDOC to flat-file.

IDOC (via tRFC

interface)




3. Set the binding property ReceiveIdocFormat to Typed.

Orchestration Design-Time

Receive XML IDOC.

IDOC (via tRFC

interface)




3. Set the binding property ReceiveIdocFormat to String.



3/13

1. Receive XML message with flat-file IDOC in tag.

2. Use the WCF adapters XPath support in the receive port conf

XML message. For example:

3. /*[local-name()='ReceiveIdoc']/*[local-name()='idocData']

4. Use flat-file disassembler to convert flat-file IDOC to XML IDO

Important

This approach can be used to receive IDOCs using the new WCF-based SA

existing BizTalk project written to receive IDOCs from the existing BizTalk

approach to receive IDOCs with version number less than the release num

IDOC (via tRFCinterface)


1. Generate the schema for the ReceiveIdoc operation from th

Add-in.

2. Set the binding property ReceiveIdocFormat to String.


Receive XML message with the IDOC represented as a string

How to Receive an IDOC from an SAP System?

Performing an operation on an SAP system using BizTalk Server involves proceduraltasks described in Building Blocks for Developing BizTalk Applications. To receive anIDOC from an SAP system, these tasks are:

1. Create a BizTalk project and generate schema for the IDOC you want toinvoke in the SAP system. While generating the schema make sure you setthe required binding properties, as listed in the previous table. Forinstructions on how to set the binding properties, see Specifying Binding

Properties.

2. Create messages in the BizTalk project for sending and receiving messagesfrom the SAP system.

3. Create an orchestration to receive an IDOC from an SAP system.

4. Build and deploy the BizTalk project.
http://void%280%29/http://msdn.microsoft.com/en-us/library/cc185237(v=bts.10).aspxhttp://msdn.microsoft.com/en-us/library/cc185244(v=bts.10).aspxhttp://msdn.microsoft.com/en-us/library/cc185244(v=bts.10).aspxhttp://void%280%29/http://msdn.microsoft.com/en-us/library/cc185237(v=bts.10).aspxhttp://msdn.microsoft.com/en-us/library/cc185244(v=bts.10).aspxhttp://msdn.microsoft.com/en-us/library/cc185244(v=bts.10).aspx


4/13

5. Configure the BizTalk application by creating physical send and receive ports.

This topic provides instructions to perform these tasks.

Samples Based On This Topic

Samples, ReceiveIDOC and ReceiveIDOC_SYSREL, based on this topic are alsoprovided with the BizTalk Adapter Pack. For more information, see Samples.

Generating Schema

You must generate schema for the Receive operation ofthe ORDERS03.V3.620 IDOC under the /IDOC/ORDERS/ORDERS03 node.See Browsing, Searching, and Retrieving Metadata for IDOC Operations for

instructions on how to generate schema for a particular IDOC. While generating theschema, you might want to set the following properties as well:

GenerateFlatFileCompatibleIDoc Generates tags so thatthe BizTalk flat-file parser can be used in BizTalk scenarios to support flat-fileIDOCs.

FlatFileSegmentIndicator Indicates if the IDOC schema tags should contain segment definition names or segment type names. This isapplicable when a used wishes to send/receive a flat-file IDOC to/from SAP. Ifthe GenerateFlatFileCompatibleIDoc is set to false,then FlatFileSegmentIndicatorbinding property is ignored.

Important

Because you are generating the schema for an inbound IDOC call, make sure you select Se

type drop-down list in the Consume Adapter Service BizTalk Project Add-in.

Defining Messages and Message Types

The schema that you generated earlier describes the "types" required for the

messages in the orchestration. A message is typically a variable, the type for whichis defined by the corresponding schema. You must link the schema you generatedin the first step to the messages from the Orchestration view of the BizTalk project.

For this topic, you must create two messagesone to receive an IDOC from the SAPsystem and the other to send a response.

Perform the following steps to create messages and link them to the schema:
http://void%280%29/http://msdn.microsoft.com/en-us/library/cc185183(v=bts.10).aspxhttp://void%280%29/http://msdn.microsoft.com/en-us/library/cc185460(v=bts.10).aspxhttp://void%280%29/http://void%280%29/http://msdn.microsoft.com/en-us/library/cc185183(v=bts.10).aspxhttp://void%280%29/http://msdn.microsoft.com/en-us/library/cc185460(v=bts.10).aspxhttp://void%280%29/


5/13

To create messages and link to schema

1. Add a new orchestration to the BizTalk project.

2. Open the orchestration view the BizTalk project, if not already open.Click View, point to Other Windows, and click Orchestration View.

3. In the Orchestration View, right-click Messages, and then click NewMessage.

4. Right-click the newly create message and select Properties Window.

5. In the Properties pane for Message_1, do the following:

Use this To do this

Identifier Type Request.

Message

Type

From the drop-down list, expand Schemas, and select ReceiveIDOC.SAPBindingSc

project.SAPBindingSchema2 is the schema generated for the Receive operation.

6. Repeat step 2 to create a new message. In the Properties pane for the newmessage, do the following:

Use this To do this

Identifier Type Response.

Message Type From the drop-down list, expand Schemas, and select ReceiveIDOC.SA

Setting up the Orchestration

You must create a BizTalk orchestration to use BizTalk Server for receiving IDOCsfrom the SAP system. In a typical scenario, the SAP adapter receives an IDOC callfrom the SAP system, processes the request, and passes the response to the SAPsystem. To achieve this as part of an orchestration, the orchestration must contain:

A two-way receive port to receive IDOCs from the SAP system andsend the response.

Send and Receive shapes.

Construct Message shape, and within that a Message Assignmentshape, to generate a response to be sent to the SAP system.

Note

If the orchestration includes a two-way receive port (request-response) to receive ID
http://void%280%29/http://void%280%29/


6/13

response back to the SAP system. If not, the SAP system does not send the next IDO

does not have to send a response to the SAP system.

A one-way send port to send the IDOCs received from the SAP systemto a folder.

A sample orchestration for receiving an IDOC from an SAP system looks like:

Adding Message Shapes

Make sure you specify the following properties for each of the message shapes. Thenames listed in the Shape column are the names of the message shapes asdisplayed in the orchestration above.


7/13

Shape Shape Type Properties

ListenToSAP Receive Set Nam

Set Act

SaveIDOC Send Set Nam

SendResponse Send Set Nam

Adding Construct Message Shape

Within the orchestration, you must generate a response and send it to the SAPsystem. To do so, you must add a Construct Message shape and within that aMessage Assignment shape to your orchestration. The Message Assignment shapeinvokes code that generates a response message that is sent to the SAP system.

The Message Assignment shape also sets the action for the response to be sent tothe SAP system.

Important

If the orchestration includes a two-way receive port (request-response) to receive IDOCs frback to the SAP system. If not, the SAP system does not send the next IDOC. However, if a

send a response to the SAP system.

For the construct message shape, set the Message Constructed propertyto Response.

The code to generate the response could be part of the same Visual Studio solutionas your BizTalk project. A sample code for generating a response message looks likethis.

namespace IdocReceiveResponseMessageCreator{

public class IdocReceiveResponseMessageCreator{

private static XmlDocument Message;private static string XmlFileLocation;private static string ResponseDoc;

public static XmlDocument XMLMessageCreator()


8/13

{XmlFileLocation = "C:\\test\\in";try{

ResponseDoc = (Directory.GetFiles(XmlFileLocation, "*.xml",SearchOption.TopDirectoryOnly))[0];

}catch (Exception ex){

Console.WriteLine("Trying to get XML from: " + XmlFileLocation);Console.WriteLine("EXCEPTION: " + ex.ToString());throw ex;

}//Create Message From XMLMessage = new XmlDocument();Message.PreserveWhitespace = true;Message.Load(ResponseDoc);return Message;

}}

}

Note

After you build the project, IdocReceiveResponseMessageCreator.dll will be created in the

assembly cache (GAC).

Add the following expression to invoke this code from the Message Assignmentshape and to set the action for the response sent to the SAP system. To add anexpression, double-click the Message Assignment shape to open the ExpressionEditor.

Response =IdocReceiveResponseMessageCreator.IdocReceiveResponseMessageCreator.XMLMessageCreator();Response(WCF.Action)="http://Microsoft.LobServices.Sap/2007/03/Idoc/3/ORDERS03//620/Receive/response";

Important

You must explicitly set the action on the response message. If you do not set the action, W

appending Response to the request action. So, the action for the response message

becomes http://Microsoft.LobServices.Sap/2007/03/Idoc/3/ORDERS03//620/ReceiveRespon

appending /response to the request action, for examplehttp://Microsoft.LobServices.Sa

Adding Ports

Make sure you specify the following properties for the logical port. The name listedin the Portcolumn is the name of the port as displayed in the orchestration.


9/13

Port Properties

ReceiveIDOCPort Set Identifier to ReceiveIDOCPort

Set Type to ReceiveIDOCPortType

Set Communication Pattern to Requ

Set Communication Direction to Rec

GetIDOCPort Set Identifier to GetIDOCPort

Set Type to GetIDOCPortType

Set Communication Pattern to One-

Set Communication Direction to Sen

Important

If the orchestration includes a two-way receive port (request-response) to receive IDOCs fr

back to the SAP system. If not, the SAP system does not send the next IDOC.

Adding a Flat File Assembler

You must add an assembler to convert the incoming IDOC message to a flat file.

To add a flat file assembler

1. Right-click the BizTalk project, point to Add, and select New Item.2. From the dialog box, do the following:

Use this

Categories

Visual Studio installed templates

Name


10/13

3. This opens the Pipeline Designer. From the BizTalk PipelineComponents toolbox, drag the Flat file assembler pipeline componentinto the Assemble stage of the send pipeline.

4. From the Pipeline Component Properties view, specify a value forthe Document Schema property. From the drop-down make sure you selectthe schema corresponding to the IDOC receive operation.

Specify Messages for Action Shapes and

Connect to Ports

The following table specifies the properties and their values to be set to specifymessages for action shapes and linking them to the ports. The names listed inthe Shapecolumn are the names of the message shapes as displayed in theorchestration above.

Shape Properties

ListenToSAP Set Message to Request

Set Operation to ReceiveIDOCPort.ReceiveIDO

SaveIDOC Set Message to Request

Set Operation to GetIDOCPort.ReceiveIDOC.Re

SendResponse Set Message to Response

Set Operation to ReceiveIDOCPort.ReceiveIDO

After you have specified these properties, the message shapes and ports areconnected and your orchestration is complete.

You must now build the BizTalk solution and deploy it to a BizTalk Server. For moreinformation, see "Building and Running Orchestrations"at http://go.microsoft.com/fwlink/?LinkId=102359.

Configuring the BizTalk Application
http://void%280%29/http://void%280%29/http://go.microsoft.com/fwlink/?LinkId=102359http://void%280%29/http://void%280%29/http://void%280%29/http://go.microsoft.com/fwlink/?LinkId=102359http://void%280%29/


11/13

After you have deployed the BizTalk project, the orchestration you created earlier islisted under the Orchestrations pane in the BizTalk Server Administration console.

You must use the BizTalk Server Administration console to configure the application.For more information about configuring an application, see "How to Configure anApplication" athttp://go.microsoft.com/fwlink/?LinkId=102360.

Configuring an application involves:

Selecting a host for the application.

Mapping the ports that you created in your orchestration to physicalports in the BizTalk Server Administration console. For this orchestration youmust:

Define send locations and physical send port. This location will containthe IDOCs coming from the SAP system.

Important

For the XMLTransmit pipeline, make sure you select SendIDOC. You created t

Define a WCF-Custom receive port. This port will receive an inboundIDOC from the SAP system and pass it on to the orchestration. This portalso sends the response to the SAP system. For information about howto create WCF-Custom ports, see Manually Configuring a Physical PortBinding to the SAP Adapter.

Important

Make sure the binding property ReceiveIDocFormat is set to Typed.

Important

If the binding property EnableBizTalkCompatibilityMode is set to true, mak

adapter as a resource in your BizTalk application, that is, the application in wh

resources seeTroubleshooting Operational Issues.

Note

Generating the schema using the Consume Adapter Service BizTalk Project Ad

the ports and the actions to be set for those ports. You can import this binding

ports (for outbound calls) or receive ports (for inbound calls). For more informa

Binding File.
http://go.microsoft.com/fwlink/?LinkId=102360http://msdn.microsoft.com/en-us/library/cc185415(v=bts.10).aspxhttp://msdn.microsoft.com/en-us/library/cc185415(v=bts.10).aspxhttp://msdn.microsoft.com/en-us/library/cc185364(v=bts.10).aspxhttp://msdn.microsoft.com/en-us/library/cc185524(v=bts.10).aspxhttp://go.microsoft.com/fwlink/?LinkId=102360http://msdn.microsoft.com/en-us/library/cc185415(v=bts.10).aspxhttp://msdn.microsoft.com/en-us/library/cc185415(v=bts.10).aspxhttp://msdn.microsoft.com/en-us/library/cc185364(v=bts.10).aspxhttp://msdn.microsoft.com/en-us/library/cc185524(v=bts.10).aspx


12/13

You must also add the assembly for the IdocReceiveResponseMessageCreatorproject to your BizTalk application. You created this project to generate theresponse to be sent to the SAP system. To do so:

1. In the console tree on the left side of the BizTalk Server Administrationconsole, under the BizTalk application where you imported the bindings,

right-click Resources, point to Add and then click BizTalk Assemblies.

2. In the Add Resources dialog box, Click Add and navigate to the foldercontaining IdocReceiveResponseMessageCreator.dll. Select the file and thenclick Open.

3. In the Add Resources dialog box, click OK.

Starting the Application

You must start the BizTalk application for receiving an IDOC from the SAP system.For instructions on starting a BizTalk application, see "How to Start anOrchestration" athttp://go.microsoft.com/fwlink/?LinkId=102387.

At this stage, make sure:

The FILE send port to save the incoming IDOC to a file location isrunning

The WCF-Custom receive port to receive IDOCs from the SAP system isrunning.

The BizTalk orchestration for the operation is running.

Executing the Operation

After you run the application, you must go the SAP system and send an IDOC intothe adapter. The adapter receives the IDOC and saves it to a file location specifiedas part of the orchestration.

Possible Exceptions

For information about the exceptions you might encounter while receiving an IDOCfrom an SAP system using BizTalk Server, see Exceptions and Error Handling.

Best Practices
http://void%280%29/http://go.microsoft.com/fwlink/?LinkId=102387http://void%280%29/http://void%280%29/http://msdn.microsoft.com/en-us/library/cc185377(v=bts.10).aspxhttp://void%280%29/http://void%280%29/http://go.microsoft.com/fwlink/?LinkId=102387http://void%280%29/http://void%280%29/http://msdn.microsoft.com/en-us/library/cc185377(v=bts.10).aspxhttp://void%280%29/


13/13

After you have deployed and configured the BizTalk project, you can exportconfiguration settings to an XML file called the bindings file. Once you generate abindings file, you can import the configuration settings from the file so that you donot need to create the send ports, receive ports, etc. for the same orchestration. Formore information about binding files, see Reusing Adapter Bindings.
http://msdn.microsoft.com/en-us/library/cc185332(v=bts.10).aspxhttp://msdn.microsoft.com/en-us/library/cc185332(v=bts.10).aspx

Documents

Receiving IDOCs From SAP by Using BizTalk Server