Last updated: March 17, 2006

This document provides instructions for installing and configuring Microsoft® BizTalk® Adapters for Enterprise Applications and Microsoft® BizTalk® Adapter v2.0 for mySAP™ Business Suite Service Pack 1.

Note:
To make sure that you are reading the most up-to-date information, download the latest version of the BizTalk Adapters for Enterprise Applications installation guide at http://go.microsoft.com/fwlink/?LinkId=56392.

Microsoft BizTalk Adapters for Enterprise Applications includes the following adapters:

Important:
You must be experienced with the specific enterprise application before you make any configuration changes.

Caution:
It is highly recommended that you back-up all data before you make any configuration changes.

Note:
For more detailed information, see the specific Help documentation for each adapter. For information about specific enterprise applications, see the enterprise application-specific Help.

Adapter Requirements

This section describes software requirements and preparation steps for each adapter. For installation information, see the "Installing BizTalk Adapters for Enterprise Applications" section.

Requirements for BizTalk Adapter for JD Edwards OneWorld

Microsoft BizTalk Adapter for JD Edwards OneWorld XE runs on the following operating systems:

  • Microsoft® Windows® 2000

  • Microsoft Windows XP

  • Microsoft Windows Server™ 2003

Note:
Microsoft J# is required for Microsoft BizTalk Adapter for JD Edwards OneWorld.

The following table shows the components that this adapter was tested against.

Components tested against

Component Support Required Components

JD Edwards OneWorld XE

B73.3.3

To correctly apply ASU, Service Pack 23.

JD Edwards Enterprise server

Windows

JD Edwards Deployment server

Windows

Preparing to Use JD Edwards OneWorld

This section describes the requirements for JD Edwards OneWorld to work with Microsoft BizTalk Adapter for JD Edwards OneWorld.
JAR Files and the CLASSPATH

Two JD Edwards OneWorld JAR files must be available to the adapter:

  • Connector.jar

  • Kernel.jar

These files are located on the JD Edwards OneWorld computer, in the following locations:

  • JD Edwards OneWorld XE_install_Directory\System\classes\Connector.jar

  • JD Edwards OneWorld XE_install_Directory\System\classes\Kernel.jar

You can copy these files to any location; however, you must specify the location of the JAR files in the CLASSPATH. The CLASSPATH must include both the full path of the file and the name of the JAR file (separated by a semicolon).

BizTalk Adapter for JD Edwards OneWorld provides the JDEJAccess JAR file for use with JD Edwards OneWorld. By default, the JDEJAccess.jar file is referenced from the <Adapter_Installation>\classes folder:

  • C:\Program Files\Common Files\Microsoft BizTalk Adapters for Enterprise Applications\JD Edwards OneWorld\classes\JDEJAccess.jar

Note:
You must verify the registration of the jdeinterop.ini file before you can use BizTalk Adapter for JD Edwards OneWorld. Make sure that you include a path to this file in the JDE Transport Property page when you create the send port in BizTalk Server. For a complete explanation, see "Customizing the jdeinterop.ini File."

Creating the BTSLIBinterop.jar File

You must create the BTSLIBinterop.jar file, and make sure that it can be accessed by the adapter. You can use the following sample as a guide:

1. Create the BTSLIB.cmd file that contains the following code:

define library BTSLIB
login
library BTSLIB
interface JDEAdapter
import B5500900
build
logout

2. Run the following command:

GenJava  /cmd  .\BTSLIB.cmd
Verifying Your Setup

Follow this checklist to verify the setup of JD Edwards OneWorld:

  1. Verify that the JD Edwards OneWorld service pack number is 23. Service packs (ESUs and ASUs) update the system binaries. The prerequisite service pack provides the ASU/ESU menu choice for import.

  2. Configure the jdeinterop.ini file to use the correct drive for logging, if it differs from drive C. For example, your JD Edwards OneWorld update could fail if the TEMP directory is out of space.

  3. Determine whether you must add a configuration file for the left/right padding of the JD Edwards OneWorld fields.

  4. Verify that your JAVA_HOME environment variable is pointing to your Java Development Kit (JDK) installation to enable the javac and java commands from any program on the computer.

  5. Verify that the CLASSPATH environment variable is set; this enables BizTalk Adapter for JD Edwards OneWorld to locate the Kernel.jar and Connect.jar files.

    The path of the JAR files is case sensitive.

  6. Test the environment by typing the following command, which is case sensitive:

    javap -s -p com.microsoft.jde.JDEJAccess
    The command you give, javap, is the Java Class File Disassembler:

    http://java.sun.com/j2se/1.3/docs/tooldocs/solaris/javap.html
    The javap command disassembles a class file. Its output depends on the options used. If no options are used, javap prints out the package, protected, and public fields and methods of the classes passed to it. javap prints its output to stdout.

    If there are no errors, all the Java files and their dependencies are in the CLASSPATH.

  7. Set up the DNS resolution by configuring the local host file, C:\WINNT\system32\drivers\etc\hosts, with the server name of the JD Edwards OneWorld system.

Creating and Installing the Custom Package

You must install the BTSREL custom package to use BizTalk Adapter for JD Edwards OneWorld.

This section describes:

  • The JD Edwards OneWorld custom package-creation process.

  • How to create and install BTSREL.

  • The BTSREL objects created in JD Edwards OneWorld.

Note:
BTSREL.exe is a custom package (an automated software update, or ASU, in JD Edwards OneWorld terminology). It contains business functions to extract metadata. A custom package should be created for a specific configuration and version of JD Edwards OneWorld.
Defining a Custom Package

A custom package is a post-release deliverable that provides software changes for specific purposes, such as regulatory changes or enhancements. These custom packages are created for specific functionality. For example, BTSREL is created to extract metadata. When the BTSREL custom package is installed, it updates selected modules in the JD Edwards OneWorld environment. To update, BTSREL objects must be merged into the appropriate JD Edwards OneWorld environment. For a detailed list of modules updated by BTSREL, see the list of modules.

Creating the Custom Package BTSREL

For information about how to create the custom package, see http://go.microsoft.com/fwlink/?LinkId=63528.

Installing the Custom Package BTSREL

To install the custom package, BTSREL, the following are required:

  • Deployment server installation.

  • Installation Workbench.

Installing BTSREL on the Deployment Server

The custom package only works on a Windows operating system and is used with the deployment server. It must be built on the deployment server and then deployed to the enterprise server. The enterprise server is usually a production server, and can be on either a Windows or UNIX operating system.

Note:
When applying the ASU to the JD Edwards OneWorld deployment server, verify that you are in Update mode. The Proof mode verifies that there are no bugs in the ASU, whereas Update mode is designated for when you apply the ASU.

To install the custom package on the deployment server

  1. Log on to the deployment server as user JDE.

  2. Create a new folder, named BTSREL, on the Deployment Server (root) /B7 folder.

  3. Copy BTSREL.exe to the newly created BTSREL folder.

  4. Run BTSREL.exe from the.../B7/BTSREL folder.

    JD Edwards OneWorld Installation Manager automatically starts after the executable file opens.

  5. On the JD Edwards OneWorld Deployment Server Setup Type screen, click Next, and then click Finish.

    After the installation finishes, a dialog box informs you if the installation was successful.

  6. Log on to the JDEPLAN environment as user JDE on the JD Edwards OneWorld deployment server.

    1. If the electronic software update (ESU) that includes SAR #4533357 has not been installed on the system, select Software Updates from the System Installation Tools menu (GH9612).

    2. Enter 02 for option 1 in the Processing Options panel.

    3. If the ESU that includes SAR #4533357 has been installed on the system, select Application Software Update from the System Installation Tools menu (GH9612).

Installing BTSREL on the JD Edwards OneWorld WorkBench

To install BTSREL on the JD Edwards OneWorld WorkBench

  1. On the Work with Application Update screen, double-click the BTSREL update, and then click Next.

  2. Double-click the environments where you want the update installed, and then click Next.

    1. Check Unattended Workbench if you want the software update to run in unattended mode.

    2. Select Backup if you want the backup of the specifications (so that the original specifications can be restored).

  3. On the Work with Installation Plan screen, select the plan for the update you are installing, and then click Select.

  4. See the automatically generated PDFs for errors after the installation is finished.

    Note:
    If errors occur, look in the JD Edwards OneWorld Software Update Guide for troubleshooting tips, or contact JD Edwards OneWorld directly.

  5. Manually register the business function library using the steps included in "Manually Registering the Business Function Library" in this section.
Uninstalling the Custom Package

There is no requirement to uninstall the custom package. However, if you want to clean the system, you can uninstall in different ways. You must rebuild the package after uninstalling. You can use one of the following methods:

  • Using the JD Edwards OneWorld Deployment Server, Gh8612—P96470, on the ROW menu, select Update, and then click Uninstall.

  • Check out all the custom objects (BTSREL) to a client computer and delete them.

  • Apply a previous snapshot of database.

During the clean-up, verify any other modifications to the other objects of JD Edwards OneWorld.

Manually Registering the Business Function Library

Because of a limitation of the JD Edwards OneWorld product packaging process, the custom Business Function Library DLL for BizTalk Adapter for JD Edwards OneWorld must be manually registered with JD Edwards OneWorld. This process consists of the following four steps:

Step 1: Create the Custom Business Function Library

Using JD Edwards OneWorld Object Management Workbench (OMW), create the Custom Business Function Library. The following procedure must be performed on initial setup and applies to all platforms.

To create the custom business function library

  1. Start the Object Management Workbench (fast path: "OMW" or menu selection: GH902 Object: P98220).

  2. Click Add, and select the option for Business Function Library.

  3. Enter the following information for the New Business Function Library Object:

    • Name: ACBLIB

    • Description: Microsoft DLL

    • Product Code: 55

    • Product System Code: 55

  4. Click OK.

Step 2: Rebuild Libraries from the Deployment Server

The following procedure must be performed on initial setup for each platform.

To rebuild libraries from the deployment server

  1. To start the BusBuild program in a standalone mode, click Start, click Run, and then click busbuild.exe.

    You are prompted to log on to JD Edwards OneWorld.

  2. Log on to JD Edwards OneWorld in the pathcode (PY7333, PD7333, or DV7333).

  3. In the Rebuild Libraries list, select the Build.

Step 3: Copy the Custom DLL

