BizTalk Server 2010 : Installation of WCF SAP Adapter (part 3) - IDOC schema generation

We are now in familiar territory having used this wizard . This time around we want to select the sapBinding from the Select a binding dropdown.

We now need to configure a URI and can do so by clicking the Configure button. The first area that we need to address is the Security tab. Within this tab, we have a few different options when it comes to Client credential type:

• None

• Windows

• Username

• Certificate&;

I am going to go out on a limb and suggest that we will never run into a situation where we don't have to provide credentials so we will not be using None. The SAP system that is being used for this walkthrough does not reside on the Windows platform so that is not an option. If your SAP system supports Windows Authentication then using this type of authentication is worth considering. There are no specific requirements around proving our identity so Certificate is not required. This leaves us with providing a standard Username and Password. Generally, these credentials are assigned by a SAP Security Administrator and sometimes a BASIS Administrator. These are the same type of credentials that users provide when accessing SAP through the SAP GUI except with additional privileges.

The next tab that we want to focus on is the URI Properties. The base properties that we need to populate include:

• Application Server Host

• System Number&;

• Client

The Application Server Host is the name of the physical SAP Application server, or more likely a virtual DNS alias. This value will most likely be unique across the various SAP landscapes, that is, DEVELOPMENT/TEST/PRODUCTION.

The System Number is a unique numerical identifier for a particular instance of SAP. Client, in this context, is used to separate data within an SAP system. For instance if you have subsidiaries sharing an SAP system, but want to have segregated data, then you could create multiple clients that will allow you to distinguish one company's data from another. If you are familiar with Dynamics CRM, Client would be the equivalent of an Organization. This number will most likely be the same across the various SAP landscapes but you may have multiple values in co-hosting situations. These are all values that you will most likely get from a BASIS Administrator.

The final tab that we need to be concerned with is the Binding Properties tab. Within this tab, we will specify some attributes related to how BizTalk will interact with SAP. It is important to note that many of these settings can be changed within the BizTalk Administration console when you are ready to configure your application. Within the next screenshot, we will concentrate on two particular properties:&;

• ReceiveTimeout — Probably one of the most important production properties to set. This property specifies the duration that BizTalk will wait for an inbound message before shutting down. The default value is 10 minutes which is hardly enough time. If we don't modify this setting, we may have some undesirable results in a Production environment when BizTalk stops listening for IDOCs once this threshold has been exceeded. The maximum value is 24.20:31:23.6470000 (24 days). To learn more about this property, please see the following blogpost: http://kentweare.blogspot.com/2010/03/biztalk-adapter-pack-sap-binding.html

• EnableBizTalkCompatibilityMode — Specifies whether the BizTalk Layered Channel Binding Element should be loaded which will allow BizTalk transactions to flow to SAP. This value should always be set to true when using the WCF-SAP Adapter in BizTalk.

There are some additional properties within the Binding Properties tab that are of interest to us:&;

• EnableSafeTyping — Not all SAP data types have .NET data type equivalents. By enabling safe typing, BizTalk will have "looser" requirements about types when trying to bind an SAP data type to a .NET data type. It is important to understand how this property may change the behavior of your app. If you are expecting a Date from SAP, it is quite possible that the data will be converted to a string when this property is set to True. Speaking from personal experience, I have not had to set this property to true when integrating with IDOCs but have had to change the property when calling RFCs and BAPIs.

• GenerateFlatFileCompatibleIDOC — This property specifies whether the <appinfo> node should include segment types, or segment definitions, for parsing flat file IDOCs. By setting the property to True, it does not mean that you have to use Flat Files in order to process the IDOCs. It is a good idea to leave this value set to true as it provides you flexibility in the future to use Flat File if so desired.

