BizTalk Server 2013 R2: WCF-SAP Adapter Step-by-Step Installation Guide

  • Article

Introduction

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.

The Microsoft BizTalk Adapter Pack Installation Guide is available to download at BizTalk 2013 and R2 Install Guides.

Common questions/doubts

Before we start the installation guide, there are some key questions that we need to clarify.

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.

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 which 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 ECC 6.0 Unicode, SAP ECC 6.0 Unicode with EHP 4.0, SAP ECC 6.0 with EHP 7.0 and all EHP previous versions

Also official documentation states that the following client versions are supported – I always recommend to use the latest version…

  • SAP client 7.1 version: SAP RFC SDK 7.10 UNICODE
  • SAP client 7.11 version: SAP RFC SDK 7.11 UNICODE
  • SAP client 7.20 version: SAP RFC SDK 7.20 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.

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 additional resources that will be specified below.

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 these resources.

In addition to the links above you may also find it 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:

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

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 find this resource at service.sap.com/patches under:

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

Extract SAP Resources

Once we have downloaded all these 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

To accomplish 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”

    • 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. These resources are available for download in the following links:

Additional Considerations

Installation of Cumulative update package 2 for BizTalk Server 2013 R2

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.
If the required binaries do not exist, you will receive the following: 
*System.IO.FileNotFoundException: Could not load file or assembly 'sapnco, Version=3.0.0.42, Culture=neutral, PublicKeyToken...
*

The SAP .NET Connector also creates an additional dependency on the latest Visual C++ Redistributable package. The following must be downloaded and installed:

OR

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

You can 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)

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

So, now that we have installed the Microsoft BizTalk Adapter Pack, we need to install the SAP Resources that we previous downloaded 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”

  • 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”:

  • 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”

  • 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”:

  • 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

  • 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

    • 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

  • 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”
    • 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 downloaded
      • 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

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

    • 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

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

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 handlers using Dedicated Send Hosts
    • One running under 32-bit: BizTalkServerSend32Host
    • One running under 64-bit: BizTalkServerSendHost
  • Add two receive handlers using Dedicated Receive Hosts
    • One running under 32-bit: BizTalkServerReceive32Host
    • One running under 64-bit: BizTalkServerReceiveHost
  • Delete the default handlers that use the “BizTalkServerApplication” Host (in my case it was “BizTalkServerApplication64Host”)

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

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

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

  • 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”.

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.

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

See Also

Another important place to find  an extensive amount of BizTalk related articles is the TechNet Wiki itself. The best entry point is BizTalk Server Resources on the TechNet Wiki.