WCF LOB Adapter SDK and BizTalk Adapter Pack : SAP

SAP Adapter – No “BAPI” node in the Metadata Search/Browse hierarchy when creating an “Inbound” contract?

mdoctor — Thu, 02 Oct 2008 04:50:08 GMT

A question which has popped up quite a few times over the last couple of weeks – “For an outbound contract, I see RFC, TRFC, IDOC and BAPI nodes in the UI. However, for an inbound contract, the BAPI node is missing. Why?”

Firstly, I’m going to explain what each of the four nodes you see really translate to within the adapter, and how they are “transported” to SAP.

The adapter communicates with SAP using the RFC protocol (it uses the RFC SDK for this purpose – which is written in C). RFC stands for “Remote Function Call” – a mechanism for calling Function Modules (functions) on SAP from external systems (you can also have functions defined on SAP which are not enabled for remote access). Using the RFC SDK, an external client can either invoke a RFC on SAP (outbound calls), or listen for incoming function calls (inbound).

The RFC and TRFC nodes you see in the metadata UI, are the only *pure* manifestations of this in the adapter.

Under the RFC node, we display all the function modules (which have been configured on SAP to allow them to be called from an external client). Invoking an operation under this node – the adapter just turns around and invokes that same operation on SAP.

The same functions also appear under the TRFC node. TRFC stands for “Transactional Remote Function Call”, though it is not really transactional. When you invoke an operation which appeared under the TRFC node (the Action is different for the same function under the RFC and TRFC nodes), the adapter when invoking the function on SAP, associates an identifier with the call. the SAP server makes a note of this identifier, and maps it to the execution status of that function. If, (suppose), the SAP server went down before completion of the function execution, the client can, at a later point, re-execute that call with the same identifier. SAP will realize that this call hasn’t been made before, and will attempt to re-execute the function. On the other hand, if SAP had successfully completed the call earlier, but if the client went down before it could process the response (or a network failure occurred before it could receive the response), the client can, at a later point, re-execute that call with the same identifier. SAP will know that an earlier call with the same identifier already completed successfully earlier, and will not execute it again, but will just send a response back to the client. The client, when it gets back a response (either on the first or later retries) should then clean up its own state with respect to the identifier, and also instruct SAP to do the same (via a RFC SDK API call, which the adapter exposes as an operation named “RfcConfirmTransID”). Once this cleanup/confirmation happens, this identifier is “forgotten”, and the next time this identifier is seen, it is assumed to be a brand new identifier / operation call. NOTE that in a TRFC call, SAP does not return any output values – hence the difference in the operation signatures when you compare them for the same RFC under the RFC node compared to the TRFC node.

What about the operations under the IDOC node? Sending IDOCs to SAP requires the client (the adapter) to execute special RFCs named IDOC_INBOUND_ASYNCHRONOUS / INBOUND_IDOC_PROCESS (depending on the version) on SAP. Receiving IDOCs from SAP requires the external application (now acting as the server) to be able to handle incoming calls to the same two functions. Operations under the IDOC node in the adapter are hence “dummy” operations which the adapter exposes – the adapter gets metadata for all available IDOCs on the SAP system, and exposes “Send” and “Receive” calls with different complex parameters based on the IDOC you want to work with. At runtime, for outbound calls, the adapter takes the individual pieces of data and converts them to the format which the above mentioned two RFCs require. For inbound calls, it splits/parses the data which it received from SAP as incoming parameter values to the above two RFCs, looks at the data to figure out which IDOC is being transmitted, gets metadata for that IDOC, and then re-formats the data to fit that metadata.

Note – for inbound IDOC calls, the adapter exposes a property named ReceiveIdocFormat (which is an enumeration of type IdocReceiveFormat). One of the values in this enumeration is “Rfc” – if you choose this, then, for incoming IDOCs, the adapter won’t peek at the data to figure out which IDOC it is and re-format it to fir the “Receive” operation – instead, it will just expose it as a RFC call to the servicehost – as a call to IDOC_INBOUND_ASYNCHRONOUS / INBOUND_IDOC_PROCESS. Well, actually, it will expose it as a TRFC call (i.e. the WCF message will have the TRFC action) since when SAP sends IDOCs to an external application, it usually does that using transactional semantics – at least SAP’s mechanism of transactions. (Note - the default value of the property/enumeration is “Typed”).

