[This is prerelease documentation and is subject to change in future releases. Blank topics are included as placeholders.]

Welcome to the Microsoft BizTalk Adapter Pack Beta2 Installation Guide. This document contains information about the installing the BizTalk Adapter Pack.

Contents

About Microsoft BizTalk Adapter Pack

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 the Windows Communication Framework. BizTalk Adapter Pack comprises the following adapters:

  • Microsoft BizTalk Adapter 3.0 for mySAP Business Suite

  • Microsoft BizTalk Adapter 3.0 for Oracle Database

  • Microsoft BizTalk Adapter 3.0 for Siebel eBusiness Applications

Software Prerequisites

Make sure you have the following components installed on the system where you will install the BizTalk Adapter Pack:

  • Microsoft .NET Framework 3.0.

  • Microsoft BizTalk Server 2006 R2. You require this only if you want to use the adapters with BizTalk.

    Important
    You must install Microsoft .NET Framework 3.0 before installing BizTalk Server 2006 R2.

    Important
    Make sure you install BizTalk Server 2006 R2 version 3.6.1228.0 or higher. WCF LOB Adapter SDK installation checks for this version to install a BizTalk add-in.

  • Microsoft Windows Communication Foundation (WCF) Line of Business (LOB) Adapter SDK (WCF LOB Adapter SDK).

    Important
    To install a BizTalk add-in, WCF LOB Adapter SDK requires BizTalk Server 2006 R2 version 3.6.1228.0 or higher. If you will be using the adapters with BizTalk, you must install this add-in. To install this add-in, you must perform a "Custom" or "Complete" installation of WCF LOB Adapter SDK.

  • Microsoft Visual Studio 2005. You require this only if you want to develop applications that run over adapters.

  • Respective enterprise application clients and associated software. See Supported Enterprise Application Versions for a list of software you must install for each adapter.

Supported Enterprise Application Versions

The following table presents the client and server versions for the enterprise application with which BizTalk Adapter Pack Beta2 can be used:

Adapter Supported Server Versions Supported Client Versions Driver Client Platform

Microsoft BizTalk Adapter 3.0 for mySAP Business Suite

  • SAP R/3 Enterprise 47x110 Non-Unicode Server

  • SAP R/3 Enterprise 4.7x220 Non-Unicode Server

  • SAP R/3 Enterprise 47x110 Unicode Server

  • SAP ECC 5.0 Non-Unicode

  • SAP 6.0 Unicode
  • SAP 6.4

  • SAP 7.0
  • librfc32u.dll.

  • DLLs available from SAP as part of the package, UCLIB.SAR. See SNOTE* 785368 for more information.

  • DLLs available from SAP as part of R3DLLINST.zip. This contains Microsoft runtime DLLs and can be downloaded from the SAP site. See SNOTE* 684106 for more information.

  • For SAP 7.0 you must have an additional DLL, Libsapu16vc71.dll. This DLL is available from the UCLIB.SAR package for SAP 6.0.

    Note
    Make sure you add these DLLs to the PATH variable.
  • Windows XP SP2

  • Windows 2003 Server SP1

  • Windows Server 2003 R2

  • Windows Vista

Microsoft BizTalk Adapter 3.0 for Oracle Database

  • Oracle 9.2.0.2

  • Oracle 10.1.0.2.0

  • Oracle 10.2.0.1.0
  • Oracle Client version 10.2.0.1 (part of Oracle Data Access Components (ODAC) version 10.2.0.020)
  • Oracle Data Provider for .NET 2.0 10.2.0.2.20 (ODP.NET 2.0)

    Note
    You must manually add the Oracle.DataAccess.dll (version 2.102.2.20) to the Global Assembly Cache (GAC). This DLL will be installed on your computer at <drive>:\oracle\product\10.2.0\client_1\odp.net\bin\2.x.
  • Windows XP SP2

  • Windows 2003 Server SP1

  • Windows Server 2003 R2

Microsoft BizTalk Adapter 3.0 for Siebel eBusiness Applications

  • Siebel 7.7 and 7.8
  • Siebel Web Client 7.7

  • Siebel Web Client 7.8

sstchca.dll
  • Windows XP SP2

  • Windows 2003 Server SP1

  • Windows Server 2003 R2

