Generating a WCF Client for IDOC Operations Using the Add Adapter Service Reference Plug-in Using SAP Adapter in Biz Talk

This section provides instructions on how to browse, search, and retrieve metadata from SAP for IDOC operations using Add Adapter Service Reference Plug-in or Consume Adapter Service Add-in. Most of the instructions are same for both Add Adapter Service Reference Plug-in and Consume Adapter Service Add-in. Wherever applicable, separate procedures are provided for using Add Adapter Service Reference Plug-in and Consume Adapter Service Add-in.

Before performing the steps provided in the following sections, you must have:

• Created a Visual Studio project.
  
  
• Connected to the SAP system using Add Adapter Service Reference Plug-in or Consume Adapter Service Add-in. For instructions see Connecting to the SAP System in Visual Studio. Note that before connecting to an SAP system to generate schema or a WCF client for IDOCs, you must set certain binding properties.
  
  
  • GenerateFlatFileCompatibleIdocSchema
    
    
  • ReceiveIdocFormat
    
    
  • FlatFileSegmentIndicator
    
    
  These properties govern how metadata for IDOC is retrieved from an SAP system. For more information about these properties, see Working with BizTalk Adapter 3.0 for mySAP Business Suite Binding Properties. For instructions on how to set the binding properties see Specifying Binding Properties.
  
  

Browsing IDOCs in an SAP System

---

While browsing metadata using Add Adapter Service Reference Plug-in or Consume Adapter Service Add-in, the SAP adapter surfaces separate operations for sending and receiving IDOCs from an SAP system.

• Send and Receive. Adapter clients can use these operations to send and receive IDOCs from an SAP system using a strongly-typed schema. The adapter surfaces these operations separately for each IDOC and are available under the respective IDOC node in the Add Adapter Service Reference Plug-in or Consume Adapter Service Add-in.
  
  
• SendIdoc and ReceiveIdoc. Adapter clients can use these operations to send and receive IDOCs from an SAP system using a weakly-typed schema. The SAP adapter only surfaces one SendIdoc and ReceiveIdoc operation for all IDOC. These operations are available directly under the IDOC node in the Add Adapter Service Reference Plug-in or Consume Adapter Service Add-in.
  
  

Perform the following steps to browse IDOCs in an SAP system using the Add Adapter Service Reference Plug-in or Consume Adapter Service Add-in.

To browse IDOCs in an SAP system

---

1. In the Consume Adapter Service Add-in (or Add Adapter Service Reference Plug-in), from the Select contract type drop-down list, select the type of contract based on whether you will be performing inbound or outbound operations using the adapter.
   
2. In the Select a category box, click the IDOC node to see the IDOC message types in the Available categories and operations box. Alternatively, you can also see the IDOC message types by expanding the IDOC node.
   

   Tip
   You can directly go to the “immediate” category node or subcategory nodes in the tree, by typing the name of the artifact in while the focus is on the tree view in the Select a category box. For example, to jump to the ACC_BILLING IDOC message type, keep the focus on the IDOC node, and then type ACC_BILLING.

   The following figure shows the Consume Adapter Service Add-in listing the IDOC message types. The root IDOC node also surfaces a SendIdoc option to send weakly-typed IDOCs to the SAP system.
   
   
   
   

   Note
   For an inbound scenario, the root IDOC node surfaces a ReceiveIdoc operation to receive weakly typed IDOCs.

3. Click the IDOC message types to see the relevant IDOC type. The following figure shows the Consume Adapter Service Add-in with the IDOC type under a particular IDOC message type.
   
   
   
   
4. Click the IDOC types to see the different versions for an IDOC type. The following figure shows the Consume Adapter Service Add-in with the versions for a particular IDOC type.
   
   
   
   
5. Click the version of an IDOC type to see the supported operations on that IDOC type. The following figure shows the Consume Adapter Service Add-in with the operation supported for a particular IDOC type version.
   
   
   
   

Searching IDOCs in an SAP System

---

While searching metadata for IDOCs in an SAP system using Add Adapter Service Reference Plug-in or Consume Adapter Service Add-in, the SAP adapter:

• Supports wildcard characters in the search expression.
  
• Enables search immediately under the node at which the search operation is performed.
  

The following table lists the special characters that can be used for search and their interpretation by the SAP adapter.

Special character	Interpretation
+ (plus)	Matches exactly one character. For example, A+ matches AB, AC, AD
* (asterisk)	Matches zero or more characters. For example, A* matches A, AB, ABC.

For more information about the special characters supported by the adapter, see How Does the Adapter Surface SAP Metadata?
Perform the following steps to search IDOCs in an SAP system using the Add Adapter Service Reference Plug-in or Consume Adapter Service Add-in.

To search IDOCs in an SAP system

---

1. In the Consume Adapter Service Add-in (or Add Adapter Service Reference Plug-in), from the Select contract type drop-down list, select the type of contract based on whether you will be performing inbound or outbound operations using the adapter.
   
2. In the Select a category box, click the IDOC node.
   

   Important
   You can search for IDOCs only at the root level.

3. In the Search in category text box, enter a search expression to search for a specific IDOC message type. For example, to search for IDOCs that have "MATMAS" in their names, type *MATMAS* in the text box.
   
4. Click the button with the right-arrow icon to start the search. After the search is complete, the Available categories and operations box lists the IDOCs that satisfy the search criteria.
   The following figure shows the Consume Adapter Service Add-in listing the IDOC search result.
   
   
   
   