Lastly, BAPIs. SAP allows you to create Business Objects, and with each object, associate methods, events, attributes, etc – its version of OOP. In the current SAP architecture, methods on business objects are just RFCs. Hence, at design time, the adapter looks up the Business Object Repository (BOR), and determines the objects present on SAP. For each object, it figures out what methods were defined for it, and what the actual implementation is – that is, what is the actual RFC to which it maps. The adapter then shows the friendly names of the operations in the UI (since it has that information when it looked up the BOR), but in the Action , it actually uses the RFC name – since at runtime, what it really needs to do is just execute the corresponding RFC.

And now, coming to the question which this post was meant to answer – why is there no BAPI node in the UI for an inbound contract? When the adapter receives an incoming call from SAP, all it has is the function name – since after all, as you can see above, everything just involves execution of an RFC – for both outbound and inbound calls. If SAP sent along a “transactional” identifier with the function invocation, the adapter formats the incoming message (which it gives to the WCF service / BizTalk Receive Location) as a TRFC call. If the function which SAP invoked was named IDOC_INBOUND_ASYNCHRONOUS / INBOUND_IDOC_PROCESS, the adapter recognizes these functions as “special”, and peeks at the data to determine the IDOC being transmitted, and formats the WCF message as a call to “Receive” with the appropriate action (which contains the IDOC type, among other things). Else, the incoming WCF message is now just formatted as a call to an RFC (with the Action containing the RFC name).

The adapter can’t format the WCF message using an Action corresponding to a specific Business Object (i.e., corresponding to an operation that would live under the BAPI node), since strictly speaking, there is no mapping from the RFC name to the Business Object type which implements it. The BAPI node in the UI for outbound contracts was really more of a convenience mechanism – so that a user can navigate the business object hierarchy to find the function of interest. All functions under the BAPI node also appear under the RFC and TRFC nodes too. For inbound calls, if you’re interested in listening for an incoming function like BAPI_SALESORDER_CREATE (which is most probably a function with the friendly name “Create” defined on the “SalesOrder” business object), just search for the RFC named BAPI_SALESORDER_CREATE under the RFC node (or under the TRFC node if you know that SAP is going to execute this “transactionally”). NOTE that in the most common case, only the “special” IDOC RFCs are invoked transactionally by SAP on an external application, so for all other incoming RFC calls, you should just add the operation under the RFC node to your Service Contract.

The “DataTypesBehavior” binding property in the SAP Adapter

mdoctor — Wed, 13 Aug 2008 11:38:00 GMT

Firstly, if you haven’t already seen it, have a look at the post describing the EnableSafeTyping binding property - http://blogs.msdn.com/adapters/archive/2007/11/24/the-enablesafetyping-binding-property.aspx.

Since the Adapter Pack V1 released, we have had requests from users, wherein, they want to expose the Date (DATS) and Time (TIMS) data types as a .NET DateTime (strong typing), but yet want the adapter to be able to handle common SAP values such as 00000000 for DATS (which in SAP would mean a MINVALUE or NULL for the Date field). Besides, we already know that SAP doesn’t validate the data in DATS, TIMS and NUMC fields, so you might end up receiving “invalid” data from a SAP RFC, but you yet want the strong typing in your client code.

As a result, we’ve added a new binding property named “DataTypesBehavior” in the SAP adapter. This property is actually a “complex” property, containing 12 sub-properties. I’ll first list the names of the sub-properties.

DateTimeMaxToDats
DateTimeMinToDats
DateTimeMaxToTims
DateTimeMinToTims
DatsMaxToDateTime
DatsMinToDateTime
TimsMaxToDateTime
DateTimeNullToDats
DateTimeNullToTims
InvalidDatsToDateTime
InvalidNumcToInt
InvalidTimsToDateTime
EmptyDatsToDateTime

I’ll explain just a few of the above; you should then be able to figure out what the rest mean.

DateTimeMaxToDats – this property controls the behavior when converting DateTimeMax (the .NET DateTime.MaxValue value) “To” Dats (the SAP DATS value). The .NET DateTime.MaxValue can only be present in the request message. The adapter needs to convert this to a DATS value when sending it to SAP. Therefore, this property controls the behavior of how the adapter parses the request message.
DatsMaxToDateTime – this property controls the behavior when converting DatsMax (the SAP DATS MaxValue, which is 99999999) “To” DateTime. DATS values can only be sent from SAP right? And, only a client consuming the adapter can understand .NET DateTime, right? Hence, this property controls the behavior of the adapter, when it receives the DATS value from SAP (as the response to a RFC invocation), and when the adapter is converting this value to XML in order to give the response to the client.

Additional information for each property, including details on the values which need to be specified for each property, can be obtained by peeking through the attached .txt file – it contains the comments present in the source code of the adapter for these individual properties.

