BizTalk Server 2013/2013 R2: Step-by-Step WCF-SAP Adapter installation guide

Posted: March 4, 2015 in BizTalk
Tags: , , , , , , ,

There is a lot of inconsistent and incorrect information about the BizTalk SAP Adapter (or in this case WCF-SAP Adapter) installation process and how it works – It is normal to see comments that the adapter only runs on 32-bit, or to see indications that we have to copy DLLs to two different places (System32 and SysWOW64) but which ones?

I hope with this step-by-step installation guide to clarify a bit and document a little better this task.

So, one of the key question that we need to clarify is: Does the WCF-SAP adapter runs under 64-bit Host Instance?

And the correct response to this question is: Yes, it does! The SAP adapter supports both the 32-bit and the 64-bit versions of the SAP RFC SDK, so it can run under 32 or 64-bit Host Instances.

The second important question that we need to clarify is that: Documentation specifies that we need to add the 32-bit version of the client DLLs for the SAP adapter to C:\Windows\SysWow64 folder and the 64-bit version of the DLLs must be added to C:\Windows\System32 folder, but what this means? Do need to add the same DLL in two different folders?

Indeed, the documentation is correct and we need to add both 32 and 64-bit to different folder in our system… but this are different DLL and no the same ones – so if you only have one SDK resource, for example the SAP RFC SDK 32-bit, you just need to add this into one of the folders, copy for both places doesn’t make any difference because the adapter will only run in this case under a 32-bit Host Instance.

For each SAP Client version (6.4, 7.0 and so on) there are two SAP RFC SDK one for 32-bit and one for 64-bit and you need to download and install both… just like the BizTalk Server Adapter Pack.

There are SAP UNICODE and NON-UNICODE, so witch version of the SAP RFC SDK should I download?

The SAP adapter requires Unicode version of the RFC SDK irrespective of whether the SAP system is Unicode or non-Unicode.

Official documentation states that only the following SAP server versions are supported:

  • SAP 7.2, SAP 7.0, SAP ERP 6.0 with EHP 4.0, SAP ECC 6.0 Unicode

However earlier version, which were mentioned in previous versions of the documentation, are also supported:

  • SAP ECC 5.0 Non-Unicode, SAP ECC 5.0 Unicode, SAP R/3 4.7 Non-Unicode, SAP R/3 4.7 Unicode, SAP R/3 4.6c Non-Unicode, SAP ERP 6.0 with EHP 4.0

Also official documentation states that the only supported client version is the SAP RFC SDK 7.2 UNICODE – I always recommend to use the latest version… however, once again, as previous versions of the documentation mentioned, these client versions are also supported:

  • SAP client 6.4 version: SAP RFC SDK 6.40 UNICODE
  • SAP client 7.0 version: SAP RFC SDK 7.00 UNICODE
  • SAP client 7.1 version: SAP RFC SDK 7.10 UNICODE
  • SAP client 7.11 version: SAP RFC SDK 7.11 UNICODE

I’m not a SAP expert but I think that all depends if the SAP client version is supported in your SAP System version. For example, in one BizTalk Server 2013 R2 environment I have the SAP client 7.2 version installed and in another one, a BizTalk Server 2013, I have the 7.0 and both are working fine.

And finally: Can I install only the 64-bit version?

No, you can’t and for the exact same reason that we need to install both version of the BizTalk Server Adapter Pack: Visual Studio and BizTalk Administration console are 32-bit applications, so in order to configure the adapter in runtime (Receive Locations or Send Ports that will be using the SAP Adapter) or to use it to generate the schemas in the development phase you always need to have installed the 32-bit version of the SAP RFC SDK.

The 64-bit version of the SAP RFC SDK is optional, but, if you have a 64-bit BizTalk environment and you want to run it under 64-bit Host Instance, then you need to also install both versions of the SAP RFC SDK.

Download Prerequisites

As happen with other LOB adapters (like Oracle for example), installing the BizTalk Adapter pack is not enough and you will need the addition resources that will be specify bellow.