* SNOTEs are release notes that accompany fixes released by the SAP.

Preparing Your Enterprise Applications to Work with Adapters

This section provides a checklist of items that make sure your enterprise application clients are properly setup to work with the adapters. Note that the items listed in the checklist are not dependent on BizTalk Adapter Pack installation. You can install the BizTalk Adapter Pack and then perform the steps in the checklist, or vice-versa.

Preparing Your SAP Client

Perform the following tasks on the computer that has the SAP client and SAP adapter installed:

  • Make sure the librfc32u.dll is available on the computer where you will install the SAP adapter.

  • Make sure the DLLs available from SAP as part of the package UCLIB.SAR, are installed on the computer where you will install SAP adapter. See SNOTE* 785368 for more information.

  • Make sure the Microsoft runtime DLLs, required by the librfc32u.dll are available on the computer. These DLLs are available in the R3DLLINST.zip file, which is available for download from the SAP site. This file unzips to create a folder, NTPATCH. Run the R3DLLINS.EXE file available in the folder to copy the required DLLs. Refer to SAP note, SNOTE 684106 for more information.

  • Make sure all the above DLLs are added to the PATH variable.

Preparing Your Siebel Client

Make sure your Siebel client and server setup includes the following:

  • Make sure the Siebel web client is installed on the computer where you have the BizTalk Adapter Pack installed.

  • Make sure the configuration file (.cfg) for your Siebel application includes the name of the database DLL that you will be using with Siebel. By default, the configuration file includes the name of the IBM DB2 database DLL.

  • Make sure the username with which you will be connecting to the Siebel system exists in the backend database and has required privileges to perform operations on the Siebel system.

Preparing Your Oracle Client

Perform the following tasks on the computer that has the Oracle client and Oracle Database adapter installed:

  • Make sure you have the right Oracle Data Access Components (ODAC) version installed. As part of the ODAC installation, make sure you install Oracle client and the right version of ODP.NET. For the list of supported versions see Supported Enterprise Application Versions.

    Note
    To make sure your application works with the most recent version of ODP.NET you must have the "policy DLLs" installed on the computer and registered in the GAC. For more information see http://go.microsoft.com/fwlink/?LinkID=92834.

  • Make sure you added the Oracle.DataAccess.dll (version 2.102.2.20) to the GAC.

  • Make sure that the net service name that you specify to connect to the Oracle database is properly configured in tnsnames.ora. You can configure a net service name by using the Net Configuration Assistant. Refer to Oracle documentation for instructions on using the Net Configuration Assistant.

Installing the BizTalk Adapter Pack

Make sure you have the prerequisites installed before installing BizTalk Adapter Pack.

To install BizTalk Adapter Pack

  1. Download the setup files to a temporary location on your computer. You can download the setup files from the appropriate link under Microsoft Connect.

  2. To launch the installation wizard, navigate to the folder containing the setup files and double-click Setup.exe.

  3. On the splash screen, click Install Microsoft BizTalk .NET Adapters to launch the adapter installation wizard.

  4. Read the information on the Welcome screen and click Next.

  5. Read and accept the license agreement and click Next.

  6. In the Choose Setup Type dialog box,

    • click Typical to install the most common features.

    • click Custom to select the adapters you wish and proceed to the next step.

    • click Complete to install all the features.

      Important
      You are recommended to perform a custom installation to install only the adapter that you will be using to interface with your enterprise application.

      Note
      For this release, Typical and Complete options essentially perform the same action.

  7. Perform this step if you chose to do a custom installation in the previous step. If you chose to perform a typical or complete install, skip this step and proceed to the next step.

    1. In the Custom Setup dialog box, expand the Base Adapters node to see the list adapters available with the adapter pack.

    2. For the adapters that you do not want to install, click the icon next to the adapter name and select Entire feature will be unavailable.

    3. Similarly, expand the ADO Providers node and select the providers that you do not want to install.

    4. Click Next.

  8. Click Install.

  9. Specify whether you want to get automatic updates for patches related to BizTalk Adapter Pack.

    Use this To do this

    Use Microsoft Update when I check for updates (recommended)

    Select this to keep BizTalk Adapter Pack up to date with the latest fixes

    I don't want to use Microsoft Update

    Select this to prevent BizTalk Adapter Pack from being updated with Microsoft Update

  10. Click OK.

  11. Click Finish.