Generating Schema for IDOC Operations Using Consume Adapter Service Add-in

---

You can use the Consume Adapter Service Add-in to generate schema for selected SAP artifacts. Once you have browsed and searched for the artifacts you want to invoke, you can generate schema for those artifacts and send messages, conforming to the schema, to the SAP system.

Note
You can select category nodes to return all the operations in that category's sub-tree—for example, you can select an IDOC type (to generate schema for all the versions of IDOCs in that group) or select a specific version of IDOC to generate schema for only that version of IDOC. For more information about the nodes, see Metadata Node IDs.

To retrieve metadata for IDOCs

---

1. In the Consume Adapter Service Add-in from the Select contract type drop-down list, select the type of contract based on whether you will be performing inbound or outbound operations using the adapter.
   
2. In the Select a category box, click the IDOC message type or the IDOC type for which you want to generate metadata.
   
3. In the Available categories and operations box, select the IDOC type or the supported operations for which you want to generate metadata and click Add. The selected IDOC types or operations are listed in the Added categories and operations box.
   The following figure shows the Consume Adapter Service Add-in listing the selected IDOCs.
   
   
   
   
   If you want to generate schema for multiple operations, there may be some duplicate element definitions among these schema that may cause failure in compiling the BizTalk project. For example, consider a scenario where you generate schema for an operation “Op1”. The schema for “Op1” contains a parameter of complex data type “CT1”. After generating the schema for “Op1” you close the Consume Adapter Service Add-in and re-open it to generate schema for another operation “Op2”. Assume that “Op2” also contains a parameter of complex data type “CT1”. After you exit the Consume Adapter Service Add-in and compile the project, you will get compilation errors because the complex data type “CT1” is defined twice in different XSD files. In such situations, we recommend the following:
   
   • Generate schema for all the operations in a single run of Consume Adapter Service Add-in. This ensures that the Consume Adapter Service Add-in generates only one definition for the complex data type “CT1”.
     
   • If you want to generate schema for multiple operations across different runs of Consume Adapter Service Add-in, make sure you select the Generate unique schema types check box so that the generated XSD files contain unique namespaces for the complex data type “CT1”.
     
4. Click OK. The schema file is saved with an .xsd extension at the same location as the IDOC project.
   By default, the files are created with the naming convention "SAPBindingSchema<n>.xsd", where 'n' can be 1, 2, etc. depending on the number of schema files created. Alternatively, you can provide a custom name to the schema files by entering a name in the Filename prefix text box. The Consume Adapter Service Add-in now creates schema files with the naming convention <filename prefix>Schema<n>.xsd.
   

   Note

   The Consume Adapter Service Add-in also creates a binding file (an XML file) containing the binding properties that you specified while generating the schema for an operation and the SOAP action to invoke the operation. You can import this binding file in the BizTalk Server Administration console to create a WCF-Custom port with the connection URI, binding properties, and the SOAP action set. For more information, see Configuring a Physical Port Binding Using a Port Binding File.

5. On the File menu, click Save All.
   

---

You can use the Add Adapter Service Reference Plug-in to generate either WCF client code to send IDOCs to an SAP system or a WCF service contract to receive IDOCs from an SAP system.

To generate a WCF client or a WCF service contract for IDOCs

---

1. In the Add Adapter Service Reference Plug-in, from the Select contract type drop-down list, select the type of contract based on whether you will be performing inbound (receiving IDOCs) or outbound (sending IDOCs) operations.
   
2. In the Select a category box, expand the IDOC node, and then browse or search for the IDOC message type or the IDOC type that you want to send or receive.
   
3. In the Available categories and operations box, select the IDOC type or the supported operations for which you want to generate a WCF client (or WCF service contract), and then click Add. The selected operations are listed in the Added categories and operations box. You can select any node that is listed in the Available categories and operations box. If you select a category node, then all of the operations available under that node and its sub-nodes will be added.
   

   Important
   The Add Adapter Service Reference Plug-in generates a unique WCF client class (or WCF service contract) for each IDOC type. Depending on the categories and operations that you select, more than one WCF client class may be generated. For more information, see Generating a WCF Client or a WCF Service Contract for SAP Artifacts.

4. For most scenarios the default serialization options are sufficient; however, if needed, you can control several aspects about the code that is generated and the type of serializer that is used. To set these options:
   
   1. Click Advanced Options to open the Advanced Options box.
      
      
   2. In the Advanced Options box under Choose options for generated proxy, select the options that you want. For example, you can select whether asynchronous methods are generated for the WCF client or disable the generation of a configuration file.
      
      
   3. Under Serializer select the serializer that should be used.
      
      
   The following figure shows the Advanced Options box with the default selections (Auto is selected for the serializer and no other options are selected).
   
   
   
   
   The options that you can configure in the Advanced Options box are equivalent to some of the options available when you use the ServiceModel Metadata Utility Tool (svcutil.exe). For more information about these options, see "ServiceModel Metadata Utility Tool (Svcutil.exe)" at http://go.microsoft.com/fwlink/?LinkId=99821.
   
5. Click OK. The Add Adapter Service Reference Plug-in saves the WCF client class (or WCF service interface) and helper code for the operations and categories that you have selected in your project directory. By default, a configuration file is also saved. Slightly different files are generated for inbound and outbound operations; for more information, see Generating a WCF Client or a WCF Service Contract for SAP Artifacts.