Copy the custom DLL from the pathcode directory to the parent package directories on the JD Edwards OneWorld deployment server and on the JD Edwards OneWorld Enterprise Server, as follows:

  • By using the JD Edwards OneWorld XE Deployment Server:

    1. Copy ACBLIB.dll from DV7333\bin32 to DV7333\Packages\DV7333FA\bin32.

    2. Copy ACBLIB.def, ACBLIB.dmp, and ACBLIB.mak from DV7333\obj folder to DV7333\Packages\DV7333FA\obj folder.

    3. Copy ACBLIB.exp, ACBLIB.lib, and sACBLIB.lib from DV7333\lib32 folder to DV7333\Packages\DV7333FA\lib32 folder.

  • By using the JD Edwards OneWorld Enterprise Server:

    After each directory and file is created, verify the authorization.

    1. Create a directory ACBLIB under DV7333FA\obj\.

    2. Create a directory ACBLIB under DV7333FA\source.

    3. FTP b5500900.c from Deployment Server DV7333\source directory to DV7333FA\source\ACBLIB directory.

    4. FTP b5500900.h from Deployment Server DV7333\include directory to DV7333FA\include directory.

Step 4: Build a Full Package

Because of a limitation of the JD Edwards package-build process, you must build a full package for the environments to which you applied the BTSREL update, or the update package build will not work correctly. See the JD Edwards documentation on how to build a full package build.

Note   When you apply JD Edwards OneWorld ASU/ESUs, the ASU/ESU does not typically create new library and business functions. Therefore, the process is simple: however, the BizTalk Adapter for JD Edwards OneWorld custom package creates a new library; therefore, you must perform extra steps, such as manually creating a directory and running a full package build.

List of Modules

The custom package BTSREL creates the following objects in JD Edwards OneWorld. BTSREL contains business functions to extract metadata and custom functions to test the data types.

Note:
There is a bug in the JD Edwards OneWorld update. If you do not have all the business and custom functions, verify that a full package build was performed, rather than an update package build.

If you are missing files from the list, for example, if you have everything below ACBTEST but nothing above it, you might be missing the Data Dictionary (DD) items. You can go to Work With Data Items and look for missing files.

If you are missing other items, such as ACBCHAR01, ACBDATE01, ADBINT01, ACBMATH01, and ACBSTR01, these are the Primary Data Elements. When you merge objects from planner to DEV, many reports run in the background. You can open the merge reports and look for errors. The reports should list all the items and indicate that they were completed without errors or warnings. With this verification, you can continue because all items are accounted for.

  • ACBCHAR01 - TEST CHAR TYPE 01

  • ACBCUST - ACB CUSTOMER ID

  • ACBDATE01 - TEST DATE TYPE 01

  • ACBDEF - ACB FUNCTION TYPE DEFINITION

  • ACBFCNT - ACB FUNCTION NAME LIST COUNT

  • ACBFUNC - ACB FUNCTION NAME LIST

  • ACBFUNCN - ACB FUNCTION NAME

  • ACBINT01 - TEST INTEGER TYPE 01

  • ACBLIB - CONTROL BROKER LIBRARY

  • ACBMATH01 - TEST MATH TYPE 01

  • ACBNEWS - ACB NEW STATUS

  • ACBORDER - ACB ORDER NUMBER

  • ACBPRC - ACB ITEM PRICE

  • ACBPROD - ACB PRODUCT ID

  • ACBQTY - ACB ITEM QUANTITY

  • ACBRES - ACB RESULT INDICATOR

  • ACBSTAT - ACB STATUS

  • ACBSTR01 - TEST STRING TYPE 01

  • ACBTEST - ACB TEST SCREEN

  • ACBTEST2 - ACB TEST SCREEN 2

  • ACBTEST3 - ACB TEST SCREEN 3

  • B5500900 - CONTROL BROKER SUPPORT MODULE

  • D5500900 - CONTROL BROKER DATA STRUCTURE

  • D5500900A - CONTROL BROKER DATA STRUCTURE

  • D5500900B - FETCH PRICE DATA STRUCTURE

  • D5500900C - GET CUSTOMER STATUS DATA STRUCTURE

  • D5500900D - SET CUSTOMER STATUS DATA STRUCTURE

  • D5500900E - UPDATE SALES ORDER STATUS DATA STRUCTURE

  • D5500900F - TEST INTEGER

  • D5500900G - TEST STRING

  • D5500900H - TEST DATE

  • D5500900I - TEST CHAR

  • D5500900J - TEST MATH NUMERIC

  • D5500900K - TEST DATE 2

Customizing the jdeinterop.ini File

The JD Edwards OneWorld XE connector classes in Connector.jar and Kernel.jar require that you use a configuration file named jdeinterop.ini. This file is defined by the JD Edwards OneWorld software and uses its terminology. For more information about the purpose and terminology of this file, see the JD Edwards Interoperability Guide Release OneWorld. There is a sample jdeinterop.ini file in <Adapter_Installation>\config\jde.

You must edit jdeinterop.ini to match the parameter values that you defined in the Transport Properties screen. Multiple JD Edwards OneWorld logical systems can share the same jdeinterop.ini file if their parameters are compatible. Generally, if two logical systems point to two different JD Edwards OneWorld computers, they will need two different copies of jdeinterop.ini.

Note:
The logging in jdeinterop.ini should be kept turned off, and the parameters for the various log files can safely be ignored.

The following table itemizes the settings found in the jdeinterop.ini file. The information is organized by section. For example [JDENET] and the sections are listed in the order that they appear in the JD Edwards OneWorld software.

File settings for jdeinterop.ini

Section Parameter and Description

[JDENET]

EnterpriseServerTimeout. The time-out value for a request to the enterprise server in milliseconds. The default size is 120000.

maxPoolSize. The JDENET socket connection pool size. The default size is 30.

[SERVER]

glossaryTextServer. The enterprise server and port that provide glossary text information. This is the server that returns text descriptions for errors. This is frequently the same host and port as the JD Edwards OneWorld application server. There may be more than one glossary server for different supported language encodings. For example, JDED:6010 or actsrv1:6009. The values must match those set in System Definition.

codePage. The encoding scheme. The default is 1252.

  • 1252 English and Western European

  • 932 Japanese

  • 950 Traditional Chinese

  • 936 Simplified Chinese

  • 949 Korean

[LOGS]

log= c:\jas.log. Location of the log file. You can safely ignore this parameter.

debuglog= c:\jasdebug.log. Location of debug log file. You can safely ignore this parameter.

Debug. Determines whether JDENET debugging is on. The default is FALSE.

[DEBUG]

JobFile= c:\Interop.log. Location of error file. You can safely ignore this parameter.

DebugFile= c:\InteropDebug.log. Location of debug file. You can safely ignore this parameter.

log= c:\net.log. Location of log file. You can safely ignore this parameter.

debugLevel= 0 - 12. Debug levels. You can safely ignore this parameter. This defines the level of tracing provided by the COM Connector and the Callobject component in the specified log file, in the COM server only.

  • 0 None. Logging is turned off and only errors are written to the JobFile.

  • 2 Errors (error messages).

  • 4 System Errors (exception messages).

  • 6 Warning Information.

  • 8 Min Trace (Key operations. For example, Logon, Logoff, Business Function calls.).

  • 10 Troubleshooting Information (Help).

  • 12 Complete Debug Information (Logs everything).

By default, you do not have to turn on tracing, but tracing is useful when you are debugging your code.

NetTraceLevel=0. Trace levels. You can safely ignore this parameter. Defines the level of tracing provided by the ThinNet component in the specified log file, in the COM server only. The odd values are reserved for future levels to be added.

The following list describes debug levels even more:

  • 0 No trace.

  • 1 Refers to the Record process ID, thread ID, and the available socket status when a new connection is added and the socket pool is searched.

  • 2 Includes the information in trace level 1 and also traces every call made in the connection manager class.

  • 3 Includes all information in trace level 2, and also traces getPort() calls and getHost() calls.

[INTEROP]

enterpriseServer. This value is the name of the host server. Make sure that this value is the same value that you enter in the Host Name field in the JDE Credentials section in System Definition in the Transport Properties dialog box. The default is JDED.

port. This value is the port number that is used to exchange data. Make sure that this value is the same value that you enter in the Port Number field in the JD Edwards Credentials section in the Transport Properties, System Definition. For example, 6010 or 6009. The values must match those set in System Definition.

inactive_timeout. The time-out value in milliseconds for a transaction in auto-commit mode. If the user is inactive for this period of time (in milliseconds), the interop server logs off the user. You can change this value to a shorter period of time. The default is 1200000.

manual_timeout. The time-out value in milliseconds for a transaction in manual commit mode. The default is 120000.

Repository. Points to the location of the directory that contains Connector.jar and Kernel.jar. On UNIX, this is a full path.

[CORBA]

You can safely ignore this parameter.

Multithread —The setting can be ignored. Set to 1 for multithread support for CORBA.

Objects= CORBA::Connector;CORBA::OneWorldVersion

Defines the objects for the CORBA server to create at startup. Also replaces the -DIORFILENAME = command-line option, for example: CORBA::Connector=connector.ior.

Requirements for BizTalk Adapter for JD Edwards EnterpriseOne

Microsoft BizTalk Adapter for JD Edwards EnterpriseOne runs on the following operating systems:

  • Windows 2000

  • Windows XP

  • Windows Server 2003

The adapter was tested against the following components:

Components tested against

Component Support Required Components

JD Edwards EnterpriseOne

Version 8.10 and access to the following files:

  • JDE 8.10 - Connector.jar, Kernel.jar, database.jar, jdeutil.jar, log4j.jar, and xerces.jar.

  • Database JDBC File. For example, Microsoft SQL Server 2000 JDBC driver—msbase.jar, mssqlserver.jar, and msutil.jar. (See Note in this section.)

  • JDEDynAccess.jar - installed with the product.
Note:
BizTalk Adapter for J.D.Edwards EnterpriseOne calls the JD Edwards EnterpriseOne API that uses JDBC, which needs a driver for the database. If you install JD Edwards EnterpriseOne with a SQL database, you need MS-SQL drivers. Similarly if you installed JD Edwards EnterpriseOne with an Oracle database, you will need Oracle drivers; or if you installed with a DB2 database, you will need DB2 drivers.

Executing a JD Edwards EnterpriseOne Master Business Function