Download SAP Resources from SAP Service Marketplace

You need to obtain a few resources from the SAP Service Marketplace in order to properly install WCF-SAP adapter:

  • SAP RFC SDK <version> UNICODE 32-bit
  • SAP RFC SDK <version> UNICODE 64-bit
  • R3DLLINST.zip containing Microsoft run-time DLLs
  • SAPCAR – SAPCAR is a compress utility (similar to WinZip, tar and so on), that is used by SAP to compress and decompress nearly all delivered files

Unfortunately, SAP Service Marketplace is restricted, so if you like to benefit from the content and services offered in the different portals of the SAP Service Marketplace, you need to request your personal User ID otherwise you need to ask your client or your SAP team to give you this resources.

In additional to the links above you may also find useful to give these two SAP notes to your client or SAP team:

Unlike R3DLLINST.zip, that is a unique resource, on the SAP Service Marketplace portal SAP RFC SDK page you will find several resources and we must understand exactly what we need, in this case for example purposes, I’m using the SAP RFC SDK 7.20 page:

SAP-Service-Marketplace-portal-SAP-RFC-SDK-7.20

Depending in the SAP client version you want to install this may change a little, but it is practically the same for the other versions, as you can see in the case of SAP RFC SDK 7.00 page

SAP-Service-Marketplace-portal-SAP-RFC-SDK

What you need to download is the:

  • Windows Server on IA32 32bit” –> this is the SAP RFC SDK 7.00 UNICODE 32-bit
  • And the “Windows on x64bit” –> SAP RFC SDK 7.00 UNICODE 64-bit

You also need to download SAPCAR to extract (unzip) the SAP resources, I think you may found this resource at service.sap.com/patches under:

  • Download, Support Packages and Patches, Entry by Application Group, Additional Components and then SAPCAR

SAP-Service-Marketplace-portal-SAPCAR

Extract SAP Resources

Once we have downloaded all this SAP resources, we need to use the SAPCAR to extract the SAP resources, in this case (SAP RFC SDK 7.20):

  • “RFC_12-10009744.SAR” is the 64-bit SDK that we want to extract to “rfcsdk 64” folder
  • “RFC_12-100097446.SAR” is the 32-bit SDK that we want to extract to “rfcsdk 32” folder

BizTalk-Server-SAP-Software-resources

To accomplished that we need to:

  • Open a command line prompt
  • Change our directory to the location where we saved the “SAPCAR.exe” and execute the following command to extract the the SAR archive:
    • SAPCAR.exe -xfv “RFC_12-10009744.SAR”
      • This will create a folder call “rfcsdk”, rename that to “rfcsdk 64”

Extract-SAR-archive-with-SAPCAR

    • SAPCAR.exe -xfv “RFC_12-10009746.SAR”
      • This will create a folder call “rfcsdk”, rename that to “rfcsdk 32”

The final step regarding to SAP Resource is to unzip the “r3dllinst.zip” file using for example an open source Windows utility for manipulating archives like 7-Zip.

Download Microsoft Visual C++ 2005 SP1 Redistributable Package

Microsoft Visual C++ run-time DLLs, again both 32 and 64-bit are required for SAP 7.11 client or higher. This resources are available from download in the following links:

download-Microsoft-Visual-C  _2005_SP1_Redistributable_Package

download-Microsoft-Visual-C  _2005_SP1_Redistributable_Package-files

Step-by-Step WCF-SAP Adapter installation guide

