http://msdn.microsoft.com/enus/library/cc185169(v=bts.10).

aspx

Receiving IDOCs from SAP by Using BizTalk 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 a special RFC call from SAP. The SAP adapter can receive IDOCs acting as an RFC server or a tRFC server. For more information about receiving an IDOC with the adapter 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 a strongly-typed schema.

ReceiveIdoc operation enables adapter to receive IDOCs having a weakly-typed schema. This operation receives IDOCs as a string in an XML message under the <idocData> tag. On the adapter side, you can specify a value for the ReceiveIDocFormat binding property to specify the format of IDOC the adapter would receive. Typed specifies the adapter will receive IDOCs with strongly-typed schema. This yields an XML IDOC.

String specifies the adapter will receive IDOCs with weakly-typed schema. This yields an XML message with the <idocData> tag. Rfc specifies the adapter will receive IDOCs in any format.

For receiving IDOCs, the SAP adapter also supports a set of message context properties that adapter clients can use in the orchestrations. For the list of properties, see Message Context Properties for Receiving IDOCs. For more information about how the SAP adapter supports receiving IDOCs from an SAP system, see Operations on IDOCs. For more information about the structure of SOAP messages for receiving an IDOC, see Message Schemas for IDOC Operations.

BizTalk Scenarios for Receiving IDOCs from an SAP System

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

Input to BizTalk Processing Adapter from SAP

IDOC (via tRFC Metadata Design Time interface)
1. 2. 3. Set the binding property GenerateFlatFileCompatibleIdocSchema to Generate the schema for the Receive operation for a specific IDOC Set the binding property ReceiveIdocFormat to Typed.

Orchestration Design Time

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

IDOC (via tRFC Metadata Design Time interface)

1. 2. 3. Set the binding property GenerateFlatFileCompatibleIdocSchema to Generate the schema for the Receive operation for a specific IDOC Set the binding property ReceiveIdocFormat to Typed.

Orchestration Design-Time

Receive XML IDOC.

IDOC (via tRFC Metadata Design Time interface)

1. 2. 3. Set the binding property GenerateFlatFileCompatibleIdocSchema to Generate the schema for the Receive operation for a specific IDOC Set the binding property ReceiveIdocFormat to String.

Orchestration Design Time

1.

Receive XML message with flat-file IDOC in <idocData> tag.