You can use the BizTalk Adapter for JD Edwards EnterpriseOne to invoke a JD Edwards EnterpriseOne master business function, such as Address Book, Purchase Order, or Sales Order. You can also use the adapter as part of an integration effort to connect JD Edwards EnterpriseOne with BizTalk Server.
Accessing Data Stored in JD Edwards EnterpriseOne

The adapter accepts XML messages to enable BizTalk Server applications to communicate and exchange transactions with JD Edwards EnterpriseOne using one of the following:

  • Transmit Adapter,which uses a Static Solicit-Response Send port to send a message to JD Edwards EnterpriseOne and expects a response.

  • Receive Adapter, which uses a Static One-Way Receive port to receive messages from JD Edwards EnterpriseOne.

Interoperability Framework

JD Edwards EnterpriseOne provides for integration with systems through its interoperability framework. The adapter uses the JD Edwards EnterpriseOne framework and takes advantage of various integration access methods to provide the greatest amount of flexibility and functionality.

BizTalk Adapter for JD Edwards EnterpriseOne supports the following integration access methods:

  • JD Edwards EnterpriseOne ThinNet API

  • JD Edwards EnterpriseOne XML

  • JD Edwards EnterpriseOne unedited transaction tables (Z tables)

The adapter uses the JD Edwards EnterpriseOne ThinNet API to communicate with the JD Edwards EnterpriseOne application. By using the ThinNet API, the adapter can invoke one master business function (MBF) in a single unit of work (UOW). When an MBF fails, the whole UOW fails. This prevents partial updates. The validation of data, business rules, and communications to the underlying database are handled by the JD Edwards EnterpriseOne application.
JD Edwards Outbound Processing Framework

In the outbound process, the event starts when a specific MBF is executed in the JD Edwards EnterpriseOne environment. The MBF writes the required information for the event into the appropriate interface table and then notifies the subsystem batch function (BF) that an event occurred. The subsystem BF then includes an entry about the event on the subsystem data queue.

The outbound subsystem retrieves the data queue entry and looks in the Data Export Control table for the external processes to notify. The outbound subsystem then calls the BizTalk Adapter for JD Edwards EnterpriseOne listener with notification. The listener passes the notification to the generator. The generator then uses the JD Edwards EnterpriseOne ThinNet API to retrieve the appropriate information from the interface table.

Setting String Justification in Jdearglist

To configure certain string arguments as right-justified and left padded in the J.D. Edwards EnterpriseOne jdearglist.txt file, you must know what business function you want to access; specifically, you must know which fields in the business function you want to call.

You must update the jdearglist.txt before you generate the bindings (schemas) in the orchestration. The instructions for updating the jdearglist.txt file outlined in the "Handling String Values" section.

If you receive a jdearglist.txt warning message in the log, its purpose is to inform you that the jdearglist.txt is missing. However, if you are running the SalesOrder or PurchaseOrder business function, you must have that file in your PATH or it will not work.

Understanding the jdeinterop.ini File

The JD Edwards EnterpriseOne connector classes in Connector.jar and Kernel.jar require that you use a configuration file named jdeinterop.ini. This file is defined by the JD Edwards EnterpriseOne software and uses its terminology. For more information about the purpose and terminology of this file, see the JD Edwards Interoperability Guide. There is a sample jdeinterop.ini file in: C:\Program Files\Program Files\Microsoft BizTalk Adapters for Enterprise Applications\JD Edwards EnterpriseOne\config.

It is not recommended that you edit this file manually because it interacts with the Transport Properties dialog box for the send port -- for example those fields marked as <configured by BizTalk>.

Requirements for BizTalk Adapter for PeopleSoft Enterprise

You must have the following software installed before you can continue with the installation of Microsoft BizTalk Adapter for PeopleSoft Enterprise.

  • Microsoft BizTalk Server

  • Sun Systems Java Development Kit (JDK)

  • PeopleSoft software

Receive Handler PeopleSoft Requirements

The PeopleSoft Integration Broker must be able to communicate with BizTalk Server. The following could have already occurred in an existing PeopleSoft environment and you could reuse an existing node; therefore, you would not have to do anything except obtain the HTTP specifications from a PeopleSoft System Administrator. For step-by-step information, see "Using PeopleSoft Application."

These are the basic steps that you must follow in PeopleSoft:

  1. Set up the message and make it active through the Application Designer.

  2. Make a one-time change to the PeopleSoft integration.gateway.properties file.

  3. Create and configure the gateway and nodes to activate HTTP.

    • The node must be using some triggering method, for example, the LOCATION_SYNC mechanism.

    • The node must use HTTP.

    • The node must point to the host and port to which you are sending the event.

Send Handler PeopleSoft Requirements

BizTalk Adapter for PeopleSoft Enterprise consists of a custom component interface (CI) that provides access through a Java API. A custom CI object, GET_CI_INFO, is deployed in the PeopleSoft system using PeopleSoft Tools, to provide metadata information that is required by BizTalk Adapter for PeopleSoft Enterprise. For more information, see "Preparing to use PeopleSoft."

Uploading of the custom component interface is a one-time occurrence. This file, GET_CI_INFO.pc, is provided with the product and must be installed in the PeopleSoft system before you can use the adapter to browse CIs. You must have access to the PeopleSoft Application Designer; however, the Application Designer does not have to be anywhere near the BizTalk Server computer. You use the Application Designer to upload the custom CI into the PeopleSoft computer that you will browse.

You must have access to the PeopleSoft computer because you must set the environment variable CLASSPATH (or set the information in the Transport Properties window) to point to the PeopleSoft PSJOA/psjoa.jar file.

Preparing to Use PeopleSoft

This section discusses how to set up PeopleSoft for use with Microsoft BizTalk Adapter for PeopleSoft Enterprise.

For more information about PeopleSoft, see the PeopleSoft documentation.
Supported PeopleSoft Platforms

BizTalk Adapter for PeopleSoft Enterprise accesses component interfaces and has been tested in PeopleSoft versions 8.17.02, 8.43, and 8.45. The adapter runs on Microsoft Windows 2000 and Windows XP, and on Microsoft Windows Server 2003.

BizTalk Adapter for PeopleSoft Enterprise requires a modification to the PeopleSoft application. To use component interfaces, you must upload a custom component interface, GET_CI_INFO, into PeopleSoft. GET_CI_INFO.pc is located in Program Files\Common Files\Microsoft BizTalk Adapters for Enterprise Applications\PeopleSoft Enterprise\Config\.

  • For instructions about how to use PeopleSoft 8.17.02, see "Uploading a Custom CI Into PeopleSoft."

  • For an 8.4* discussion on uploading the GET_CI_INFO, see "Creating a New Component Interface."

Setting Environment Variables

Updating JAVA_HOME

Set the JAVA_HOME variable to point to your JDK installation, for example: 

set JAVA_HOME=C:\j2sdk1.4.2_06

Updating CLASSPATH

To use component interfaces (PeopleSoft 8 only) you must update your CLASSPATH to include the PeopleSoft component interface jar file.

To update the CLASSPATH

  1. In Control Panel, open System.

  2. On the Advanced tab, click Environment Variables, and then select CLASSPATH.

  3. Add the path, for example:

    <PeopleSoft_Home>\web\PSJOA\psjoa.jar

BizTalk Adapter for PeopleSoft Enterprise requires the psjoa.jar file. This is performed when you create a send port. For more information, see "Setting Transport Properties in PeopleSoft System" in the adapter documentation.

Note:
Only have one of these directories in your PATH to make sure that BizTalk Adapter for PeopleSoft Enterprise picks up the correct DLLs. Failure to set up your environment correctly for the desired version of PeopleSoft could lead to errors that are difficult to trace.

Using Component Interfaces

Uploading a Custom CI into PeopleSoft

BizTalk Adapter for PeopleSoft Enterprise requires a modification to the PeopleSoft application. To use component interfaces, you must upload a custom component interface, GET_CI_INFO, into PeopleSoft. You only have to import GET_CI_INFO during initial setup to use the adapter. The adapter uses GET_CI_INFO to obtain information about other existing component interfaces in PeopleSoft.

This section explains how to manually import a custom component interface that will let you browse component interfaces in PeopleSoft 8.17.02, 8.43, or 8.45. Note that the custom methods do not use or modify any properties of the component interface that it is installed in. To import the custom component interface, you can use one of the following methods:

  • Create a new component to import the custom methods.

  • Use an existing component that contains no keys, for example, INSTALLATION_RS.

The simple component interface must not contain keys. If you are not sure whether a particular component interface contains keys, you can run this simple SQL statement using your SQL Query tool. It will give you a list of all the component interfaces in your application that have no keys.

select distinct BCNAME

from PSBCITEM bc1

where not exists

(select 1

from PSBCITEM bc2

where bc1.BCNAME = bc2.BCNAME

and bc2.BCTYPE in (1, 2))

You can follow PeopleSoft documentation to create a unique simple component for storing BizTalk Adapter for PeopleSoft Enterprise custom methods. You can also clone one of the pre-existing component interfaces and use it to store the custom methods.

To verify that your GET_CI_INFO has no keys, run the PeopleTools Application Designer Component Interface Test tool.

Creating a New Component Interface

Follow these steps to create a new component interface using the PeopleSoft, Application Designer Version 8.1.

Note:
To view instructions for 8.4 see "Creating a Component Interface."

To create a component interface

  1. Click Start, point to All Programs, point to PeopleSoft, and then select Application Designer.

  2. Enter a three-tier connection type, and then click OK.

    For example, select Application Server from the list.

  3. In the Application Designer, on the File menu, select New.

  4. In the New dialog box, select Component Interface, and then click OK.

  5. Click Select.

  6. From the list of all components, select any simple component.

    For example, select INSTALLATION_RS, or a new PeopleSoft component that you created.

    The custom methods do not use or modify any properties of the component interface that it is installed in.

    This simple component interface must not contain keys. If you are not sure whether a particular component interface contains keys, you can run this simple SQL statement using your SQL Query tool. It will give you a list of all the component interfaces in your application that have no keys:

select distinct BCNAME from PSBCITEM bc1 where not exists (select 1 from PSBCITEM bc2 where bc1.BCNAME = bc2.BCNAME and bc2.BCTYPE in (1, 2))

Note:
You can also follow PeopleSoft documentation to create a unique simple component for storing custom methods for BizTalk Adapter for PeopleSoft Enterprise.

To verify that your GET_CI_INFO has no keys, run the PeopleTools Application Designer Component Interface Test tool.

Checking Component Interface