The first thing you need to make sure that you have installed already is both 32 and 64-bit versions of the Microsoft BizTalk Adapter Pack.

  • The Microsoft BizTalk Adapter Pack contains adapters that enable enterprise applications and databases to interface with each other by implementing a common adapter framework. Similar to programming to Web services, adapters enable clients to program to different enterprise applications. Technically, adapters are a binding to Windows Communication Framework (WCF). The BizTalk Adapter Pack consists of the following adapters:
    • Microsoft BizTalk Adapter for Oracle Database (Oracle Database adapter).
    • Microsoft BizTalk Adapter for Oracle E-Business Suite (Oracle E-Business adapter).
    • Microsoft BizTalk Adapter for mySAP Business Suite (SAP adapter). This also includes the .NET Framework Data Provider for mySAP Business Suite (Data Provider for SAP).
    • Microsoft BizTalk Adapter for Siebel eBusiness Applications (Siebel adapter). This also includes the .NET Framework Data Provider for Siebel eBusiness Applications (Data Provider for Siebel).
    • Microsoft BizTalk Adapter for SQL Server (SQL adapter).
  • Find more about the BizTalk Adapter Pack installation process in the following articles:

Notice that, at this point, if you try to create a receive or send port using the WCF-SAP adapter you will get the following error:

Exception has been thrown by the target of an invocation. (mscorlib)
Could not load file or assembly ‘Microsoft.Adapters.SAP.SAPGInvoker.dll’ or one of its dependencies. The specified module could not be found. (Microsoft.Adapters.SAP)

Could-not-load-file-assembly-Microsoft.Adapters.SAP.SAPGInvoker.dll

This is because we need the SAP resources required to run the adapter are not install (or are i installed incorrectly).

So, now that we have install the Microsoft BizTalk Adapter Pack, we need to install the SAP Resources that we previous download in our BizTalk Server machine:

  • Open the “rfcsdk 64” folder containing the SAP RFC SDK 7.20 UNICODE 64-bit and access to the lib folder
    • “C:\SAP Resources\rfcsdk 64\lib”

SAP-rfcsdk-7.2-64-bit-lib-Resources

  • Install the SAP RFC SDK 64-bit DLLs by coping (or drag) them to the “System32” folder in your system “Windows” folder
    • “C:\Windows\System32”:

SAP-rfcsdk-7.2-64-bit-lib-Resources-Installation

  • And now we need to do the a similar process to the Open the SAP RFC SDK 7.20 UNICODE 32-bit
  • For that you need to open the “rfcsdk 32” folder containing the SAP RFC SDK 7.20 UNICODE 32-bit and access to the lib folder
    • “C:\SAP Resources\rfcsdk 32\lib”

SAP-rfcsdk-7.2-32-bit-lib-Resources

  • Install the SAP RFC SDK 32-bit DLLs by coping (or drag) them to the “SysWOW64” folder in your system “Windows” folder
    • “C:\Windows\SysWOW64”:

SAP-rfcsdk-7.2-32-bit-lib-Resources-Installation

  • Open the “r3dllinst\ ntpatch” folder containing the content of “r3dllinst.zip” file, ,and we need to execute the “R3DLLINS.EXE” tool, in order to install the SAP R/3 DLLs (Microsoft run-time DLLs):
    • msvcr71.dll
    • msvcp71.dll
    • mfc71.dll
    • mfc71u.dll

install-SAP-r3dllinst-R3DLLINS

  • The tool specifies that the DLLs were installed under “C:\Windows\System32” folder, however because I’m using a 64-bit environment instead they were installed in “c:\Windows\SysWOW64” folder

install-SAP-r3dllinst-R3DLLINS-SysWOW64

    • You should check if DLL are present in “C:\Windows\System32”, if they are not I advise you to:
      • Leave them in the ” c:\Windows\SysWOW64” folder
      • And, just to be sure, copy the same four DLLs to “C:\Windows\System32” folder

install-SAP-r3dllinst-R3DLLINS-windows-folder

  • And finally we also need to installed Microsoft Visual C++ 2005 SP1 Redistributable Package – 32-bit and 64-bit – containing the Visual C++ run-time DLLs required for SAP 7.20 (or 7.11) client:
    • Install the Microsoft Visual C++ 2005 SP1 Redistributable Package (x86) – 32-bit – by executing the “Vcredist_x86.exe” file that we previous download
      • On the Microsoft Visual C++ 2005 SP1 Redistributable Package window, click “Yes”