After Installing the BizTalk Adapter Pack

Perform the following steps after installing the BizTalk Adapter Pack.

  • Create tables in a SQL database. You must perform this task only if you wish to make tRFC (transactional RFC) calls to the SAP system using the SAP adapter.

  • Register the adapter bindings and the ADO providers if the setup wizard failed to do so.

  • Install the custom RFCs if you chose to install the Data Provider for SAP.

Creating Tables in a SQL database

To use the transaction RFC (tRFC) feature, the SAP adapter requires some tables in a SQL database. You must create these tables manually after installing the BizTalk Adapter Pack. The BizTalk Adapter Pack installation copies the SQL files to <install drive>:\Program Files\Microsoft BizTalk .NET Adapters. You should run the file, SapAdapter-DbScript-Install.sql to create the tables in the SQL database.

Registering the Bindings

You must perform these steps only if the installation wizard fails to register the adapter bindings or ADO providers in the machine.config file.

To register the adapter bindings or the ADO providers

  1. Navigate to the machine.config file under <system drive>:\WINDOWS\Microsoft.NET\Framework\<version>\CONFIG

  2. Open the file using a text editor.

  3. To register the adapter bindings:

    1. Search for the element "system.serviceModel" and add the following under it:

      <client>
  <endpoint binding=”sapBinding” contract=”IMetadataExchange” name=”sap” />
  <endpoint binding=”siebelBinding” contract=”IMetadataExchange” name=”siebel” />
  <endpoint binding=”oracleDBBinding” contract=”IMetadataExchange” name=”OracleDb” />
</client>
    2. Search for the element "bindingExtensions" under system.serviceModel\extensions.

    3. Look for the missing adapter binding. Add the following sections under the "bindingExtensions" node, depending on the missing adapter binding. You must register all the bindings if the wizard fails to register any.

    • For SAP adapter, add:

      <add name="sapBinding" type="Microsoft.Adapters.SAP.SapAdapterBindingSection,Microsoft.Adapters.SAP, Version=2.0.0.0, Culture=neutral, PublicKeyToken=public key" />
    • For Siebel adapter, add:

      <add name="siebelBinding" type="Microsoft.Adapters.Siebel.SiebelAdapterBindingSection,Microsoft.Adapters.Siebel, Version=2.0.0.0, Culture=neutral, PublicKeyToken=public key" />
    • For Oracle Database adapter, add:

      <add name="oracleDBBinding" type="Microsoft.Adapters.DbAdapter.DbAdapterBindingSection,Microsoft.Adapters.DbAdapter, Version=2.0.0.0, Culture=neutral, PublicKeyToken=public key" />
    Note
    Refer to the Determining the Public Key to find out how to determine the public key.

  4. To register the ADO providers:

    1. Search for the element DbProviderFactories under the system.data node.

    2. Look for the missing ADO providers. Add the following sections under the DbProviderFactories node, depending on the missing ADO provider. You must register all the providers if the wizard fails to register any.

    • For Data Provider for SAP, add:

      <add name="SAP ADO.NET Provider" invariant="Microsoft.Adapters.SAP.SAPProvider"
description="ADO.NET Provider For SAP" type="Microsoft.Adapters.SAP.SAPProvider.SapProviderFactory,Microsoft.Adapters.SAP.SAPProvider, Version=2.0.0.0, Culture=neutral, PublicKeyToken=public key" />
    • For Data Provider for Siebel, add:

      <add name="Siebel ADO.NET Provider" invariant="Microsoft.Adapters.SiebelDbProvider"
description="ADO.NET Provider For Siebel" type="Microsoft.Adapters.SiebelDbProvider.SiebelProviderFactory,Microsoft.Adapters.SiebelDbProvider, Version=2.0.0.0, Culture=neutral, PublicKeyToken=public key" />

  5. Save and close the machine.config file.

Determining the Public Key

Perform the following steps to determine the public key for an adapter or ADO provider.

