integrating your business

In this post I will talk about setting up a trace for the WCF-Adapter. This post should be a good addition to some previous posts I made about the WCF-Adapter.

Communicating with SAP through WCF : Send and Receive Ports

Communicating with SAP through WCF : Generate SAP schemas

1.  Tracing within the Adapter

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>

    <sources>

      <source name="Microsoft.ServiceModel.Channels" switchValue="Warning">

        <listeners>

          <add name="eventlog" />

        </listeners>

      </source>

      <source name="Microsoft.Adapters.SAP" switchValue="Warning">

        <listeners>

          <add name="eventlog" />

        </listeners>

      </source>

    </sources>

    <sharedListeners>

      <add name="eventlog" type="System.Diagnostics.EventLogTraceListener" initializeData="APPLICATION_NAME"/>

      </sharedListeners>

    <trace autoflush="false" />

  </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.

If not possible to write to event log or if too bulky, then alternatively, you can put the following instead of the listeners “event log” if you want to log to a file. You will then need the tracing viewer (see below):

<add name="xml" type="System.Diagnostics.XmlWriterTraceListener"

   traceOutputOptions="LogicalOperationStack"

          initializeData="C:\log\WCF\AdapterTrace.svclog" />

ATTENTION: Trace files can become huge. Remember to stop tracing once issues have been solved.

2.  Tracing the Adapter and the LOB Application

To diagnose issues that you suspect are related to the LOB application, you must enable tracing for communication between the adapter and the LOB application. Adapters also depend on LOB tracing (client/server side) to access this information. The SAP adapter enables adapter clients to turn on tracing within the SAP system by specifying the "RfcSdkTrace" parameter in the connection URI. You must specify this parameter to enable the RFC SDK to trace information flow within the SAP system. For more information about the connection URI, see The SAP System Connection URI.

This parameter is specified in the SAP binding URI of the BizTalk WCF adapter:

Additionally, you can also create an RFC_TRACE environment variable that sets the level of tracing for the RFC SDK. RFC_TRACE is an environment variable defined by SAP and is used by the RFC SDK. If this variable is not defined or is set to 0, the RFC SDK tracing level is bare minimum. If the variable is set to 1 or 2, the tracing level is more detailed.

RFC_TRACE = 2
RFC_TRACE_DIR = C:\log\LOB

Note: Irrespective of whether the RFC_TRACE environment variable is set, the RFC SDK tracing is enabled only if setting the "RfcSdkTrace" parameter to true in the connection URI (see in STEP 2). The value of this environment variable solely governs the level of RFC SDK tracing. If RfcSdkTrace is set to true, the message traces between the adapter and the SAP system are copied to the “system32” folder on your computer. To save the RFC SDK traces to some other location, you can set the RFC_TRACE_DIR environment variable. For more information about these environment variables refer to the SAP documentation.

3.  Viewing the Traces

You can use the Windows Communication Foundation (WCF) Service Trace Viewer tool to view the traces. For more information about the tool, see "Using Service Trace Viewer for Viewing Correlated Traces and Troubles" at http://go.microsoft.com/fwlink/?LinkId=91243 .

Enjoy!

Glenn Colpaert 

A few weeks ago I had to create a flow that receives messages from SAP with a specific IDoc release number. The SAP system was a 620 release and the IDoc was 46C release.
So to start with, I generated the schema for the 46C release and deployed that on my BizTalk box.

When we sent an IDoc to BizTalk, we got following error :

The segment or group definition E2EDP01006 was not found in the IDoc metadata. The UniqueId of the IDoc type is: IDOCTYP/3/ORDERS05//620. For Receive operations, the SAP adapter does not support unreleased segments.

So this message stated that SAP was sending a 620 IDoc. After a discussion with an SAP developer, we found out that the DOCREL field in the EDI_DC40 header had the value 620 while we where expecting to receive 46C.

The way that the new SAP adapter works in BizTalk is that when he receives an IDoc from SAP, he will check all the segments that are sent to see if it is a valid IDoc. Since the segment E2EDP01006 is not present in IDoc release 620, this is a normal error. This validation occurs in the adapter, so even before the message reaches BizTalk. So even if you have the correct schema deployed (like in my case) you will still get the error.

While searching for a solution we found 3 ways to solve this.

1.  Always use the latest IDoc release

This is the most obvious one off course. Just ask an SAP developer to send the latest release of the IDoc to BizTalk and you will be able to receive it. (The latest release will be the same as the system release)

This is also the option we choose at the time. It was the fastest solution we could both support.
But we still spent a little bit time to investigate the other options.