You have completed uploading the Microsoft BizTalk Adapter for PeopleSoft GET_CI_INFO into your PeopleSoft System. The GET_CI_INFO is a user-defined custom component interface. It contains user-defined methods. The GET_CI_INFO component interface lets you browse component interfaces in your PeopleSoft system using the Microsoft Adapter Wizard. You can locate and expand GET_CI_INFO to view its user-defined methods.

Note   For more information about user-defined methods, see "PeopleSoft: Component Interface User-Defined Methods" in the adapter documentation.

Setting the Component Interface Security

After you install the custom GET_CI_INFO PeopleSoft component interface on PeopleSoft, set the security settings for GetCINamespace, GetDetails, and GetCollections methods for BizTalk Adapter for PeopleSoft Enterprise. This is standard practice when you create custom components or user-defined methods.

Note:
The following procedure describes how to configure security for all supported releases of PeopleSoft in all supported modes.

To configure security for the component interface

  1. Point to PeopleTools, point to Security, point to Permissions & Roles, and then select Permission Lists.

  2. In the Maintain Security window, click Search, select the relevant Permission List, and then click the appropriate list hyperlink.

  3. In the Permission List pane on the right, click the right arrow next to the Sign-on Times tab to display the Component Interfaces tab.

  4. Click the Component Interfaces tab.

  5. Click the plus sign (+) to add a new row to the Component Interfaces list.

  6. Select the GET_CI_INFO component interface, and then click Edit.

  7. To set the methods to Full Access, click Full Access (All), and then click OK.

  8. Scroll to the bottom of the Component Interfaces window, and then click Save.
Testing the Component Interface

You have finished configuring security for the GET_CI_INFO component interface delivered with BizTalk Adapter for PeopleSoft Enterprise. Your PeopleSoft component interface is ready, and you can browse PeopleSoft component interfaces.

Follow these steps to test the component interface in the Application Designer.

To test the component interface

  1. Start the Application Designer.

  2. On the File menu, point to Open, and then select Definition = Component Interface.

  3. From the list of component interfaces, select GET_CI_INFO CI.

  4. After you open GET_CI_INFO, right-click anywhere in the right pane of your component interface definition, and then select Test Component Interface.

    The Component Interface Tester window appears.

    There should be no keys listed. If your GET_CI_INFO contains keys, or if there is another option for selection, return to the Application Designer and eliminate all keys from GET_CI_INFO.

Requirements for BizTalk Adapter for Siebel eBusiness Applications

You must have the following software installed before you can continue with the installation of Microsoft BizTalk Adapter for Siebel eBusiness Applications.

  • Microsoft BizTalk Server 2006

  • Siebel software

Preparing Siebel Software

This section discusses setting up Siebel for use with BizTalk Adapter for Siebel eBusiness Applications. It includes information about the following:

  • Supported Siebel platforms

  • Preparing to use Siebel Servers

  • Verifying your Siebel information
Supported Siebel Platforms

BizTalk Adapter for Siebel eBusiness Applications runs on the following operating systems:

  • Windows 2000

  • Windows XP

  • Windows Server 2003

The adapter was tested against these versions:

  • Siebel, version 6.2.1 with patch 110 or later versions

    • Siebel Thin Client Enterprise Component

    • Siebel Java Data Bean using Java Development Kit (JDK) 1.1.8 or JDK 1.3

  • Siebel, version 7.0.3

    • Siebel Java Data Bean (using JDK 1.1.8, JDK 1.3, or JDK 1.4)

  • Siebel, version 7.5.2 and 7.7

    • Siebel Java Data Bean ( JDK 1.4)

Note:
Patch 110 for version 6.2.1 resolves a memory leak on the Siebel server when you use any kind of remote client. You must follow all instructions in the patch 110 Maintenance Release Guide from Siebel Systems. Note that you can avoid the server side memory leak by specifying the Siebel server component parameter recyclefactor to a value greater than the default, zero. The guide recommends a value of 3. This improves server performance and memory usage. You must do this for all object managers that are being used.

BizTalk Adapter for Siebel eBusiness Applications uses the Siebel Object Interface API as implemented in the Siebel Java Data Bean. The following Siebel JAR files must be available to support the adapter:

Siebel 6.2.1

  • SiebelTcOM.jar

  • SiebelTcCommon.jar

  • SiebelTC_%lang%.jar

    Where %lang% is the installed language pack; for example, SiebelJI_enu.jar is for English or SiebelJI_jpn.jar is for Japanese. You can install the .jar files through the Siebel Enterprise Server installation, or by installing Siebel Tools. For more information, see the Siebel documentation.

  • SiebelDataBean.jar

Siebel 7.0.3 and 7.5.2

  • SiebelJI_%lang%.jar

    Where %lang% is the installed language pack; for example, SiebelJI_enu.jar is for English or SiebelJI_jpn.jar is for Japanese. You can install the .jar files through the Siebel Enterprise Server installation, or by installing Siebel Tools. For more information, see the Siebel documentation.

  • SiebelJI_Common.jar

Siebel 7.7 and Siebel 7.8

  • Siebel_%lang%.jar

    Where %lang% is the installed language pack; for example, SiebelJI_enu.jar is for English or SiebelJI_jpn.jar is for Japanese. You can install the .jar files through the Siebel Enterprise Server install, or by installing Siebel Tools. For more information, see the Siebel documentation.

  • Siebel.jar

Siebel Platform Note

Excerpt from Siebel Knowledge Base 38-683408651: If you receive an 8859_1 not supported error, you must set your Java Virtual Machine (JVM) environment. The JVM encoding must match the Siebel FileEncoding setting. You must add this setting in the Windows registry or systemsettings.txt file:

Adapters/Siebel/Compatibility.FileEncoding: string = ISO8859_1

Preparing to Use Siebel Servers

This section contains instructions for how to prepare your Siebel servers to use with BizTalk Adapter for Siebel eBusiness Applications.
Updating JAVA_HOME

Set the JAVA_HOME variable to point to your JDK installation (depending on your Siebel version), for example: 

set JAVA_HOME=C:\j2sdk1.4.2_03
Updating CLASSPATH

The SBLJAccess.jar file contains the Java part of BizTalk Adapter for Siebel eBusiness Applications. The following .jar files make up the Siebel Java Data Bean provided on the Siebel 2000 eBusiness Applications and the Siebel 7 installation CD.

  • Two for Siebel 7*: (SiebelJI_enu.jar and SiebelJI_Common.jar)

  • Four for Siebel 6.2.1: (SiebelTcOM.jar, SiebelTcCommon.jar, SiebelTC_enu.jar, and SiebelDataBean.jar)

The BizTalk Adapter for Siebel computer must be able to connect to the location of these .jar files. Siebel uses these files at both run time and design time.

Follow these steps to set the CLASSPATH variable.

To set the CLASSPATH variable

  • In Control Panel, open System, and then select Environment Variables.

    OR

    On the Transport Properties page, set the variable in the Environment section.

The following example is presented on separate lines for clarity.

Siebel 6.2.1

set CLASSPATH=.;
c:\..\DATABEAN\classes\SiebelTcOM.jar;
c:\..\DATABEAN\classes\SiebelTcCommon.jar;

c:\..\DATABEAN\classes\SiebelTC_%lang%.jar;
c:\..\DATABEAN\classes\SiebelDataBean.jar;

Siebel 7.0.3 or 7.5

set CLASSPATH=.;
c:\..\DATABEAN\classes\SiebelJI_%lang%.jar;
c:\..\DATABEAN\classes\SiebelJI_Common.jar;

Siebel 7.7

set CLASSPATH=.;
c:\..\DATABEAN\classes\SiebelJI_%lang%.jar;
c:\..\DATABEAN\classes\Siebel.jar;

where:

c:\..\DATABEAN\classes - Is the directory where you have installed the Siebel Data Bean JAR files

%lang% - Is the installed language pack; for example, SiebelJI_enu.jar for English or SiebelJI_jpn.jar for Japanese. You can install the .jar files through the Siebel Enterprise Server installation, or by installing Siebel Tools. For more information, see the Siebel documentation.

BizTalk Adapter for Siebel eBusiness Applications provides a JAR file to use with Siebel. By default, this file is referenced from the siebeladapterinstallation\classes folder:

<siebeladapterinstallation_install_dir>\classes\SBLJAccess.jar;
Note:
If you are accessing the Siebel JAR files from another computer, be careful when typing the path and file names, because they are case sensitive. For example,

\Machine_A\Servers\Siebel_databean\classes\SiebelDataBean.jar

Enabling Siebel Thin Client (Siebel 6.2.1 Only)

This section describes the requirements for Siebel 6.2.1 to work with Microsoft BizTalk Adapter for Siebel eBusiness Applications. Siebel 6.2.1 requires that you enable the Siebel Thin Client Enterprise Component to enable any thin client to communicate remotely with the Siebel Application Server.

Verifying that the Siebel Thin Client Enterprise is Enabled

Follow these steps to verify that the Siebel Thin Client Enterprise is enabled on the server.

To verify that the Siebel Thin Client Enterprise is enabled

  1. Log on to the Siebel system using the Siebel Client (with Server Administration enabled).

    The user ID must have sufficient authorization to make server management changes.

  2. Click Screens, point to Server Administration, point to Enterprise Configuration, and then point to Enterprise Component Groups.

  3. Make sure that the Thin Client component is enabled.

    If it is not enabled, select the component in the list, and then click Enable.

  4. Restart the server to make sure that the settings are registered and the component is started.

Managing Memory with a Thin Client

The following settings can help memory management when you use a thin client extensively in a Microsoft BizTalk Adapter for Siebel multithreaded or multiuser scenario.
Setting Max Tasks and Max MT Server Parameters for the Siebel Object Manager

The following information is from the Siebel FAQ and should be used as a guideline for setting certain parameter values for the Siebel Object Manager (SOM) components.

FAQ 1380 from Siebel Support: The SOM is primarily used for thin client connections. The SOM is like a connected client that makes requests for multiple users. It caches information in several different ways. Some information is cached and used by all connections, and other information is stored for each user connection. Using SOMs is more efficient than using connected clients because up to 20 thin client connections can use one SOM. The clients' processing power and memory requirements can be reduced significantly, whereas the server requirements go up.

There are some concerns with memory growth for the SOM processes. Siebel has implemented some parameters to clean up the memory used by SOM.

How the process works