To determine the public key

  1. Navigate to the Windows directory, typically C:\WINDOWS\assembly.

  2. Right-click the DLL for which you want the public key and select Properties. The following table lists the name of the DLLs for each adapter and provider.

    Adapter/ADO Provider Name of the DLL

    SAP Adapter

    Microsoft.Adapters.SAP

    Siebel Adapter

    Microsoft.Adapters.Siebel

    Oracle Database Adapter

    Microsoft.Adapters.DbAdapter

    SAP ADO Provider

    Microsoft.Adapters.SAP.SAPProvider

    Siebel ADO Provider

    Microsoft.Adapters.SiebelDbProvider

  3. On the General tab, the value against the Public Key Token label specifies the public key for the DLL.

  4. Copy the public key and click Cancel.

Installing the Custom RFCs

You must perform this step only if you want to use the Data Provider for SAP. For instructions on installing the custom RFC refer the to the "Installing the Custom RFCs for SAP ADO Provider" topic in the SAP adapter documentation. The document is installed along with the adapter at <install drive>: \Program Files\Microsoft BizTalk Adapter Pack\Documents.

Installing the Enterprise Applications

Refer to respective enterprise application installation guides for installation instructions. Refer to the user documentation for each adapter to know about specific configuration changes, if any, required to be performed for each enterprise applications. The user documents for the adapters are installed along with the adapters at <install drive>:\Program Files\Microsoft BizTalk .NET Adapters\Documents.

Installation and Post Installation Checklist

Make sure you have performed the following tasks related to installation and post installation of BizTalk Adapter Pack.

Modifying the BizTalk Adapter Pack Installation

Perform the following steps to modify the BizTalk Adapter Pack installation. Make sure you have the WCF LOB Adapter SDK installed before you run the setup program to modify the BizTalk Adapter Pack installation.

To modify Microsoft BizTalk Adapter Pack installation

  1. Launch the Control Panel. Click Start > All Programs > Control Panel.

  2. In the Control Panel window, click Add or Remove Programs.

  3. In the Add or Remove Programs window, highlight Microsoft BizTalk .NET Adapters and click Change.

  4. Read the information on the Welcome screen and click Next.

  5. In the Change, repair, or remove installation dialog box,

    • click Change to select the components you wish to install.

    • click Repair to repair errors in the most recent installation.

    • click Remove to remove Microsoft BizTalk Adapter Pack from the computer.

  6. If you chose to modify the installation,

    • Expand the Microsoft BizTalk .NET Adapters node to specify whether you wish to install the base adapters or the ADO providers or both.

    • Expand the Base Adapters node to specify whether you wish to install all the adapters or specific adapters.

    • Expand the ADO Providers node to specify whether you wish to install all the providers or specific providers.

    • Click Next.

    • Click Change and click Finish.

  7. If you chose to repair the installation, in the Ready to repair Microsoft BizTalk .NET Adapters dialog box, click Repair and click Finish.

  8. If you chose to remove the adapters, in the Ready to remove Microsoft BizTalk .NET Adapters dialog box, click Remove and click Finish.

Removing the BizTalk Adapter Pack

If you created tables in the SQL database to work with the tRFC feature of the SAP adapter, you must manually remove them before removing the BizTalk Adapter Pack. The BizTalk Adapter Pack installation copies a SapAdapter-DbScript-Uninstall.sql file under <install drive>:\Program Files\Microsoft BizTalk .NET Adapters. You must run this file to remove the tables you created.

Perform the following steps to remove Microsoft BizTalk Adapter Pack from your computer. Make sure you have the WCF LOB Adapter SDK installed before you run the setup program to remove the adapters.

To remove Microsoft BizTalk Adapter Pack

  1. Launch the Control Panel. Click Start > All Programs > Control Panel.

  2. In the Control Panel window, click Add or Remove Programs.

  3. In the Add or Remove Programs window, highlight Microsoft BizTalk .NET Adapters and click Remove.

  4. In the dialog box, click Yes.

After Removing the BizTalk Adapter Pack

Perform the following steps after removing the BizTalk Adapter Pack.

  • Remove the adapter bindings and the ADO providers registration if the setup wizard failed to do so.

  • Remove the custom RFCs if you chose to install the Data Provider for SAP.