Microsoft-Visual-C  -2005-SP1-Redistributable-Package-x86

    • Do the same steps to install the Microsoft Visual C++ 2005 SP1 Redistributable Package (x64) – 64-bit – by executing the “Vcredist_x64.exe” file that we previous download
      • On the Microsoft Visual C++ 2005 SP1 Redistributable Package window, click “Yes”
Add adapters to BizTalk Administration Console

As it happens with all adapters that we installed on our BizTalk Servers environment, before we can begin to use them we need to register or add the adapters. So in the next step it will be describing how can we add the enterprise adapters, or any other custom adapter, on the BizTalk Administration Console. To accomplish that we need to:

  • Open BizTalk Administration Console by pressing the “Windows key” to switch to the Start screen, type “BizTalk Server Administration” or “BizTalk”, click “BizTalk Server Administration” option from the Search menu
  • In the console left tree, expand “BizTalk Server Administration –> BizTalk Group –> Platform Settings” and then “Adapters”
  • Right-click on “Adapters” and add a new adapter by selecting the option “New –> Adapter”

BizTalk-Administration-Console-Register-WCF-SAP-adapter-add-new

  • In the “Adapter Properties” window
    • In the Name box, type a descriptive name for this adapter.
      • WCF-SAP
    • In the Adapter combo box, select the adapter from the drop-down that you want to add.
      • WCF-SAP
    • In the Description box, type a description for the adapter (this is optional).
      • The WCF-SAP adapter provides a rich metadata layer on top of SAP that enables the consumption of RFCs and enables seamless BAPI and IDOC exchange in an interoperable manner. The SAP adapter exposes the SAP system as a WCF service to client applications.

BizTalk-Administration-Console-Register-WCF-SAP-adapter

    • Click “OK” to complete the process of adding the adapter.
      • We will receive a warning message saying that we need to restart the Host Instances
      • Click “Ok”, we will deal with it in a moment

BizTalk-Administration-Console-Register-WCF-SAP-adapter-warning-message

  • Now we need to create other send and receive adapter handlers for the WCF-SAP Adapter, to accomplished that we need to:
  • Expanded the adapter list, right-click the “WCF-SAP” adapter, point to New, and then:
    • click “Send Handler to create a send handler”
    • Or click “Receive Handler” to create a receive handler.

BizTalk-Administration-Console-Register-WCF-SAP-adapter-add-receive-send-handlers

Notice: that by default the adapter already have one Receive and one Send handler that are associated to the default Host Instance – normally the “BizTalkServerApplication” Host Instance

  • Add two send handler using Dedicated Send Hosts
    • One running under 32-bit: BizTalkServerSend32Host
    • One running under 64-bit: BizTalkServerSendHost
  • Add two receive handler using Dedicated Receive Hosts
    • One running under 32-bit: BizTalkServerSend32Host
    • One running under 64-bit: BizTalkServerSendHost
  • Delete the default handlers that use the “BizTalkServerApplication” Host (in my case it was “BizTalkServerApplication64Host”)

BizTalk-Administration-Console-Register-WCF-SAP-adapter-handler-configuration

Note: Now more about Create and Configure BizTalk Server Host and Host Instances in my TechNet Wiki article: BizTalk Server Best Practices: Create and Configure BizTalk Server Host and Host Instances

  • Finally we just need to restart our BizTalk Server Host Instances, for that you need to:
    • Expand the BizTalk group, click “Platform Settings”, and then click “Host Instances”.
    • In the details pane, right-click the host instance you want to start, and then click “Start”.

BizTalk-Administration-Console-restart-host-instances-final-step

Validate if the WCF-SAP adapter is properly installed

To do a preliminary test you to your WCF-SAP Adapter installation you can create a new receive port:

  • Right-click “Receive Ports”, point to “New”, and click “One-way Receive Port”

SAP-validation-add-new-receive-port

  • Just leave the default name and click on the “Receive Locations” tab and then click “New”.

SAP-validation-add-new-receive-location

  • In the Receive Location Properties dialog box, do the following:
    • From the Type drop-down list, select the “WCF-SAP” adapter you added earlier, and then click “Configure”.