A parameter called the RecycleFactor multiplies the maximum number of threads that a multithreaded server can run at the same time. It works together with the MaxMTServers and MaxTasks parameters. When the RecycleFactor is set to n, it causes the current Object Manager processes to shut down and a new Object manager to start every n number of connections.

The algorithm

When the multithreaded server is started, it calculates how many threads it can run before it has to recycle itself by using the following formula:

(MaxTasks / MaxMTServers) * RecycleFactor
Note:
Remember to always make MaxTasks divisible by MaxMTServers.

When a task is created for a client connection, the multithreaded server verifies whether it is time for recycling; if it is, the server stops accepting more client connections (starting new tasks) and creates a new multithreaded server to handle new connections. When the last task ends in a deactivated multithreaded server, the process exits.

This functionality applies to situations where a server component might be leaking any kind of resource. For example, a user may want to recycle the process (multithreaded server) when it has serviced 20 clients. That means that it can run 20 tasks before it must recycle. On the other hand, because of concurrency limitations, only 20 tasks can be run per process (multithreaded server), and users want to be able to handle up to 1000 simultaneous tasks. The values for the configuration parameters will be the following:

MaxTasks = 1000
MaxMTServers = 50
MinMTServers = Max MTServers = 50

RecycleFactor = 1

These values provide the following:

Concurrent tasks per server = MaxTasks / MaxMTServers or 1000 / 50 = 20

The recommended ratio of MaxTasks to MaxMTServers is 20 to 1.

Higher ratios, such as 25 to 1 or 30 to 1, cause a high number of context switches to occur. This causes poor performance.

Low ratios, such as 10 to 1 or 5 to 1, do not take advantage of the architecture for high scalability.

    Max tasks before recycling = concurrent tasks per server *
    RecycleFactor
    or 20 * 1 = 20

The RecycleFactor is a hidden parameter. You must set it using the command-line server administration tool, srvrmgr.

Use the following command at the srvrmgr prompt:

    change param RecycleFactor= 3 for comp <component_name> server
    <server_name>

The default value for this parameter is 0 (zero), which means never recycle.

The value of the RecycleFactor must be greater than 0 (zero) if Resonate is used.

To set the value of Maximum MT Servers and Minimum MT Servers on an enterprise level

  • On the Siebel menu, point to Screens, point to Server Administration, point to Enterprise Configuration, and then click Enterprise Parameters.
To set the value of Maximum Tasks

  • On the Siebel menu, point to Screens, point to Server Administration, point to Tasks, and then click Task Parameters.

The thread-pooling component parameters are MinPoolThreads, MaxPoolThreads, and UseThreadPool.

MaxTasks / Max MT Servers = Number of sessions per Object Manager

Verifying Your Siebel Information

To help in connecting to Siebel, the following provides a brief description of Siebel terms and describes where you can locate information in a Siebel system.

  • An App server refers to the name of the Siebel Server. This is the name of the host computer where Siebel Server is installed.

  • Gateway Server is the name of the host on which the gateway server is running.

  • Enterprise refers to the name that was specified for the Enterprise server during a Siebel Server installation.

  • Enterprise Server is a logical entity. It collectively represents the Siebel Servers (application servers) and Gateway Server.

You can retrieve the name of the Gateway server, Siebel server, and Enterprise from the siebel.cfg file located in the <siebel_root>/siebsrvr/BIN/ENU directory.

You can verify the Siebel user name and password by running Siebel Call Center. When you start this application, you must enter the user name and password (which has administrator permissions).

Requirements for BizTalk Adapter for Oracle E-Business Suite

Microsoft BizTalk Adapter for Oracle E-Business Suite uses databases registered through the ODBC Data Source Administrator. The adapter runs on the following operating systems:

  • Windows 2000

  • Windows XP

  • Windows Server 2003

Microsoft BizTalk Adapter for Oracle E-Business Suite was tested against the following version:

  • Oracle Application, Version 11.5.7

You must have an Oracle client installed to use the adapter. The Oracle client installation includes the Oracle ODBC driver, which must be updated to Oracle ODBC driver 9.2.0.5.4 after you install the client.

This section includes information about the following:

  • Installing the Oracle client

  • Upgrading the Oracle driver

  • Configuring a database connection

    Note:
    For information about Oracle user account permissions, see "Permissions in Oracle E-Business Suite" in the adapter documentation. What you can see using the Adapter Wizard at design time and how your end user will use your service at run time depend on the permission set in this account.

Installing the Oracle Client

To use Oracle and Microsoft BizTalk Adapter for Oracle E-Business Suite, you must install an Oracle client. The Oracle client installation includes the Oracle ODBC driver.

Note:
Oracle 9.2 only - The ODBC driver that is installed with the Oracle 9.2 client contains a bug that prevents the enumeration of items that contain Japanese characters.

Follow these steps to install an Oracle client on your computer:

To install the Oracle client

  1. Run the Oracle client, setup.exe.

  2. Accept default values on the Welcome and File Location screens.

  3. On the Installation Types page, select Administrator, and then click Next.

  4. On the Oracle MTS Recovery Service Configuration page, accept the default port, or set your own port, and then click Next.

  5. On the Install page, click Install.

    The Oracle client installs.

  6. The Oracle .NET Configuration Assistant completes the typical configuration setup.

    You can create a Net Service Name yourself.

  7. On the Welcome page, click Next.

  8. Select the No, I want to defer this configuration to another time option, and then Next.

  9. Accept the default local naming method, and then click Next.

  10. On the Database Version page, select 8i or a later version, and then click Next.

  11. On the Service Name page, enter the service name that was set up in the Oracle Server, for example, vis, and then click Next.

  12. On the Select Protocols page, select your protocol, and then click Next.

  13. On the TCP/IP Protocol page, enter the following information, and then click Next.

    • Host name: Host name of the computer for the database, for example, Oracle11x.

    • Port number: Select to keep the default port, or change it to one that has been set for you, for example, 1521.

  14. Continue through the Wizard until you can click Finish to complete the setup.

Upgrading the Oracle Driver

After you download and open the self-extracting archive file, ORA92054.exe, it creates an installable directory structure on the hard disk drive. Run the Oracle Universal Installer from the local drive.

To upgrade the Oracle driver

  1. On the File Location page, click Browse.

  2. Locate the file, products.jar.

    This file is located in the folder that was created by the ORA92054.exe extraction.

  3. Select the file, and then click Next.

  4. On the Summary page, click Install.

  5. When the ODBC Driver upgrade finishes, click Exit.

Configuring the BizTalk Database Connection

You must set several ODBC variables before you can configure Microsoft BizTalk Adapter for Oracle E-Business Suite. The following provides a basic overview of the database configuration information; however, you can also refer to the individual instructions for more database-specific information.

In the Driver Manager, two of the selections are System Data Source Name (DSN) and Connection Pooling.

  • System DSN: System DSN is used when you are running processes under separate users and not necessarily the user who is installing and configuring BizTalk Server. The System DSN is the recommended way of defining the ODBC source.

  • Connection Pooling: Connection pooling is not required from the Driver Manager, because the Oracle Database will pool connections to the database. The maximum number of connections that the adapter will use is configurable per port using the Transport Properties window.

It is recommended that you use Test Connection for the driver wherever it is provided to verify the ODBC source connectivity to the database. If the ODBC source is not correctly set up, BizTalk Adapter for Oracle E-Business Suite cannot retrieve the metadata for this database.
Setting Up an ODBC Connection

After verifying that you have the Database Client installed on your BizTalk Adapter for Oracle E-Business Suite computer, you have to set the ODBC connection to a database.

Note:
The ODBC drivers provided by the database vendors are those that BizTalk Adapter for Oracle E-Business Suite has been tested against. The adapter has not been tested against third-party ODBC drivers. The use of any other ODBC driver is not supported.

Follow these steps to set the ODBC connection to a database.

To set the ODBC connection to the database

  1. In Control Panel, open Administrator Tools.

  2. Click [ODBC] Data Sources.

  3. Click the System DSN tab, and then click Add.

    A list of data sources appears.

  4. Select Oracle in OraHome92, and then click Finish.
Identifying Your Data Source

Follow these steps to complete the identification of your data source.

To complete the identification of the data source

  1. Enter the connection parameters.

  2. Click Test Connection to verify that you can connect to the database.

  3. Click OK to exit.

You are now ready to use the Oracle database, through BizTalk Adapter for Oracle E-Business Suite in your orchestrations using the Microsoft Adapter Wizard.

When you create an ODBC source, the driver asks for the database to use. The list of table owners is retrieved from this database. This is used to populate the TopLevel of the browser. In Oracle, this is known as the list of schemas.

ODBC Connections and Service Name

For the requests to succeed, the Local Net Service Name that is used to connect to the production system must be identical to that used for the development and test systems; however, these can refer to different server database instances.

It is not sufficient for all the schemas (user IDs), tables/views, and stored procedures that are available on one system (for example, on a development or test system), to also be available on a different system (for example, a production environment).

Requirements for BizTalk Adapter for Oracle Database

Microsoft BizTalk Adapter for Oracle Database uses databases registered through the ODBC Data Source Administrator. The adapter runs on the following operating systems:

  • Windows 2000

  • Windows XP

  • Windows Server 2003

BizTalk Adapter for Oracle Database was tested against the following version:

  • Oracle Application, Version 11.5.7

You must have an Oracle client installed to use BizTalk Adapter for Oracle Database. The Oracle client installation includes the Oracle ODBC driver, which must be updated to Oracle ODBC driver 9.2.0.5.4 after you install the client.

This section contains information about the following:

  • Installing the Oracle client

  • Upgrading the Oracle driver

  • Configuring a database connection

    Note:
    For information about Oracle user account permissions, see "Oracle Database Permissions" in the adapter documentation. What you can see using the Adapter Wizard at design time and how your end user will use your service at run time depend on the permission set in this account.

Installing the Oracle Client

To use Oracle and BizTalk Adapter for Oracle Database, an Oracle client must be installed. The Oracle client installation includes the Oracle ODBC driver.

Note:
Oracle 9.2 only - The ODBC driver that is installed with the Oracle 9.2 client contains a bug that prevents the enumeration of items that contain Japanese characters.

Follow these steps to install the Oracle client on your computer:

To install the Oracle Client

  1. Run the Oracle client, setup.exe.

  2. Accept the default values on the Welcome and File Location pages.

  3. On the Installation Types page, select Administrator, and then click Next.

  4. On the Oracle MTS Recovery Service Configuration page, accept the default port, or set your own, and then click Next.

  5. On the Install page, click Install.

    The Oracle Client installs.

  6. The Oracle .NET Configuration Assistant finishes the typical configuration setup. You can create a Net Service Name yourself.

  7. On the Welcome page, click Next.

  8. Select the No, I want to defer this configuration to another time option, and then Next.

  9. Accept the default local naming method, and then click Next.

  10. On the Database Version page, select 8i or a later version, and then click Next.

  11. On the Service Name page, enter the service name that was set up in the Oracle Server, for example, vis, and then click Next.

  12. On the Select Protocols page, select your protocol, and then click Next.

  13. On the TCP/IP Protocol page, enter the following information, and then click Next.

    • Host name: Host name of the computer for the database, for example, Oracle11x.

    • Port number: Select to keep the default port or change it to one that has been set for you, for example, 1521.

  14. Continue through the Wizard until you can click Finish to complete the setup.

Upgrading the Oracle Driver

After you download and open the self-extracting archive file, ORA92054.exe, it creates an installable directory structure on the hard disk drive. Run the Oracle Universal Installer from the local drive.

To upgrade the Oracle driver

  1. On the File Location page, click Browse.

  2. Locate the file, products.jar.

    This file is located in the folder that was created by the ORA92054.exe extraction.

  3. Select the file, and then click Next.

  4. On the Summary page, click Install.

  5. When the ODBC Driver upgrade finishes, click Exit.

Configuring the BizTalk Database Connection

You must set several ODBC variables before you can configure BizTalk Adapter for Oracle Database. This section provides an overview of the database configuration information; however, also refer to the individual instructions for more database-specific information.

In the Driver Manager, two of the selections are System DSS and Connection Pooling.

  • System DSN: System DSN is used when you are running processes under separate users and not necessarily the user who is installing and configuring BizTalk Server. The System DSN is the recommended way of defining the ODBC source.

  • Connection Pooling: Connection pooling is not required from the Driver Manager, because the Oracle Database will pool connections to the database. The maximum number of connections that the adapter will use is configurable per port using the Transport Properties window.

It is recommended that you use Test Connection for the driver wherever it is provided, to verify the ODBC source connectivity to the database. If the ODBC source is not correctly set up, BizTalk Adapter for Oracle Database cannot retrieve the metadata for this database.
Setting Up an ODBC Connection

After verifying that you have the database client installed on the BizTalk Adapter for Oracle Database computer, you have to set the ODBC connection to a database.

Note:
The ODBC drivers provided by the database vendors are those which Microsoft BizTalk Adapter for Oracle Database has been tested against. BizTalk Adapter for Oracle Database has not been tested against third-party ODBC drivers.

Follow these steps to set the ODBC connection to a database:

To set the ODBC connection to the database

  1. In Control Panel, open Administrator Tools.

  2. Click [ODBC] Data Sources.

  3. Click the System DSN tab, and then click Add.

    A list of data sources appears.

  4. Select Oracle in OraHome92, and then click Finish.
Identifying Your Data Source

Follow these steps to complete the identification of your data source.

To complete the identification of the data source

  1. Fill in the connection parameters.

  2. Click Test Connection to verify that you can connect to the database.

  3. Click OK to exit.

You are now ready to use the Oracle database, through BizTalk Adapter for Oracle Database in your orchestrations using the Microsoft Adapter Wizard.

When you create an ODBC source, the driver asks for the database to use. The list of table owners is retrieved from this database. This is used to populate the TopLevel of the browser. In Oracle, this is known as the list of schemas.

ODBC Connections and Service Name

For the requests to succeed, the Local Net Service Name that is used to connect to the production system must be identical to the one used for the development and test systems; however, these can refer to different server database instances.

It is not sufficient for all the schemas (user IDs), tables/views, and stored procedures that are available on one system (for example, on a development or test system), to also be available on a different system (for example, a production environment).

Requirements for BizTalk Adapter for TIBCO Rendezvous

Microsoft BizTalk Adapter for TIBCO Rendezvous runs on the following operating systems:

  • Windows 2000

  • Windows XP

  • Windows Server 2003

Other Requirements

  • The TIBCO Rendezvous run-time component must be installed on the computer where BizTalk Adapter for TIBCO Rendezvous is running.

  • The TIBCO Rendezvous license must be configured on the computer where BizTalk Adapter for TIBCO Rendezvous is running.

  • The TIBCO Rendezvous binaries directory must be visible to the adapter: either in the Environment variables PATH value, or specified on each Rendezvous port in BizTalk Server. This is necessary for the Rendezvous assembly to find its libraries and executables.

  • The TIBCO.Rendezvous.dll assembly must be registered in the global assembly cache (GAC) so that the adapter can find the DLL.

Requirements for BizTalk Adapter for TIBCO Enterprise Message Service

Microsoft BizTalk Adapter for TIBCO Enterprise Message Service runs on the following operating systems:

  • Windows 2000

  • Windows XP

  • Windows Server 2003