2.    Receive “untyped” flat file IDocs.

This means that you need to generate the flat file schemas for the IDoc instead of the typed xml schema. You have to make sure that you set the GenerateFlatfileCompatibleIdocSchema field to true in the “Consume adapter service” window.(If you want to receive multiple IDocs via the same receive port, make sure you install the KB977528 hotfix)

This has the limitation that you need to use the flat file assembler in your receive pipeline. If you want to receive alot of different types of IDocs with the same receive pipeline, you will have to put a flat file disassembler in there for every IDoc type.

3.    Change the SAP output module

SAP has 2 ways of exchaning IDocs with other systems.

1. Application Link Enabling (ALE)

ALE was created to exhange IDocs between SAP R/3 systems and/or R/3 and external systems.

1. Electronic Data Interchange (EDI)

This interface is used to communicate with non R/3 systems.

Since BizTalk can act as an R/3 system, the standard way we received IDocs was via ALE. But when you use ALE, the DOCREL field will always contain the system release number.So if you use ALE as the output module, you can only receive the latest IDoc release know inside the system.The EDI interface works in a different way, that makes sure that the DOCREL field is filled in correctly. Since we already chose to go for the first solution, we did not test this at runtime.
But The SAP developer told us that this should do the trick as well.

Tim D'haeyer, CODit

In order to successfully setup communication with SAP. You have following configurations.
In terms of the SAP part you need to have following things on SAP side:

·         A SAP user with suitable access

·         A RFC connection (This will specify the ‘listening’ program running on BizTalk. (SAP transaction SM59)

·         A tRFC port which uses the RFC connection defined above. (SAP transaction WE21)

There is also some setup in terms of messages. Assignment of messages to receiving/sending partner…
But this would be down to the SAP team for doing this sort of implementation.

The most important thing from BizTalk point of view is the configuration of the Send and Receive ports.
There for you need to first generate the correct SAP schemas.  (See blog post: “Communication with SAP through WCF custom adapter – Generate SAP schemas”).

Note: When generating the SAP schemas, BizTalk will provide you with the correct bindings to setup the Send/Receive Ports.
On the other side, it’s better to cross-check that configuration to be sure that you have the correct setup.

Send Ports

Your URI should look like this:

sap://CLIENT=[SAPClientID];LANG=[LANG];@a/[ServerName]/[SystemID]?RfcSdkTrace=False&AbapDebug=False
ex: sap://CLIENT=235;LANG=EN;@a/10.80.32.3/00?RfcSdkTrace=False&AbapDebug=False

In the SOAP Action header you should specify the action, this action you can find in the configuration of your generated SAP schema. 

Double check the configuration of the URI and do not forget to add your credentials to avoid logon problems. 

Receive Ports

Your URI should look like this:

sap://CLIENT=[SAPClientID];LANG=[LANG];@a/[ServerName]/[SystemID]?ListenerGwHost=[ListenerGWHost]&amp;ListenerGwServ=[ListenerGWService]&amp;ListenerProgramId=[ListenerProgramID]
ex: sap://CLIENT=235;LANG=EN;@a/10.80.32.3/00?ListenerGwHost=10.80.32.3&amp;ListenerGwServ=SAPGW00&amp;ListenerProgramId=BIZTALK_CODIT

The SAP team has to provide you with the correct variables. Again, do not forget to add your credentials to avoid logon problems.
If you still have issues with enlisting your Receive Locations you should paste following entries in c:\windows\system32\drivers\etc\services.
 Services.txt (3.71 kb)

Enjoy !

Glenn Colpaert 

In order to send and receive messages from SAP you need to have the correct schemas generated from SAP.
To successfully generate those schemas you need following prerequisites installed.

·         BizTalk - SAP LOB Adapter SDK SP2

·         BizTalk – Adapter Pack 2.0

·         BizTalk – SAP client libraries 

Create a new project in Visual Studio. Click “Add Generated Items”. 

Select “Consume Adapter Service”.

Select the “sapBinding” and press “Configure”.
Configure the URI properties (application server host, the gateway host, the gateway service, the system number, the client, programid) and credentials provided.

When the configuration is finished press the “Connect button”.
In the following sceen you can Select Client (Outbound operations) or Server (Inbound Operations), then you can select the IDOC you want.
Be sure to select the correct version of the IDOC. Select the Send or Receive operation and click “OK” to generate the schema.

 Generating a schema will provide you with the correct schemas and a binding file that you can use to setup the receive or send port.
(See blog post: “Communication with SAP through WCF custom adapter – Send and Receive Ports”)

Enjoy !

Glenn Colpaert