Removing the Bindings

You must perform these steps only if the installation wizard fails to remove the adapter bindings or ADO provider registration from the machine.config file.

To remove the adapter bindings or ADO providers registration

  1. Navigate to the machine.config file under <system drive>:\WINDOWS\Microsoft.NET\Framework\<version>\CONFIG

  2. Open the file using a text editor.

  3. To remove the adapter binding registration:

    • Search for the element bindingExtensions under system.serviceModel\extensions.

    • Look for the adapter binding that is still registered. Remove the following sections under the bindingExtensions node, depending on the existing adapter binding. You must remove all the bindings if they exist.

    • For SAP adapter, remove:

      <add name="sapBinding" type="Microsoft.Adapters.SAP.SapAdapterBindingSection,Microsoft.Adapters.SAP, Version=2.0.0.0, Culture=neutral, PublicKeyToken=public key" />
    • For Siebel adapter, remove:

      <add name="siebelBinding" type="Microsoft.Adapters.Siebel.SiebelAdapterBindingSection,Microsoft.Adapters.Siebel, Version=2.0.0.0, Culture=neutral, PublicKeyToken=public key" />
    • For Oracle Database adapter, remove:

      <add name="oracleDBBinding" type="Microsoft.Adapters.DbAdapter.DbAdapterBindingSection,Microsoft.Adapters.DbAdapter, Version=2.0.0.0, Culture=neutral, PublicKeyToken=public key" />

  4. To remove the ADO provider registration:

    • Search for the element DbProviderFactories under the system.data node.

    • Look for the ADO providers that are still registered. Remove the following sections under the DbProviderFactories node, depending on the existing ADO provider. You must remove all the providers if they exist.

    • For Data Provider for SAP, remove:

      <add name="SAP ADO.NET Provider" invariant="Microsoft.Adapters.SAP.SAPProvider"
description="ADO.NET Provider For SAP" type="Microsoft.Adapters.SAP.SAPProvider.SapProviderFactory,Microsoft.Adapters.SAP.SAPProvider, Version=2.0.0.0, Culture=neutral, PublicKeyToken=public key" />
    • For Data Provider for Siebel, remove:

      <add name="Siebel ADO.NET Provider" invariant="Microsoft.Adapters.SiebelDbProvider"
description="ADO.NET Provider For Siebel" type="Microsoft.Adapters.SiebelDbProvider.SiebelProviderFactory,Microsoft.Adapters.SiebelDbProvider, Version=2.0.0.0, Culture=neutral, PublicKeyToken=public key" />

  5. Save and close the machine.config file.

Removing the Custom RFCs

You must perform this step to remove the custom RFCs you installed in the SAP system. For instructions on removing the custom RFC refer the to the "Installing the Custom RFCs for SAP ADO Provider" topic in the SAP adapter documentation. The document is installed along with the adapter at <install drive>: \Program Files\Microsoft BizTalk Adapter Pack\Documents.

Samples for BizTalk Adapter Pack

This BizTalk Adapter Pack release provides samples demonstrating how to use the adapters with BizTalk Server, channel programming model, and proxy programming model. The samples are available in the "Samples" directory on the CD image.

Accessing the Adapter Pack Forum

You can use the Adapter Pack forum to discuss any issues you encounter with Microsoft BizTalk Adapter Pack Beta 2. The adapterpacknoversion forum is available at http://go.microsoft.com/fwlink/?LinkId=87695.

Copyright

This document supports a preliminary release of a software product that may be changed substantially prior to final commercial release.  This document is provided for informational purposes only and Microsoft makes no warranties, either express or implied, in this document.  Information in this document, including URL and other Internet Web site references, is subject to change without notice.  The entire risk of the use or the results from the use of this document remains with the user.  Unless otherwise noted, the companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted in examples herein are fictitious.  No association with any real company, organization, product, domain name, e-mail address, logo, person, place, or event is intended or should be inferred.  Complying with all applicable copyright laws is the responsibility of the user.  Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document.  Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

© 2007 Microsoft Corporation.  All rights reserved.

Microsoft, MS-DOS, Windows, Windows Server, Windows Vista, and BizTalk are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

All other trademarks are property of their respective owners.