NOTE – this binding property is present in the SAP Adapter in the Adapter Pack v2. For the Adapter Pack v1, there is a hotfix available (KB # 954539) – your Microsoft support contact should be able to obtain it for you.

Exception: Loading property information list by namespace failed or property not found in the list

mdoctor — Mon, 04 Feb 2008 18:00:00 GMT

When using the SAP Adapter, while receiving an IDoc, you might see the error message "Loading property information list by namespace failed or property not found in the list" in the event log.

Cause: The SAP adapter is promoting the IDoc control record fields in/to the BizTalk message context. However, there is no schema deployed for these context properties.

Resolution: Add the "Microsoft.Adapters.SAP.BizTalkPropertySchema" dll to the Resources section of your BizTalk application.

The post http://blogs.msdn.com/adapters/archive/2007/10/12/enablebiztalklayeredchannel-what-does-this-binding-property-do-part-1.aspx talks about this in a little more detail (of course - EnableBizTalkLayeredChannel was renamed to EnableBizTalkCompatibilityMode from the RC build onwards).

TimeoutException(s), timeout related ArgumentOutOfRangeException(s) thrown from the SAP Adapter

mdoctor — Mon, 28 Jan 2008 08:56:00 GMT

You must have read in the documentation that the SAP adapter does not support/honour the timeout values specified on the binding (sendTimeout, openTimeout, etc). However, at times you might yet receive timeout related exceptions from the adapter. Why?

The SAP Adapter uses the SAP RFC SDK Library to communicate with SAP. The API calls in this SDK don't support timeouts, and hence, when making a call using this API, the adapter is helpless if an API invocation ends up taking a really long time. However, in most of the code paths within the adapter, the adapter performs a bunch of steps - some of them within the adapter, while the rest involving API invocations in the RFC SDK.

Now, as mentioned above, the timeout is not honored during a single API invocation. However, in between API calls, if the adapter determines that a timeout has occurred, then it does throw a TimeoutException.

But why does it throw an ArgumentOutOfRangeException at times? That is a side effect of the internal implementation; however, the error message might be something to the tune of "Timeout must be greater than or equal to TimeSpan.Zero", indicating a timeout related exception.

If you find such exceptions common in your environment, you should increase the sendTimeout value on the SAPBinding (the default is 1 minute, which might be insufficient when sending IDocs or executing BAPIs with a large amount of data, for example).

Making Microsoft BizTalk Adapter v2.0 for mySAP Business Suite projects work with WCF SAP Adapter #2

manasg — Thu, 17 Jan 2008 19:36:00 GMT

This is in continuation to the previous post, where we discussed the differences in the XML structure used by the old SAP adapter and the new WCF SAP Adapter. In a transactional scenario, the old adapter uses the context property named 'ConnectionType'. This context property is present in the new adapter too, with a few changes, which we illustrate here.

The corresponding values for the context property ‘ConnectionType’ in the old and the new adapters are as follows:

1. OPENREUSE: Open a new connection for reuse. Equivalent in new adapter is 'OPEN'
2. REUSECONNECTION: Reuse an existing cached connection. Equivalent in new adapter is 'REUSE'.
3. REUSECLOSECONNECTION: Reuse open connection and then close it. Equivalent in new adapter is 'CLOSE'.

In addition to the above, the new adapter provides an additional value 'ABORT', which closes the connection after the current call is made despite of any exceptions that may occur. This value does not have an equivalent in the old adapter. The WCF SAP Adapter documentation discusses this context property in more detail.

The pipeline component included with the preceding post (here) has now been updated to map the old adapter's context property ‘ConnectionType’ to that of the new adapter - in addition to the XML mapping it already did - making transition from the old adapter to the new one an easy process.

Making Microsoft BizTalk Adapter v2.0 for mySAP Business Suite projects work with WCF SAP Adapter

manasg — Mon, 14 Jan 2008 10:47:00 GMT

We have written a custom pipeline component (code and sample projects using this pipeline component are attached) that you can use to make your BizTalk orchestrations calling RFCs and BAPIs written with Microsoft BizTalk Adapter v2.0 for mySAP Business Suite work with the new WCF SAP Adapter. All you need to do is to use custom send and receive pipelines that replace the usual XMLTransmit and XMLReceive pipelines, and plug in the new adapter in place of the old one. No other changes. The source code of the pipeline component is included so you can make changes to it if you want to.

The custom pipeline component performs the following transformations:

1. Old adapter Request XML to New adapter request XML

2. New adapter Response XML to Old adapter response XML

The result? Your orchestration and messages do not have to change at all!

The major differences between the old and new adapters’ XML structure for RFCs are as follows:

1. Namespaces:

· Old Adapter : Root element is in the namespace http://schemas.microsoft.com/BizTalk/2003 while other elements have an empty namespace

· New Adapter: Elements with depth 0 and 1 are in the namespace http://Microsoft.LobServices.Sap/2007/03/Rfc/ while elements with depth 2 and 3 are in the namespace http://Microsoft.LobServices.Sap/2007/03/Types/Rfc/

2. Name of the Root Node:

· Old Adapter: The root node is named {RFC_NAME}_Request for the request XML, and {RFC_NAME}_Response for response XML

· New Adapter: The root node is named {RFC_NAME} for the request XML, and {RFC_NAME}Response for the response XML

3. Array of Complex types:

· Old Adapter : There are multiple nodes of with the name of the parameter, each of which contain one instance of the structure as the child nodes. The name of the complex type does not appear in the XML. For example:

<ComplexParameterName>
<Element1>Value1</Element1>
<Element2>Value2</Element2>

</ComplexParameterName>
          <ComplexParameterName>
                   <Element1>Value3</Element1>
                   <Element2>Value4</Element2>
          </ComplexParameterName>
           .
              .

· New Adapter : There is only one node with the name of the parameter, which contains multiple child nodes whose name is set to the name of the complex type , each containing one instance of the structure. For example:

.
.
<ComplexParameterName>
          <ComplexTypeName>
                   <Element1>Value1</Element1>
                   <Element2>Value2</Element2>
          </ComplexTypeName>
          <ComplexTypeName>
                   <Element1>Value3</Element1>
                   <Element2>Value4</Element2>
          </ComplexTypeName>
</ComplexParameterName>
.
.

4. Tables Returned:

· Old Adapter: All tables that have any output value are returned.

· New Adapter: Only the tables that were present in the request XML are present in the response XML.

How does the custom component work?

Changing Namespaces and Name of the root node is straightforward. To figure out the name of the ComplexParameter’s type, we use reflection on the RFC specific dll created by the old adapter, and expect it to be present at “C:\Program Files\Microsoft BizTalk Adapter v2.0 for mySAP Business Suite\Bin\{RFC_Name}.dll” (The old adapter creates this Dll automatically when you generate the RFC Schema). To make sure the tables returned are same as what the old adapter would have returned, we append empty nodes for all the table parameters that were not included in the request XML by using the schema in your project. That way, the response XML contains all tables. Now we simply eliminate the tables that are empty to get the response similar to that of the older adapter.

Using the custom pipeline component

1. Build the custom pipeline component or use the dll included

2. Copy the assembly to “C:\Program Files\Microsoft BizTalk Server 2006\Pipeline Components” and also add it to the GAC

3. In your existing BizTalk project, create new send and receive pipelines and include the custom component in encode and decode stages. (you’ll need to add reference to the custom pipeline assembly and add it to the pipeline toolbox)

4. Build and deploy

5. Go to the BizTalk administration console and restart the host instance.

6. For the ports that send or receive to/from SAP, select the new SAP adapter and configure it as described in the documentation. Set the ‘enableSafeTyping’ binding property to true

7. Use the custom pipeline you created with the ports that talk to SAP

8. Start!

A few sample BizTalk projects that use schemas generated with the old adapter and include custom pipelines are included in the attachment. Sample configuration bindings are also included. To build the samples, you should change the name of the SQL server in project deployment properties.

Update: The attached Pipeline component has been updated to transform the context property 'ConnectionType' too. See this post for more info.

"When I Execute BAPIs, I don't get back any data". Help!

mdoctor — Thu, 10 Jan 2008 03:44:00 GMT

The two most common questions I get from customers using the SAPBinding:

I execute a BAPI (via the generated WCF proxy) from a .NET application. However, after the call returns, I see that many table parameters are null.
I am trying to execute a BAPI with some input values. If I use those same values in the SAP GUI, relevant data is returned. However, when I call the method via a WCF proxy from a .NET application, I get the message "No data found" or something similar.

For the first issue: consider a scenario where you want to call a BAPI, which returns 25 tables. Each table on the average, (assume) contains 100 rows relevant to the input you returned. That's a lot of data. You might be interested in just the rows from one table, and don't want the extra payload slowing things down. Therefore, we added an optimization in the WCF SAP Adapter - we only return those tables, which you specifically requested. You will notice that table parameters are ref / InOut parameters in the generated proxy. If you pass in null, the interpretation is that you are not interested, and hence the adapter will return null for that table. Therefore, if you want rows for a particular table, pass in an empty table (i.e., your array parameter should not be null, but instead new array[0]).

If you're sending messages using the channel model instead of using a .NET proxy (for example, in BizTalk) - if the table node is missing from the input XML, we interpret that as if you're not interested in that table. If you do want the rows from that table in the response message, you should pass in the node in the input XML (0 rows, just the starting and ending parameter tag).

For the second issue: SAP has a concept called "conversion exit" - when you enter values in the SAP GUI, and then press F8 to execute the RFC, SAP behind the scenes converts your value (which you entered in the UI) to an appropriate format before executing the RFC. For example, lets take the RFC_CUSTOMER_GET RFC. For this example, enter * in the NAME1 field (leave the KUNNR field blank) and execute the RFC, to get back a list of all customers in SAP. Choose any customer, whose KUNNR is less than 10 digits (assume the KUNNR for a customer is "12"). Now, go back to the RFC_CUSTOMER_GET execution screen, leave the NAME1 field blank, and enter "12" in the KUNNR field. Execute the RFC. You should get back the details of the one customer (the customer with KUNNR = "12").
Now, from the WCF proxy generated for RFC_CUSTOMER_GET, execute it with the same input (i.e., NAME1 is null (since we don't want to send any value for NAME1 to SAP), but KUNNR is "12"). You will get back an error saying "NO_RECORD_FOUND". Why? Because, there really is no customer with KUNNR="12". When you executed the RFC from the SAP GUI, the conversion exit kicked in, which (behind the scenes) converted "12" to "0000000012" and then searched for the relevant data. It is not possible to apply such conversion exits from external programs (your .NET application using the SAP Adapter, for example), and hence you need to know the format in which the data is stored in SAP. If you re-run your .NET code passing in "0000000012" as the KUNNR in RFC_CUSTOMER_GET, (and provided you passed in an empty table (see issue #1 above) for the CUSTOMER_T table), you should now successfully get back 1 row for that customer.

Performance Comparison - Sending IDocs using SAP.NET Connector versus the SAPBinding

mdoctor — Sat, 22 Dec 2007 10:47:00 GMT

I'm not going to give you numbers - instead, I'll give you an easy way to generate the numbers in your environment.

Attached is a VS 2005 Solution which you can use for testing. Have a look in the Program.cs file. The code is pretty self-explanatory. You need to give a list of paths to the IDocs you want to test with, and you need to enter the SAP Server details. The IDocs have to be in Flat-File format - the first line representing the control record, and then each subsequent line representing a data record.

You need to add references to Microsoft.Adapters.SAP.dll, Microsoft.ServiceModel.Channels.dll and System.ServiceModel.dll (for the SAPBinding); and SAP.Connector.dll (the SAP .NET Connector).

You also need to have both RFC SDK Libraries present - Unicode + NonUnicode. The SAPBinding uses the Unicode Library, while the SAP.Connector uses the NonUnicode Library.

Once you've carried out the above two steps (i.e., corrected the paths in the code to point to your IDocs, and added references to the above mentioned DLLs), compile and run the program. The latencies for sending IDocs via the .NET Connector, and the SAPBinding, are displayed.

Why don’t I get exceptions when something unexpected happens in inbound scenarios in SAP Adapter?

manasg — Fri, 21 Dec 2007 08:34:00 GMT

You might have observed that in outbound scenarios, for example while calling an RFC, if something goes wrong, an exception is thrown to the user. This does not happen in the same manner for inbound scenarios, for example when receiving an RFC or an iDoc. Let us see what this difference is.

When an outbound call is made to SAP, the (simplified) scenario looks like this:

User code issues a request, and the response is sent by SAP. Any exceptions that occur in SAP or the adapter are propagated to the user. However, the inbound scenario looks like this:

The User code sends response to SAP’s request. All exceptions are thrown to SAP except the ones that occur while the user code reads data – after all SAP is the party that issues the request in this case. This is the reason why we don’t see exceptions when something goes wrong in inbound scenarios.

Now, is there a way to see the exceptions being passed to SAP?

Yes! Tracing is the answer. We recommend that you enable Error and Warning level tracing for adapters. The exceptions that are thrown to SAP are also traced and will find a place in the trace log if tracing is enabled. However, trace logs tend to grow huge – and picking out new entries manually can be daunting. Using the System.Diagnostics.EventLogTraceListner class instead of the XMLWriterTraceListener class, you can redirect your traces to the event viewer – the one stop solution to monitor your applications and services.

If you’re working with the WCF service model, add the following to the configuration section of your app.config file. If you’re working with Biztalk applications, add the following to the configuration section of your BizTalk configuration file, BTSNTvc.exe.config which is present under <system drive>:\Program Files\Microsoft BizTalk Server 2006:

<system.diagnostics>

</listeners>

</source>

</listeners>

</source>

</sources>

</sharedListeners>

</system.diagnostics>

This will enable Warning level tracing (Errors + Warnings). Replace APPLICATION_NAME with the name of your application as you want it to appear in the event viewer. Now you can see the errors and warnings - even the ones that were thrown to SAP - in the event viewer. Neat!

"Receiving IDocs from SAP using the SAPBinding requires higher SAP user privilege as compared to the older mySAP Adapter". Really??

mdoctor — Fri, 14 Dec 2007 18:03:00 GMT

Firstly, let me explain the common customer scenario using the old (mySAP 2.0) Adapter (NOTE - points in red and green below highlight the similarities/differences in configuration):

The user, at design time, uses a high privilege account (let's call it account A), to obtain the schemas for an IDoc. These schemas are deployed in a BizTalk project.
In the BizTalk project, the user adds the FlatFile Pipeline component (because the user wants the IDoc which SAP sends out as a strongly typed XML in his BizTalk orchestration).
At runtime, the adapter is deployed using a SAP account which has low privileges (account B).
At runtime, the adapter receives an IDoc from SAP as a flat file.
The adapter hands this flat file out to the FlatFile Pipeline component.
The FlatFile pipeline component, using the deployed schemas, converts this FlatFile to a XML document, and submits that to BizTalk.

Now, here's what the user would do when using the new WCF SAPBinding.

The user, at design time, uses a high privilege account (let's call it account A), to obtain the schemas for an IDoc. These schemas are deployed in a BizTalk project.
In the runtime configuration of the SAPBinding, the user sets the ReceiveIdocFormat property to Typed, since he wants the IDoc which SAP sends out as a strongly typed XML in his BizTalk orchestration).
At runtime, the adapter is deployed using a SAP account which has low privileges (account B).
At runtime, the adapter receives an IDoc from SAP as a flat file.
The adapter makes an outbound call to the RFC IDOCTYPE_READ_COMPLETE, in order to obtain the metadata for the IDOCTYP which was received (e.g., ORDERS05, MATMAS05, etc).
This call (to IDOCTYPE_READ_COMPLETE) fails, since the SAP account B does not have sufficient permission.
An exception is thrown.

Bummer!

As you can see, the SAPBinding requires a more privileged account, since it is doing something extra as compared to the older adapter.You can get it to work with a low privileged account, by making it do the same thing as the older adapter. Here's how:

The user, at design time, uses a high privilege account (account A), to obtain the schemas for an IDoc. These schemas are deployed in a BizTalk project.
In the runtime configuration of the SAPBinding, the user sets the ReceiveIdocFormat property to String, so that the adapter gives out the Idoc as a ReceiveIdoc operation (FlatFile format).
In the runtime configuration of the SAPBinding, the user follows the instructions in the post http://blogs.msdn.com/adapters/archive/2007/10/05/receiving-idocs-getting-the-raw-idoc-data.aspx (note - hyperlink opens a new browser window), so that the FlatFile data is pulled out of the loosely-typed ReceiveIdoc() xml.
In the BizTalk project, the user adds the FlatFile Pipeline component (because the user wants the IDoc which SAP sends out as a strongly typed XML in his BizTalk orchestration).
At runtime, the adapter is deployed using a SAP account which has low privileges (account B).
At runtime, the adapter receives an IDoc from SAP, and hands it out as a ReceiveIdoc XML. (NOTE - Adapter makes no attempt to retrieve IDoc metadata via a call to IDOCTYPE_READ_COMPLETE, since the ReceiveIdocFormat was set to String)
The WCF-Adapter, (assuming the instructions in the blog post mentioned above were correctly followed), extracts the IDoc data from within the ReceiveIdoc XML node, and hands the FlatFile data out to the FlatFile Pipeline component.
The FlatFile pipeline component, using the deployed schemas, converts this FlatFile to a XML document, and submits that to BizTalk.

Yay! Its working now!

However, note that in configurations where you set ReceiveIdocFormat to String and then use the FlatFile Pipeline component to convert the FlatFile IDoc to a strongly typed XML, such configurations won't work when you are receiving IDocs containing multi-byte characters, from non-Unicode systems. (Why? That's a different (and really long) blog post altogether. It has to do with limitations in the RFC SDK Unicode Library.)

Hence, we recommend, that as far as possible, you set ReceiveIdocFormat to Typed in your runtime configuration, which makes the Adapter hand out the IDoc as a strongly-typed XML, without requiring the FlatFile Pipeline Component.

As for the extra permissions required in order to call IDOCTYPE_READ_COMPLETE, the authorization object required is:

Authorisation object S_IDOCDEFT. Fields:
EDI_TCD, value 'WE30'
ACTVT, value - 03
EDI_DOC, value * (or the specific IDOCTYP)
EDI_CIM, value * (or the specific Extension)

The EnableSafeTyping Binding Property

mdoctor — Sat, 24 Nov 2007 08:38:00 GMT

In the November CTP of the Adapter Pack V1, a new binding property has been added to the SAPBinding - "EnableSafeTyping" (a boolean)

When this property is true, DATS, TIMS and NUMC fields are exposed as Strings, and any value can be passed back and forth between the client and the SAP Server.

For DATS, you (ideally) should pass DATE values in the format YYYYMMDD in order for SAP to interpret it correctly.
For TIMS, it (ideally) should be HHMMSS (24 hour format).
For NUMC, you (ideally) should pass in a numeric value ("12345" for example).

The adapter will not validate the values you pass in (or which SAP passes out).

When this property is false, then

for DATS, only valid DateTime objects can be passed back and forth. (If SAP returns a DATS value of 00000000, or 99999999, an exception will be thrown by the adapter).
For TIMS, only valid DateTime objects can be passed back and forth.
For NUMC, you must pass in a numeric value (positive integer), and the assumption is that SAP will do the same when sending back a response. An exception will be thrown if the value is not valid.

NOTE - This is different from the Beta2 behavior, wherein, a DateTime value of 9999-12-31 was sent to SAP as 99999999 (and vice versa) and a DateTime value of 0001-01-01 was sent to SAP as 00000000 (and vice versa).

For more information on how the DateTime values are treated by the adapter, have a look at http://blogs.msdn.com/adapters/archive/2007/10/05/date-time-handling-in-the-microsoft-biztalk-net-sap-adapter-wcf.aspx

For the SAP ADO Provider, for both EXEC and SELECT calls, you need to use the 'DisableDataValidation' option to achieve the same functionality. (http://blogs.msdn.com/adapters/archive/2007/10/15/sap-dats-column-containing-the-value-a-b-c-d-problem-when-sap-ado-is-used.aspx).

IdocProxy.SendIdoc(string idocData) call - doesnt this load the entire IDoc data in memory?

mdoctor — Sat, 03 Nov 2007 04:19:00 GMT

The SAP Adapter exposes a "generic" Send call which can be used to send any Idoc. In the Metadata SearchBrowse UI, this operation is visible as "SendIdoc" under the Idoc node.

The signature for this operation is

SendIdoc(string idocData, Guid guid)

The "guid" parameter is used if you want to use a TID when sending the Idoc to SAP (the adapter will map the guid to a TID). Assume that you dont want the guid. However, the idocData parameter is exposed as a string. This data is the flat-file idoc data. If you want to send a 100 mb idoc, and you use this proxy call, the entire 100mb data is going to get loaded into the string parameter. This is horrible!

Well, the way out would be to not use the proxy interface (the IdocProxy.SendIdoc() call), but instead program directly to the IOutputChannel or IRequestChannel interface, to send a WCF Message across to the adapter.

However, the way you create this Message can have an impact on the memory consumption. You can create a Message using a XmlReader, XmlDictionaryReader, or a BodyWriter. The adapter implementation is such that it consumes the Message using a XmlDictionaryWriter. Due to internal .NET implementation, if you create your message using a XmlReader or XmlDictionaryReader, and since the Adapter writes the message to a XmlDictionaryWriter, the entire idoc data will yet get loaded into memory (since the entire idoc data is present within a single Xml node). The way to get around this is for you to create your input message using a BodyWriter.

Attached is a sample which sends an idoc to the SAP Adapter by sending a WCF Message object, with this WCF Message object being created from the idoc data using a BodyWriter.

Debugging SAP RFCs when using the SAP Adapter / SAP ADO.NET Provider

mdoctor — Mon, 29 Oct 2007 19:55:00 GMT

The RFC SDK supports the ABAP_DEBUG option, which allows you to break into the RFC ABAP code when invoking an RFC from your application. The SAP Adapter and the SAP ADO.NET Provider also expose this setting.

The main advantage of this - consider this scenario - you invoke an RFC using the SAP Adapter, pass in some input parameters, the call returns and you get the output values, and to your horror, find that the values are unexpected! Using the Abap Debug option, you can break into the Abap code, verify that the input values received by the RFC are the actual values you passed in to the adapter, and that the values being returned by the RFC are the same which the adapter gives you back in the response.

Note that in order to be able to break into the Abap code, you need to install the SAP GUI on your client machine (because the SAP GUI will act as the "IDE" displaying the ABAP code).

Another thing, when using the Abap Debug option, you might invoke an RFC named RFC_FOO, but when the SAP GUI starts up and breaks into ABAP code, you might find yourself in another RFC. The reason being - the adapter internally makes a few extra RFC calls to retrieve metadata. Hence, before your actual RFC_FOO call is invoked, the adapter might have made calls to RFCs such as RFC_GET_FUNCTION_INTERFACE, RFC_GET_STRUCTURE_DEFINITION, IDOC_RECORD_READ, IDOCTYPE_READ_COMPLETE, etc. Return from those functions in the debugger, and in a short while you should find yourself in the RFC of interest in the debugger.

The URI for the adapter when using the Abap Debug option is of the form:

sap://Client=800;Lang=EN@A/SAPSERVER/00?AbapDebug=True

The connection string when using the Abap Debug option from the ADO Provider is of the form:

ASHOST=SAPSERVER;CLIENT=800;LANG=EN;USER=blah;PASSWORD=blah;ABAPDEBUG=True;

Downloading the SAP SNC Libraries

mdoctor — Wed, 24 Oct 2007 12:46:00 GMT

The SAP Adapter supports SAP SNC Authentication. For this, you need to have the SNC libraries present. You can download them by following the steps outlined below:

Log in to SAP Service Marketplace.
Under the SAP Support Portal section, click on the SAP Notes Search quick link.
In the page that opens up, somewhere between the top and middle portion of the page on the right side, there is a text box where you can enter a SAP Note Number. Enter 352295 and click the double-arrowed button to search.
The SAP Note information is displayed.

The SAP Note contains information on SNC. At the bottom of the page, links are present for downloading the 32 and/or 64 bit versions of the SNC Libraries.

FYI - Information on configuring the SAP server for SNC can be obtained here: https://www.sdn.sap.com/irj/sdn/go/portal/prtroot/docs/library/uuid/ac81c690-0201-0010-c4b4-c72618f3590d

FYI - Information on configuring the SAPBinding for SNC can be obtained here: http://msdn.microsoft.com/en-us/library/cc185541.aspx

Getting LOB metadata from SAP, OracleDB and Siebel adapter using svcutil

Jayanthi S — Tue, 23 Oct 2007 11:56:00 GMT

The WCF based adapters that ship in the Biztalk Adapter Pack are WCF bindings. The svcutil tool can be used to get metadata for a LOB method using these bindings. The scheme in the URI determines which adapter binding is loaded by svcutil. However when using the svcutil tool, there is no easy way to specify the LOB credentials that should be used to get metadata from the LOB. One way to specify the LOB credentials to our adapters is to set it in the URI. However, by default (for security reasons) the adapters do not accept credentials in the URI.

To get around this, you need to set the binding property acceptCredentialsInUri to true and then specify the LOB credentials in the URI. To be able to set binding properties or other custom settings when using svcutil.exe, you should use the svcutil.exe.config file. This article describes how to use it.

Attached is a sample svcutil.exe.config which has the endpoint and binding configurations for all the three adapter bindings. Place this in the same folder as svcutil.exe.

The following are sample command lines to use to get metadata from our adapters.

SvcUtil.exe "sap://user=youruser;passwd=yourpassword;Client=800;lang=EN@A/adapsap47/00?op=http://Microsoft.LobServices.Sap/2007/03/Rfc/RFC_GET_FUNCTION_INTERFACE"

SvcUtil.exe "oracledb://User=MYUSER;Password=MYPASSWORD@ADAPTER/?op=http://Microsoft.LobServices.OracleDB/2007/03/SCOTT/Table/AEMP/Insert"

SvcUtil.exe "siebel://Username=MYUSER;Password=MYPASSWORD@mssebldemo:2321?SiebelObjectManager=SSEObjMgr_enu&SiebelEnterpriseServer=ent771&Language=enu&op=http://Microsoft.LobServices.Siebel/2007/03/BusinessObjects/Account/Agreement/Query"

Note the quotation mark around the URI. In the configuration for Siebel (in the attached config file) also note the idleConnectionTimeout without which it will take the default 1 minute for svcutil to terminate. Look for more details on the idleConnectionTimeout in a separate post on Siebel.

Note also that if you use the Add Adapter Service Reference tool (that gets installed with the WCF LOB Adapter SDK) to get metadata for a LOB method for use in a C# or VB project, the AcceptCredentialsInUri binding property will not be visible or settable. You can set the LOB credentials using the credentials tab in the tool.