• ReceiveIDOCFormat — Previously with the SAP Adapters that were based upon the .NET Connector, you had to process the IDOC as a Flat File. This is no longer the case with the WCF version of the Adapter. We now have the opportunity to send and receive messages as XML without the use of Flat File Schemas and Pipelines. If we specify Typed then we will receive the message as an XML message. We also have the ability to specify String or RFC. If we want to use a Flat File Schema/Pipeline then we need to specify String. If we want to receive the IDOC as a WCF message with RFC parameters then we want to specify RFC. Do note that these properties can be modified when we configure our receive location inside of the BizTalk Administration console.&;

Now that we have our configuration set, click the OK button to return to the main wizard.

As long as we have configured the Wizard properly, we can now click the Connect button to establish a connection to SAP.

The next question that we need to ask ourselves is whether this is an Inbound or Outbound operation. It is important to remember the context in which this question is being asked. The question is being asked from a BizTalk perspective. Will this IDOC be an Outbound Operation from BizTalk or an Inbound Operation to BizTalk? Since we are sending an IDOC to SAP then we will want to specify a Client (Outbound operations).

If we wanted to receive an IDOC from SAP, we will want to specify Service (Inbound operations):

The next area to focus on is the Search in category function. In order for this function to work we need to specify the Select a category as we cannot search SAP's entire BAPI, IDOC, RFC, and TRFC catalogue. For the purpose of this demonstration, we will select IDOC.

Within this text box, we can provide wild card searches and then click on the green arrow to execute the search. In this case, we can provide the term CONF, which will search for Confirmation IDOCs.

We will see our results populated in the Available categories and operations: list. The particular IDOC that we are interested in is the CONF32 IDOC. Once we have this IDOC selected, we can click Add and then the IDOC will be added to the Added categories and operations: list box.

With the old, .NET Connector-based adapter one IDOC equaled one BizTalk XSD schema. This is no longer the case. The Consume Adapter Service Wizard will generate multiple schemas for each IDOC. The reason for this is the Wizard will create schemas for specific SAP types that then get imported into a Master, or Parent, Schema. If you have many IDOCs within your solution this can get very confusing unless you provide a Filename Prefix. If we provide a prefix, like CONF32, all schemas will start with this prefix, which will allow us to organize and differentiate our schemas.&;

Once we have provided this prefix, we can click the OK button and our IDOC schema will get generated.

While this method is convenient, it comes with some baggage. When you click the OK button, it will download every version of the IDOC from your SAP system. This may leave you with way more schemas than you are interested in and may also result in timeouts from the Consume Adapter Server Wizard as there is just too much data to retrieve.

Another option that we have is to browse the IDOC catalogue and find the exact version of the IDOC that we are interested in. As you can see by the following image, there are many different versions of the IDOC within our SAP systems. Select the version of the IDOC that you are interested in, click the Add button. Had we used the steps previously mentioned by downloading all versions, our BizTalk Solution would have become extremely bloated. By browsing to the exact version that we are interested in, we will only download that version and any supporting schemas that contain the complex types.&;&;

We now have an opportunity to provide a Filename Prefix. If we do not provide a Prefix, the wizard will provide a very generic filename that will not differentiate it from other SAP schemas. We should use a descriptive prefix so that we can easily differentiate this schema from other schemas that we will have in our solution. We can click the OK button to have the schemas added to our BizTalk solution.

We will now find that six artifacts have been added to our solution. The main schema that we are interested in is CONF32IDOCOperation.CONF32.700.3.Send.xsd. The remaining schemas are there to support sending the IDOC and we also have a binding file that contains the values that we used to configure the Consume Adapter Service Wizard.&;

The Consume Adapter Service Wizard allows us to generate a single IDOC schema or multiple IDOCs at the same time. When dealing with multiple schemas, we need to be careful that the IDOCs do not share underlying common types that could lead to compilation errors. In order to avoid these compile time errors, we can check the Generate unique schema types check box. By doing so we will increase the number of schemas that are added to our solution. The additional schemas will include unique namespaces, which allows us to avoid the compile time errors.&;