SAP-validation-add-new-receive-port-configure-receive-location

If you were able to access the WCF-SAP Transport Properties window and the URI SAP configuration windows, this is half way thru and a good indication that the adapter is properly configured in your environment

WCF-SAP-Transport Properties-adn-URI-Windows

Of course now you need to actually test it against your SAP environment to see if you actually can receive or send messages from or to SAP System.

Comments
  1. Benny Verhamme says:

    Dear Mr.

    We have installed a new BizTalk 2013 R2 environment. We are also testing the SAP Adapter.
    Everything works fine until we do some failure tests. Like filling in No Password in the credentials. If we do that the host instance just crash. And message that needs to be send out stays in process.
    This is the error we see in te eventlog. We have installed the same versions you described here above. We would expect that message just get suspended with a error about the credentials (just lik in BizTalk 2010).

    Application: BTSNTSvc.exe
    Framework Version: v4.0.30319
    Description: The process was terminated due to an unhandled exception.
    Exception Info: System.Runtime.CallbackException
    Stack:
    at Microsoft.Adapters.Internal.LayeredChannelBindingElement.LayeredAsyncResult.SignalFinished(System.Object, System.Exception)
    at Microsoft.Adapters.Internal.LayeredChannelBindingElement.LayeredOutboundChannel`1[[System.__Canon, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089]].AsyncRequest(System.Object)
    at System.Threading.QueueUserWorkItemCallback.WaitCallback_Context(System.Object)
    at System.Threading.ExecutionContext.RunInternal(System.Threading.ExecutionContext, System.Threading.ContextCallback, System.Object, Boolean)
    at System.Threading.ExecutionContext.Run(System.Threading.ExecutionContext, System.Threading.ContextCallback, System.Object, Boolean)
    at System.Threading.QueueUserWorkItemCallback.System.Threading.IThreadPoolWorkItem.ExecuteWorkItem()
    at System.Threading.ThreadPoolWorkQueue.Dispatch()
    at System.Threading._ThreadPoolWaitCallback.PerformWaitCallback()

    • Benny Verhamme says:

      But we use the WCF-Custom adapter with SAP-Binding

      • I’m also using WCF-Custom adapter with SAP-Binding but I don’t get the behavior that you described. Instead as I expected I get : Reason: “Microsoft.ServiceModel.Channels.Common.ConnectionException: Details: ErrorCode=RFC_OK. ErrorGroup=RFC_ERROR_LOGON_FAILURE. SapErrorMessage=Name or password is incorrect (repeat logon).

        Problem there is something wrong with your installation.

  2. Benny Verhamme says:

    Hello

    Did you set the EnableBizTalkCompatibilityMode to False in de SAP-Binding? I just found out if I set this to false that it works. But on our BizTalk 2010 it is set at true and there it works fine. I imported the resource Microsoft.Adapters.SAP.BizTalkPropertySchema in my application but that didn’t help. So it only works if I set EnableBizTalkCompatibilityMode to False.

    Thanks in Advance.

    Kind regards
    Benny Verhamme

  3. […] Just make sure that you install all the pre-reqs correctly, and you’ll be […]

  4. Darshan says:

    The link for downloading RFC SDK on SAP Marketplace suggests that we should migrate to new NW RFC SDK. So does that impact the steps for setting up SAP adapter. I am still getting the same error after following above steps.

    Thanks!

    • Darshan says:

      It seems to be working fine now. I realized classic SDKs are still available.

      • Hi Darshan,
        This post was made before BizTalk Server 2013 R2 CU2 have been released so… Upon installation of CU2, the WCF-SAP or WCD-Custom, sapBinding is enabled to utilize the SAP .Net Connector. This feature improvement also creates a binary dependency. The SAP .Net Conector 3.0 must be downloaded from the SAP Marketplace and installed on all BizTalk nodes running the WCF-SAP adapter.

        According to the SAP note on the installation of the RFC SDK it will no longer be supported after March 31, 2016. The classic RFC SDK was replaced by the SAP .Net Connector

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s