2. Use the WCF adapters XPath support in the receive port configuratio XML message. For example:
3. /*[local-name()='ReceiveIdoc']/*[local-name()='idocData']

4.

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

Important This approach can be used to receive IDOCs using the new WCF-based SAP adapt existing BizTalk project written to receive IDOCs from the existing BizTalk SAP ad approach to receive IDOCs with version number less than the release number (SY

IDOC (via tRFC Metadata Design Time interface)

1. Generate the schema for the ReceiveIdoc operation from the IDOC Add-in. 2. Set the binding property ReceiveIdocFormat to String.

Orchestration Design Time

Receive XML message with the IDOC represented as a string in the <

How to Receive an IDOC from an SAP System?

Performing an operation on an SAP system using BizTalk Server involves procedural tasks described in Building Blocks for Developing BizTalk Applications. To receive an IDOC from an SAP system, these tasks are: 1. Create a BizTalk project and generate schema for the IDOC you want to invoke in the SAP system. While generating the schema make sure you set the required binding properties, as listed in the previous table. For instructions on how to set the binding properties, see Specifying Binding Properties. 2. Create messages in the BizTalk project for sending and receiving messages from the SAP system. 3. Create an orchestration to receive an IDOC from an SAP system. 4. Build and deploy the BizTalk project.

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 also provided with the BizTalk Adapter Pack. For more information, see Samples.

Generating Schema
You must generate schema for the Receive operation of the 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 the schema, you might want to set the following properties as well: GenerateFlatFileCompatibleIDoc Generates <appinfo> tags so that the BizTalk flat-file parser can be used in BizTalk scenarios to support flat-file IDOCs.

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

Important
Because you are generating the schema for an inbound IDOC call, make sure you select Service 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 which is defined by the corresponding schema. You must link the schema you generated in 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 SAP system and the other to send a response. Perform the following steps to create messages and link them to the schema:

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 New Message. 4. Right-click the newly create message and select Properties Window. 5. In the Properties pane for Message_1, do the following:

Use this
Identifier Message Type

To do this
Type Request. From the drop-down list, expand Schemas, and select ReceiveIDOC.SAPBindingSchema2, 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 new
message, do the following:

Use this
Identifier Message Type

To do this
Type Response.

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

Setting up the Orchestration

You must create a BizTalk orchestration to use BizTalk Server for receiving IDOCs from the SAP system. In a typical scenario, the SAP adapter receives an IDOC call from the SAP system, processes the request, and passes the response to the SAP system. To achieve this as part of an orchestration, the orchestration must contain: A two-way receive port to receive IDOCs from the SAP system and send the response.

Send and Receive shapes.

Construct Message shape, and within that a Message Assignment shape, 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 IDOCs fro

response back to the SAP system. If not, the SAP system does not send the next IDOC. How does not have to send a response to the SAP system. A one-way send port to send the IDOCs received from the SAP system to 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. The names listed in the Shape column are the names of the message shapes as displayed in the orchestration above.

Shape
ListenToSAP

Shape Type
Receive

Properties

Set Name to L

Set Activate t

SaveIDOC

Send

Set Name to S

SendResponse

Send

Set Name to S

Adding Construct Message Shape

Within the orchestration, you must generate a response and send it to the SAP system. To do so, you must add a Construct Message shape and within that a Message Assignment shape to your orchestration. The Message Assignment shape invokes 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 to the SAP system.

Important

If the orchestration includes a two-way receive port (request-response) to receive IDOCs from the back to the SAP system. If not, the SAP system does not send the next IDOC. However, if a one-wa send a response to the SAP system. For the construct message shape, set the Message Constructed property to Response. The code to generate the response could be part of the same Visual Studio solution as your BizTalk project. A sample code for generating a response message looks like this.
namespace IdocReceiveResponseMessageCreator { public class IdocReceiveResponseMessageCreator { private static XmlDocument Message; private static string XmlFileLocation; private static string ResponseDoc; public static XmlDocument XMLMessageCreator()

{ 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 XML Message = new XmlDocument(); Message.PreserveWhitespace = true; Message.Load(ResponseDoc); return Message; } } }

Note

After you build the project, IdocReceiveResponseMessageCreator.dll will be created in the project assembly cache (GAC). Add the following expression to invoke this code from the Message Assignment shape and to set the action for the response sent to the SAP system. To add an expression, double-click the Message Assignment shape to open the Expression Editor.
Response = IdocReceiveResponseMessageCreator.IdocReceiveResponseMessageCreator.XMLMessageCr eator(); 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, WCF-Cus appending Response to the request action. So, the action for the response message becomes http://Microsoft.LobServices.Sap/2007/03/Idoc/3/ORDERS03//620/ReceiveResponse. How appending /response to the request action, for examplehttp://Microsoft.LobServices.Sap/2007

Adding Ports
Make sure you specify the following properties for the logical port. The name listed in the Port column is the name of the port as displayed in the orchestration.

Port
ReceiveIDOCPort

Properties

Set Identifier to ReceiveIDOCPort Set Type to ReceiveIDOCPortType

Set Communication Pattern to Request-Res

Set Communication Direction to Receive-S

GetIDOCPort

Set Identifier to GetIDOCPort Set Type to GetIDOCPortType Set Communication Pattern to One-Way Set Communication Direction to Send

Important

If the orchestration includes a two-way receive port (request-response) to receive IDOCs from the 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

3. This opens the Pipeline Designer. From the BizTalk Pipeline

Components toolbox, drag the Flat file assembler pipeline component into the Assemble stage of the send pipeline. 4. From the Pipeline Component Properties view, specify a value for the Document Schema property. From the drop-down make sure you select the 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 specify messages for action shapes and linking them to the ports. The names listed in the Shapecolumn are the names of the message shapes as displayed in the orchestration above.

Shape
ListenToSAP

Properties

Set Message to Request

Set Operation to ReceiveIDOCPort.ReceiveIDOC.Requ

SaveIDOC

Set Message to Request Set Operation to GetIDOCPort.ReceiveIDOC.Request

SendResponse

Set Message to Response

Set Operation to ReceiveIDOCPort.ReceiveIDOC.Resp

After you have specified these properties, the message shapes and ports are connected and your orchestration is complete. You must now build the BizTalk solution and deploy it to a BizTalk Server. For more information, see "Building and Running Orchestrations" at http://go.microsoft.com/fwlink/?LinkId=102359.

Configuring the BizTalk Application

After you have deployed the BizTalk project, the orchestration you created earlier is listed 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 an Application" 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 physical ports in the BizTalk Server Administration console. For this orchestration you must:
Define send locations and physical send port. This location will contain

the IDOCs coming from the SAP system.

Important

For the XMLTransmit pipeline, make sure you select SendIDOC. You created this pipe
Define a WCF-Custom receive port. This port will receive an inbound

IDOC from the SAP system and pass it on to the orchestration. This port also sends the response to the SAP system. For information about how to create WCF-Custom ports, see Manually Configuring a Physical Port Binding 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, make sure adapter as a resource in your BizTalk application, that is, the application in which you resources see Troubleshooting Operational Issues.

Note

Generating the schema using the Consume Adapter Service BizTalk Project Add-in als the ports and the actions to be set for those ports. You can import this binding file fro ports (for outbound calls) or receive ports (for inbound calls). For more information, se Binding File.

You must also add the assembly for the IdocReceiveResponseMessageCreator project to your BizTalk application. You created this project to generate the response to be sent to the SAP system. To do so: 1. In the console tree on the left side of the BizTalk Server Administration console, 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 folder containing IdocReceiveResponseMessageCreator.dll. Select the file and then click 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 an Orchestration" 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 is running

The WCF-Custom receive port to receive IDOCs from the SAP system is running. 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 into the adapter. The adapter receives the IDOC and saves it to a file location specified as part of the orchestration.

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

Best Practices

After you have deployed and configured the BizTalk project, you can export configuration settings to an XML file called the bindings file. Once you generate a bindings file, you can import the configuration settings from the file so that you do not need to create the send ports, receive ports, etc. for the same orchestration. For more information about binding files, see Reusing Adapter Bindings.