Enterprise Message Service (EMS) version 4.2 includes a client SDK (using the TIBCO EMS C# API). BizTalk Adapter for TIBCO EMS uses this to communicate with the Server.

Requirements for BizTalk Adapter v2.0 for mySAP™ Business Suite Service Pack 1

The Adapter requires that you install the following software on one computer, in the order listed:

  1. Microsoft Windows® 2000 Server SP4, Windows Server™ 2003 SP1, or Windows Server 2003 R2. You can also use Windows XP SP2 for your development environment only.

  2. Microsoft Visual Studio® 2005. This software is not required on your run-time computers.

  3. Microsoft BizTalk Server 2006, and all prerequisites.

    For more information about installing BizTalk Server 2006 and its prerequisites, see the BizTalk Server Installation Guide, at http://go.microsoft.com/fwlink/?LinkId=46922.

  4. SAP .NET Connector for Visual Studio, available from the SAP Service Marketplace Web site.

  5. You must install the SAP .NET Connector 1.x RUNTIME before installing the Adapter. You can download the SAP .NET Connector from the SAP Marketplace Web site. To download the SAP .NET Connector, you must be an SAP customer with a valid user name and password.

Installing BizTalk Adapters for Enterprise Applications

Before running the Microsoft BizTalk Adapters for Enterprise Applications installation program, make sure that you install Microsoft BizTalk Server 2006, Microsoft .NET Framework 1.1 with Service Pack 1, and all the software prerequisites for the adapters that you want to install. It is recommended that you close all applications before running Setup.

To install Microsoft BizTalk Adapters for Enterprise Applications

  1. Double-click setup.exe to run the installation program.

    The installation program extracts its files and the Introduction page appears.
Note:
You can also run a silent installation using the following command: msiexec /i <msi> /qn /l* <logfile> -- where <logfile> is optional, but is useful in the event of a failed installation.

Note:
The installation updates the PATH environment variable. To make sure that you are using the correct variables, close the installation command window to update your variables.

  1. On the Introduction page, click Next to continue.

    The License Agreement appears.

  2. Click Next after you read and accept the license agreement.

    • If you select No, the installation program removes the extracted files and closes.

    • If you select Yes, the installation program prompts you to enter your customer information.

  3. Enter the user name and organization on the Customer Information page, and then click Next.

    The Setup Type page appears.

  4. Select how you want to install Microsoft BizTalk Adapters for Enterprise Applications: Complete or Custom.

    • Complete: installs all the Microsoft BizTalk Adapters for Enterprise Applications together with all the program features and is used for development and run time.

    • Custom: lets you choose the adapters and features that you want to install and where they will be installed.

    To set the destination, click Browse and set the installation path.

  5. Click Next to continue.

  6. Click Install on the Ready to Install page.

    BizTalk Adapters for Enterprise Applications loads files to your selected location.

  7. On the Install Complete page, click Finish.
Note:
For information about how to add the adapters to BizTalk Server, see the section, "Adding the BizTalk Adapters for Enterprise Applications to BizTalk Server."

Installation Information for BizTalk Adapter for JD Edwards OneWorld

Microsoft BizTalk Adapter for JD Edwards OneWorld consists of a transmit adapter that interfaces supported databases and server systems to Microsoft BizTalk Server. The transmit adapter enables you to invoke a server system's call from BizTalk Server. The transmit adapter (the BizTalk Server Administration Send Handler) configuration specifies the location of the SQL database.

See the adapter documentation for information about how to use BizTalk Adapter for JD Edwards OneWorld and about the mapping between its model and the BizTalk Server model.

Single Sign-On

BizTalk Adapter for JD Edwards OneWorld provides support for Enterprise Single Sign-On (SSO). If you select to use SSO in the Transport Properties page, the credentials for the affiliate application in the SSO Credentials database are used. An affiliate application represents an application—a back-end that requires credentials.

Installed Components

As BizTalk Adapter for JD Edwards OneWorld finishes its installation, it registers its components in the global assembly cache (GAC) by gacutil.exe. This is required by the Microsoft .NET Framework. You can verify the registration in the GAC by viewing the assembly folder in your explorer; for example, <%WINDIR%>\assembly, or use gacutil /l.

  • Microsoft.BizTalk.Adapters.BizUtil.dll

  • Microsoft.BizTalk.Adapters.JDEProperties.dll

  • Microsoft.BizTalk.Adapters.CoreManagement.dll

  • Microsoft.BizTalk.Adapters.CoreReceiver.dll

  • Microsoft.BizTalk.Adapters.CoreTransmitter.dll

The following GAC entry is installed and deployed by btsdeploy.exe for the adapter. The BizTalk Server Deployment Log results are located in \Program Files\Microsoft BizTalk Adapters for Enterprise Applications\jdeDeploy.html and jdeDeploy.xml:

  • Microsoft.BizTalk.Adapters.JDEProperties.dll

Adapter-specific files are installed in Program Files and Program Files\Common Files.

The following files are installed in Program Files\Microsoft BizTalk Adapters for Enterprise Applications\JDEOneWorld.

  • samples\

Program Files\Common Files\Microsoft BizTalk Adapters for Enterprise Applications\JD Edwards OneWorld\ contains the following files:

  • classes\JDEJAccess.jar

  • Config\JDEOneWorld\BTSREL.exe

  • Config\JDEOneWorld\jdearglist.txt

  • Config\JDEOneWorld\jdeinterop.ini

Program Files\Common Files\Microsoft BizTalk Adapters for Enterprise Applications\Bin\ contains the following files:

  • Microsoft.BizTalk.Adapters.JDEProperties.dll

  • jdecba.dll

Installation Information for BizTalk Adapter for JD Edwards EnterpriseOne

Microsoft BizTalk Adapter for JD Edwards EnterpriseOne contains a transmit adapter that interfaces with supported databases and server systems to BizTalk Server. The transmit adapter enables you to invoke a server system’s call from BizTalk Server.

BizTalk Adapter for JD Edwards EnterpriseOne provides support for Enterprise Single Sign-On (SSO). If you select to use SSO in the Transport Properties page, the credentials for the affiliate application in the SSO Credentials database are used. An affiliate application represents an application—a back-end that requires credentials.

Installation Information for BizTalk Adapter for PeopleSoft Enterprise

Microsoft BizTalk Adapter for PeopleSoft Enterprise contains a transmit adapter that interfaces supported databases and server systems to BizTalk Server. The transmit adapter enables you to invoke a server system’s call from BizTalk Server. The transmit adapter (the BizTalk Server Administration Send Handler) configuration specifies the location of the SQL database.

BizTalk Adapter for PeopleSoft Enterprise provides support for Enterprise Single Sign-On (SSO). If you select to use SSO in the Transport Properties page, the credentials for the affiliate application in the SSO Credentials database are used. An affiliate application represents an application—a back-end that requires credentials.

The adapter installation includes samples in the \samples directory.

Installed Components

As BizTalk Adapter for PeopleSoft Enterprise finishes its installation, components are registered in the GAC by gacutil.exe. This is required by the .NET Framework. You can verify the registration in the GAC by viewing the assembly folder in Windows Explorer; for example, <%WINDIR%>\assembly, or use gacutil /l.

  • Microsoft.BizTalk.Adapters.BizUtil.dll

  • Microsoft.BizTalk.Adapters.CoreManagement.dll

  • Microsoft.BizTalk.Adapters.CoreReceiver.dll

  • Microsoft.BizTalk.Adapters.CoreTransmitter.dll

Adapter-specific files are installed in Program Files and Program Files\Common Files.

The following files are installed in C:\Program Files\Microsoft BizTalk Adapters for Enterprise Applications\PeopleSoft:

  • bin\BTAPeopleSoftTrace.cmd

  • config\btaPeopleSoftTrace.mof

  • config\GET_CI_INFO.pc

  • samples\

The folder Program Files\Common Files\Microsoft BizTalk Adapters for Enterprise Applications contains the following files:

  • bin\psosa.dll

  • bin\Microsoft.BizTalk.Adapters.CoreManagement.dll

  • bin\Microsoft.BizTalk.Adapters.CoreReceiver.dll

  • bin\Microsoft.BizTalk.Adapters.CoreTransmitter.dll

Installation Information for BizTalk Adapter for Siebel eBusiness Applications

Microsoft BizTalk Adapter for Siebel eBusiness Applications includes a receive adapter and a transmit adapter that interface supported databases and server systems to BizTalk Server.

  • The receive adapter listens for calls outbound from the server system. The receive adapter (the BizTalk Server Administration Receive Handler) does not require configuration and is used with Notifications (events).

  • The transmit adapter enables you to invoke a server system’s call from BizTalk Server. The transmit adapter (the BizTalk Server Administration Send Handler) configuration specifies the location of the SQL database.

BizTalk Adapter for Siebel eBusiness Applications provides support for Enterprise Single Sign-On (SSO). If you select to use SSO in the Transport Properties page, the credentials for the affiliate application in the SSO Credential database are used. An affiliate application represents an application—a back-end that requires credentials.

BizTalk Adapter for Siebel eBusiness Applications installation also includes samples in the \samples directory.

Installed Components

As BizTalk Adapter for Siebel eBusiness Applications finishes its installation, gacutil.exe registers the components in the global assembly cache (GAC). This is required by the .NET Framework.

You can verify the registration in the GAC by viewing the assembly folder in your explorer. For example: <%WINDIR%>\assembly or use gacutil /l.

  • Microsoft.BizTalk.Adapters.BizUtil.dll

  • Microsoft.BizTalk.Adapters.CoreManagement.dll

  • Microsoft.BizTalk.Adapters.CoreReceiver.dll

  • Microsoft.BizTalk.Adapters.CoreTransmitter.dll

Adapter-specific files installed in Program Files and Program Files\Common Files. The following files are installed under Program Files\Microsoft BizTalk Adapters for Enterprise Applications\Siebel.

  • bin\btaSiebelTrace.cmd

  • Classes\SBLJAccess.jar

  • config\Siebel\btaSiebelTrace.mof

  • samples\

The folder Program Files\Common Files\Microsoft BizTalk Adapters for Enterprise Applications contains the following files:

  • bin\sblcba.dll

  • Microsoft.BizTalk.Adapters.CoreManagement.dll

  • Microsoft.BizTalk.Adapters.CoreReceiver.dll

  • Microsoft.BizTalk.Adapters.CoreTransmitter.dll

Adding BizTalk Adapter for Siebel eBusiness Applications

For information about how to add BizTalk Adapter for Siebel eBusiness Applications to the BizTalk Server Administrator and start a BizTalk Server project using Siebel, see the section, "Adding the BizTalk Adapters for Enterprise Applications to BizTalk Server." If you have already added the adapter to BizTalk Server, you do not have to add the adapter again, and you do not have to connect to a database.

Depending on the type of orchestration you are building, see one of the following topics in the adapter documentation for more information:

  • Creating Siebel Send Handlers Using BizTalk Server

  • Creating Siebel Receive Handlers Using BizTalk Server

Installation Information for BizTalk Adapter for Oracle E-Business Suite

Microsoft BizTalk Adapter for Oracle E-Business Suite contains a receive adapter and a transmit adapter that interface supported databases and server systems to BizTalk Server. The receive adapter listens for calls outbound from the server system.

See the adapter documentation for information about how to use BizTalk Adapter for Oracle E-Business Suite and about the mapping between its model and the BizTalk Server model.

Single Sign-On

BizTalk Adapter for Oracle E-Business Suite provides support for Enterprise Single Sign-On (SSO). If you select to use SSO in the Transport Properties page, the credentials for the affiliate application in the SSO Credential database are used. An affiliate application represents an application—a back-end that requires credentials.

BizTalk Adapter for Oracle E-Business Suite installation also includes samples in the \samples directory.

Installed Components

As BizTalk Adapter for Oracle E-Business Suite finishes its installation, it registers its components in the GAC using gacutil.exe. This is required by the .NET Framework. You can verify the registration in the GAC by viewing the assembly folder in your explorer; for example: <%WINDIR%>\assembly or use gacutil /l.

  • Microsoft.BizTalk.Adapters.BizUtil.dll

  • Microsoft.BizTalk.Adapters.CoreManagement.dll

  • Microsoft.BizTalk.Adapters.CoreReceiver.dll

  • Microsoft.BizTalk.Adapters.CoreTransmitter.dll

Adapter-specific files are installed in Program Files and Program Files\Common Files. The following files are installed in Program Files\Microsoft BizTalk Adapters for Enterprise Applications\Oracle E-Business Suite:

  • bin\BTAOracleAppsTrace.cmd

  • config\btaOracleAppsTrace.mof

Adding BizTalk Adapter for Oracle E-Business Suite

For information about how to add BizTalk Adapter for Oracle E-Business Suite to the BizTalk Server Administrator and start a BizTalk Server project using Oracle E-Business Suite, see the section, "Adding the BizTalk Adapters for Enterprise Applications to BizTalk Server."

Note:
Refer to the releasenotes.html for any notes specific to this adapter.

If you have already added the adapter to Microsoft BizTalk Server, you do not have to add the adapter again, and you do not have to connect to a database.

Depending on the type of orchestration you are building, see one of the following topics:

  • Creating Oracle E-Business Suite Send Handlers

  • Creating Oracle E-Business Suite Receive Handlers

Installation Information for BizTalk Adapter for Oracle Database

Microsoft BizTalk Adapter for Oracle Database contains a receive adapter and a transmit adapter that interface supported databases and server systems to BizTalk Server. The receive adapter listens for calls that are outbound from the server system.

See the adapter documentation for information about how to use BizTalk Adapter for Oracle Database and about the mapping between its model and the BizTalk Server model.

Single Sign-On

BizTalk Adapter for Oracle Database provides support for Enterprise Single Sign-On (SSO). If you select to use SSO in the Transport Properties page, the credentials for the affiliate application in the SSO Credentials database are used. An affiliate application represents an application—a back-end that requires credentials.

BizTalk Adapter for Oracle Database installation also includes samples in the \samples directory.

Installed Components

As BizTalk Adapter for Oracle Database finishes its installation, it registers its components in the GAC using gacutil.exe. This is required by the .NET Framework. You can verify the registration in the GAC by viewing the assembly folder in your explorer; for example: <%WINDIR%>\assembly or use gacutil /l.

  • Microsoft.BizTalk.Adapters.BizUtil.dll

  • Microsoft.BizTalk.Adapters.CoreManagement.dll

  • Microsoft.BizTalk.Adapters.CoreReceiver.dll

  • Microsoft.BizTalk.Adapters.CoreTransmitter.dll

Adapter-specific files are installed in Program Files and Program Files\Common Files. The following files are installed in Program Files\Microsoft BizTalk Adapters for Enterprise Applications\Oracle Database.

  • bin\BTAOracleDBTrace.cmd

  • config\btaOracleDBTrace.mof

Installation Information for BizTalk Adapter for TIBCO Rendezvous

Microsoft BizTalk Adapter for TIBCO Rendezvous contains receive and transmit functionality that interface with supported databases and server systems to BizTalk Server.

  • The receive side listens for calls that are outbound from the server system.

  • The transmit side enables you to invoke a server system’s call from BizTalk Server.

See the adapter documentation for information about how to use Microsoft BizTalk Adapter for TIBCO Rendezvous and about the mapping between its model and the BizTalk Server 2006 model.

Installed Components

As BizTalk Adapter for TIBCO Rendezvous finishes its installation, it registers its components in the GAC using gacutil.exe. This is required by the .NET Framework. You can verify the registration in the GAC by viewing the assembly folder in your explorer; for example: <%WINDIR%>\assembly or use gacutil /l.

  • Microsoft.BizTalk.Adapters.TibcoRV

  • Microsoft.BizTalk.Adapters.TibcoRV.Common

  • Microsoft.BizTalk.Adapters.TibcoRV.Service

  • Microsoft.BizTalk.Adapters.TibcoRV.Properties

Adapter-specific files are installed in Program Files and Program Files\Common Files. The following files are installed in Program Files\Microsoft BizTalk Adapters for Enterprise Applications\TIBCO Rendezvous.

  • bin\BTATibcoRVTrace.cmd

  • bin\mbaRV.exe

  • bin\Microsoft.BizTalk.Adapters.TibcoRV.Common.dll

  • bin\Microsoft.BizTalk.Adapters.TibcoRV.dll

  • bin\Microsoft.BizTalk.Adapters.TibcoRV.Service.dll

  • bin\Microsoft.BizTalk.Adapters.BizUtil.dll

  • bin\Microsoft.BizTalk.Adapters.CoreManagement.dll

  • bin\Microsoft.BizTalk.Adapters.CoreReceiver.dll

  • bin\Microsoft.BizTalk.Adapters.CoreTransmitter.dll

  • bin\Microsoft.BizTalk.Adapters.TibcoRV.Properties.dll

  • Config\btaTibcoRVTrace.mof

  • Software Development Kit\

The folder Program Files\Common Files\Microsoft BizTalk Adapters for Enterprise Applications contains the following files:

  • bin\tibcorvcba.dll

  • Microsoft.BizTalk.Adapters.CoreManagement.dll

  • Microsoft.BizTalk.Adapters.CoreReceiver.dll

  • Microsoft.BizTalk.Adapters.CoreTransmitter.dll

Adding TIBCO.Rendezvous.dll to the GAC

BizTalk Adapter for TIBCO Rendezvous requires that you add the TIBCO Rendezvous TIBCO.Rendezvous.dll assembly to the GAC. The adapter triggers an exception and logs an appropriate message if this assembly is not installed.

You must use late binding to load assemblies so that the TIBCO Rendezvous assemblies do not fail when a particular version of the TIBCO.Rendezvous.dll and TIBCO.Rendezvous.net module are not present on the target computer. For instructions about how to use late bindings, see http://go.microsoft.com/fwlink/?LinkId=63509 and http://go.microsoft.com/fwlink/?LinkId=63512.
Runtime Component

Verify you have the TIBCO Rendezvous Runtime Component installed on your computer. The Runtime Component is the only component that you must install when you install TIBCO Rendezvous.

At a Visual Studio command prompt, change directories to the location of the TIBCO.Rendezvous.dll file. The path of this DLL in the default installation of TIBCO Rendezvous is C:\TIBCO\TIBRV\BIN\TIBCO.Rendezvous.dll.

At the command prompt, type the following:

C:\TIBCO\TIBRV\BIN > gacutil /i TIBCO.Rendezvous.dll

The TIBCO.Rendezvous.dll now shows GAC list. To view the list, in Control Panel, open Administrator Tools, open Microsoft .NET Framework Configuration, and then open Assembly Cache.

Installation Information for BizTalk Adapter for TIBCO Enterprise Message Service

Microsoft BizTalk Adapter for TIBCO Enterprise Message Service (EMS) contains receive and transmit functionality that interface with supported databases and server systems to BizTalk Server.

  • The receive side listens for calls that are outbound from the server system.

  • The transmit side enables you to invoke a server system’s call from BizTalk Server.

See the adapter documentation for information about how to use BizTalk Adapter for TIBCO EMS and about the mapping between its model and the BizTalk Server 2006 model.

Installed Components

As BizTalk Adapter for TIBCO Enterprise Message Service finishes its installation, it registers its components in the GAC using gacutil.exe. This is required by the .NET Framework. You can verify the registration in the GAC by viewing the assembly folder in your explorer; for example: <%WINDIR%>\assembly or use gacutil /l.

  • Microsoft.BizTalk.Adapters.TibcoEMS.dll

Adapter-specific files are installed in Program Files and Program Files\Common Files. The following files are installed under Program Files\Microsoft BizTalk Adapters for Enterprise Applications\TIBCO EMS.

  • bin\BTATibcoEMSTrace.cmd

  • Microsoft.BizTalk.Adapters.TibcoEMS.dll

  • Config\btaTibcoEMSTrace.mof

  • Software Development Kit\

The folder Program Files\Common Files\Microsoft BizTalk Adapters for Enterprise Applications\bin contains the following files:

  • Microsoft.BizTalk.Adapters.CoreManagement.dll

  • Microsoft.BizTalk.Adapters.CoreReceiver.dll

  • Microsoft.BizTalk.Adapters.CoreTransmitter.dll

Note:
You must use late binding to load assemblies so that the TIBCO EMS assemblies do not fail when a particular version of the TIBCO.EMS.dll is not present on the target computer. For instructions about how to use late bindings, see http://go.microsoft.com/fwlink/?LinkId=63509 and http://go.microsoft.com/fwlink/?LinkId=63512.

Adding TIBCO.EMS.dll API to the GAC

BizTalk Adapter for TIBCO EMS requires that you add the TIBCO.EMS.dll to the GAC. BizTalk Adapter for TIBCO EMS triggers an exception and logs an appropriate message if this assembly is not installed.

To add TIBCO EMS C# API to GAC

  1. Copy the TIBCO EMS C#API to your BizTalk computer.

  2. At a Visual Studio command prompt, change directories to the location of the C# API file.

  3. In a Visual Studio command prompt, type the following:

    C:\<TIBCO EMS Folder>bin> gacutil /i TIBCO.EMS.dll

The TIBCO.EMS.dll now shows in the C:\Windows\assembly listing. Or, in Control Panel, open Administrator Tools, open Microsoft .NET Framework 2.0 Configuration, and open Assembly Cache to view the GAC list.
Limitations

BizTalk Adapter for TIBCO EMS uses TIBCO.EMS.dll to communicate with the server. The following are limitations when you use the TIBCO.EMS.dll:

  • Message compression, which enables the TIBCO EMS client to send messages in a compressed form to EMS, is not available.

  • Encryption of messages between the adapter and the server is not available. The TIBCO.EMS.dll does not allow for SSL encryption using the OpenSSL libraries.

  • Administration API for EMS is not supported.

Activating Tracing for all the Adapters

The file name used with Windows tracing is up to the administrator. The application writes to the operating system, which ignores all logs until you want the logs for a particular back-end system. You do this by running a separate BizTalk Adapters for Enterprise Applications command file. One of the arguments for that command is the name of the file that will be used to capture the trace information. For more information, see the following section, "Using Windows Trace Event."

Trace files install in C:\Program Files\Microsoft BizTalk Adapters for Enterprise Applications\.

  • bin\BTATrace.cmd

  • config\btaTrace.mof

Using Windows Trace Event

The adapters log error, warning, and information messages to the Windows Event Viewer. You can view additional tracing messages by using the Event Tracing for Windows (ETW) tool. When ETW is enabled, it creates an *.etl file to receive the messages. This file is in binary format and must be converted to be read. To do this, you must have a consumer application available to interpret the *.etl file, for example, Windows tracerpt.exe or tracedmp.exe.

ETW Components

Event Tracing for Windows has three components:

Controller application: Activates and deactivates a provider. For example, tracelog.exe or logman.exe.

You set your PATH environment variable to point to the location of tracelog.exe. This makes sure that BTA<Adapter Name>Trace calls can locate tracelog.exe in the system. By default, BTA<Adapter Name>Trace searches the current path.

Note:
tracelog.exe is available from the Microsoft SDK and is compatible with the commands provided by Microsoft BizTalk Adapters for Enterprise Applications. To use logman.exe, see the logman documentation.

Consumer application: Reads logged events.

For the consumer application to be able to read the event in the .etl file, Event Tracing for Windows must dump them into that file. Typically this is done when the controller deactivates the tracing.

To use the consumer application without deactivating the trace, the controller must activate the trace with the real-time option, <Real time> = -rt.

Provider: Used to provide the event.

Each adapter includes five different providers. They are registered in Windows Management Instrumentation (WMI). To find the registered providers in the root\WMI\EventTrace path, you can use tools such as WMI CIM Studio.

The five providers enable you to log different kinds of messages:

  • Receiver Logging Provider: The <Trace element> switch is - receiver.

  • Receiver CastDetails Provider: The <Trace element> switch is - castDetailsReceive.

  • Transmitter Logging Provider: The <Trace element> switch is - transmitter.

  • Transmitter CastDetails Provider: The <Trace element> switch is - castDetailsTransmit.

  • Management Logging Provider: The <Trace element> switch is - management.

To use ETW, run the command for the specific adapter, BTA<Adapter Name>Trace.cmd. You use this command as follows:

BTA<Adapter Name>Trace <Trace element> -start [-cir <MB>| 
    -seq <MB>] [-rt] logfile
BTA<Adapter Name>Trace <Trace element> -stop

Where:

<Trace element> (required) is the kind of provider. The options are as follows:

-castDetailsTransmit

-transmitter

-castDetailsReceive

-receiver

-management

-start, -stop: Activate or deactivate the provider.

-cir <MB>: Size and kind of file. -cir is a circular file. <MB>: Size in megabytes.

-seq <MB>: Size and kind of file. -seq is a sequential file. <MB>: Size in megabytes.

-rt: Set the real-time mode on.

Logfile: Name of the log file (c:\rtlog.etl is the default).

For example: 

BTAXXXTrace -transmitter -start -cir 10 -rt c:\log\mylog.etl
BTAXXXTrace -transmitter -stop
Note:
You use the tracerpt.exe command to format the .etl files.

Adding the BizTalk Adapters for Enterprise Applications to BizTalk Server

Follow these steps to add the Microsoft BizTalk Adapters for Enterprise Applications to BizTalk Server.

To add Microsoft BizTalk Adapters for Enterprise Applications

  1. Click Start, point to Program Files, point to Microsoft BizTalk Server, and then select BizTalk Server Administrator to start the BizTalk Administrator Console.

  2. Expand Microsoft BizTalk Server, and then expand Platform Settings.

  3. Right-click Adapters, point to New, and then select Adapter.

  4. Type a name, for example, PeopleSoft.

  5. Select the name, in this example, PeopleSoft, from the Adapter list.

  6. Click OK.

-----------------------------------------------------------------------------------------------

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.

© 2006 Microsoft Corporation. All rights reserved.

Microsoft, MS-DOS, Windows, Windows Server, Windows Vista, BizTalk, and Visual Studio 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.