websphere business integration adapters - ibm · websphere business integration adapters adapter...

WebSphere Business Integration Adapters

Adapter for Ariba Buyer User GuideAdapter Version 3.0.x

��

Note!Before using this information and the product it supports, read the information in Appendix D, “Notices”, on page 87.

March 2003

This edition of this document applies to adapter version 3.0.x and to all subsequent releases and modifications untilotherwise indicated in new editions.

To send us your comments about IBM WebSphere Business Integration documentation, [email protected]. We look forward to hearing from you.

When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in anyway it believes appropriate without incurring any obligation to you.

© Copyright International Business Machines Corporation 2003. All rights reserved.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Integration broker compatibility

Supported on IBM WebSphere Business Integration Adapter Framework version2.2.0, IBM WebSphere Business Integration Toolset version 4.2.0, IBM WebSphereInterChange Server 4.2.0 (if the environment uses ISO Latin-1 data only), andWebSphere MQ Integrator Broker version 2.1.

See Release Notes for any exceptions.

© Copyright IBM Corp. 2003 iii

iv Adapter for Ariba Buyer User Guide

Contents

Integration broker compatibility . . . . . . . . . . . . . . . . . . . . . . . . . iii

About this document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viiAudience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viiRelated documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viiTypographic conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii

Chapter 1. Overview of the adapter . . . . . . . . . . . . . . . . . . . . . . . . 1Adapter architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1How the connector works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Chapter 2. Installing and configuring the adapter . . . . . . . . . . . . . . . . . . 7Installing related software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Overview of the installation process . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Installing the adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Configuring Ariba Buyer for the adapter . . . . . . . . . . . . . . . . . . . . . . . . . 10Configuring the adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Configuring the integration channel . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Starting the adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Stopping the adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Using log and trace files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Chapter 3. Understanding business objects . . . . . . . . . . . . . . . . . . . . 17Defining meta-data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Overview of business object structure . . . . . . . . . . . . . . . . . . . . . . . . . . 18Business objects for Ariba Buyer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Generating business objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Chapter 4. Generating business object definitions . . . . . . . . . . . . . . . . . 25Overview of the ODA for Ariba Buyer . . . . . . . . . . . . . . . . . . . . . . . . . . 25Generating Business Object Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . 25Uploading your files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Chapter 5. Troubleshooting and error handling . . . . . . . . . . . . . . . . . . 35Channel error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Connector error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37ODA error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Tracing messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Tips for troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Appendix A. Standard configuration properties for connectors . . . . . . . . . . . 43New and deleted properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Configuring Standard Connector Properties for WebSphere InterChange Server. . . . . . . . . . . . . 44Configuring Standard Connector Properties for WebSphere MQ Integrator . . . . . . . . . . . . . . 56

Appendix B. Connector Configurator . . . . . . . . . . . . . . . . . . . . . . . 65Using Connector Configurator in an internationalized environment. . . . . . . . . . . . . . . . . 65Starting Connector Configurator . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Choosing your broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Using a connector-specific property template . . . . . . . . . . . . . . . . . . . . . . . . 68Using Connector Configurator with ICS as the broker . . . . . . . . . . . . . . . . . . . . . 71Setting the configuration file properties (ICS) . . . . . . . . . . . . . . . . . . . . . . . . 73Setting the configuration file properties (WebSphere MQ Integrator Broker) . . . . . . . . . . . . . . 78

© Copyright IBM Corp. 2003 v

Using standard and connector-specific properties with Connector Configurator. . . . . . . . . . . . . 81Completing the configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Appendix C. Connector feature list . . . . . . . . . . . . . . . . . . . . . . . 83Event notification features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Service call request handling features . . . . . . . . . . . . . . . . . . . . . . . . . . . 84General features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Appendix D. Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87Programming interface information . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Trademarks and service marks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

vi Adapter for Ariba Buyer User Guide

About this document

The IBM(R) WebSphere(R) Business Integration Adapter product is a suite ofsoftware integration products that supply connectivity for leading e-businesstechnologies and enterprise applications. It includes:v Prebuilt components for common business integration processesv Tools and templates for customizing and creating componentsv A flexible, easy-to-use platform for configuring and managing the components

This document describes the installation, configuration, troubleshooting, andbusiness object development for the IBM WebSphere Business Integration Adapterfor Ariba Buyer.

AudienceThis document is for consultants, developers, and system administrators who usethe adapter at customer sites.

Related documentsThe complete set of documentation available with this product describes thefeatures and components common to all WebSphere Business Integration Adapterinstallations, and includes reference material on specific components.

To access the documentation, go to the directory where you installed the productand open the documentation subdirectory. If a welcome.html file is present, open itfor hyperlinked access to all documentation. If no documentation is present, youcan install it or read it directly online at one of the following sites:v If you are using WebSphere MQIntegrator as your integration broker:

http://www.ibm.com/software/websphere/wbiadapters/infocenterv If you are using InterChange Server as your integration broker:

http://www.ibm.com/websphere/integration/wicserver/infocenterv For adapter information:

http://www.ibm.com/websphere/integration/wbiadapters/infocenter

The documentation set consists primarily of Portable Document Format (PDF) files,with some additional files in HTML format. To read it, you need an HTMLbrowser such as Netscape Navigator or Internet Explorer, and Adobe AcrobatReader 4.0.5 or higher. For the latest version of Adobe Acrobat Reader for yourplatform, go to the Adobe website (www.adobe.com).

Typographic conventionsThis document uses the following conventions:

courier font Indicates a literal value, such as a command name, filename, information that you type, or information that thesystem prints on the screen.

italic, italic Indicates a new term the first time that it appears, a variablename, or a cross-reference.

© Copyright IBM Corp. 2003 vii

http://www.ibm.com/websphere/integration/wbiadapters/infocenter

http://www.ibm.com/websphere/integration/wicserver/infocenter


blue text Blue text, which is visible only when you view the manualonline, indicates a cross-reference hyperlink. Click any bluetext to jump to the object of the reference.

{ } In a syntax line, curly braces surround a set of options fromwhich you must choose one and only one.

| In a syntax line, a pipe separates a set of options from whichyou must choose one and only one.

[ ] In a syntax line, square brackets surround an optionalparameter.

... In a syntax line, ellipses indicate a repetition of the previousparameter. For example, option[,...] means that you canenter multiple, comma-separated options.

< > Angle brackets surround individual elements of a name todistinguish them from each other, as in<server_name><connector_name>tmp.log.

/, \ In this document, backslashes (\) are used as the conventionfor directory paths. For UNIX installations, substitute slashes(/) for backslashes. All product pathnames are relative to thedirectory where the connector for Ariba Buyer is installed onyour system.

%text% and $text Text within percent (%) signs indicates the value of theWindows text system variable or user variable. Theequivalent notation in a UNIX environment is $text,indicating the value of the text UNIX environment variable.

viii Adapter for Ariba Buyer User Guide

Chapter 1. Overview of the adapter

This chapter describes the IBM WebSphere Business Integration adapter for AribaBuyer and the associated system architecture.

The adapter for Ariba Buyer consists of a connector, the adapter framework, andan integration channel. Together they enable Ariba Buyer to exchange informationwith an integration broker such as the WebSphere MQ Integrator Broker or theWebSphere InterChange Server (ICS).

The adapter for Ariba Buyer enables integration to version 8.0 of Ariba Buyer. It isnot compatible with earlier versions of the application. The channel componentruns on all platforms that support Ariba Buyer, whether or not they support theadapter framework. The connector component runs on all platforms that supportthe adapter framework.

For more information about the relationship of the integration broker to theadapter, see IBM WebSphere Business Integration System Administration Guide.

This chapter contains the following sections:v “Adapter architecture” on page 1v “How the connector works” on page 4

Adapter architectureThe adapter for Ariba Buyer enables Ariba Buyer to communicate with externalapplications such as SAP, Oracle Financials, and PeopleSoft.

Components

The adapter includes three primary components:v Integration channel

Required by Ariba Buyer to communicate with target applications. It runs as acomponent of Ariba Buyer and communicates with the connector remotely.

v Connector

Acts as an intermediary between the integration broker and the application inthe transfer of data. The connector is meta-data-driven.

v Object Discovery Agent (ODA)

A design-time tool that reads meta-data exported by the application andconverts it into business object definitions. The connector uses these definitionsat run time to convert application data into business objects.

Figure 1 on page 2 shows how these adapter components work together.

© Copyright IBM Corp. 2003 1

Connectors and nodes

Ariba Buyer may be run in a multi-node configuration with the nodes all on onemachine, or distributed across many machines in a multi-serverconfiguration—provided that all the servers run the same operating system. In amulti-server configuration, each machine has at least one node. However, there isonly one instance of the connector, regardless of the number of nodes.

Each node runs in its own process and communicates with its own instance of theintegration channel, but all nodes communicate with the same Ariba Buyerapplication database.

Run-time event flows

For events originating from Ariba Buyer:1. A message object is sent to the integration channel of a specific Ariba Buyer

node.

me

ta-

da

ta

Connector

Machine 2Machine 1

Buyer 8.0

Database

Broker

AS

BO

Broker

Repository

File

system

repository

WBIAAB

ODA

BO

DesignerBO Definition

Java VM

AMF

Buyer 8.0

Channel

Java VM

AMF

Buyer 8.0

Channel

Java VM

AMF

Buyer 8.0

Channel

Message

Message

Message

Figure 1. Adapter architecture

2 Adapter for Ariba Buyer User Guide

2. The integration channel sends the message object to the connector.3. The connector maps the business object data in the message object to an

application-specific business object (ASBO), using a business object definitioncreated by the ODA at design time. It then sends the ASBO to the integrationbroker.

For events originating from the integration broker:1. The broker sends an application-specific business object to the connector.2. The connector determines whether the application-specific business object is a

response to an earlier request by checking for the existence of a reply key in theobject.

3. The application-specific business object is converted to a message object.4. If the application-specific business object is a response to a previous request,

the message object is routed to the node that originated the request. Otherwise,the message object is routed to the first available node.

Integration ChannelThe integration channel is the link between Ariba Buyer and the connector. AribaBuyer communicates with the channel using the Ariba Messaging Framework(AMF). The AMF is used by the application to send message objects to the channel,and by the channel to send objects to the application.

Communication between the AMF and the channel occurs whenever:v An integration event defined on the channel is triggered within Ariba Buyer. The

AMF can trigger events synchronously or asynchronously.v A service call is received from the integration broker. The call is sent to the first

available channel node.v The meta-data changes within Ariba Buyer. This happens only on the primary

node and only in development mode.

Service call events are sent by the connector to the first available channel node,which relays the event to the application.

For more information, see Chapter 3, “Understanding business objects”, on page 17,and Chapter 4, “Generating business object definitions”, on page 25.

ConnectorConnectors consist of two parts: the application-specific component and the controllerand communications framework. The application-specific component contains codetailored to a particular application or technology (in this case, Ariba Buyer). Thecontroller and communications framework, whose code is common to allconnectors, act as an intermediary between the integration broker and theapplication-specific component by providing the following services:v Receives and sends business objectsv Manages the exchange of startup and administrative messages

The connector for Ariba Buyer communicates with the application through theintegration channel.

Chapter 1. Overview of the adapter 3

The integration channel and connector communicate with each other at run time.The message object originates in an Ariba Buyer node and is passed to theintegration channel through the AMF. The integration channel sends the messageobject to the connector.

The connector maps the business object data contained in the message object to anapplication-specific business object, using a definition stored in the brokerrepository, and sends it to the broker. It may also receive business objects from thebroker for delivery to Ariba Buyer. These business objects are sent back throughthe channel instance for the Ariba Buyer node that initiated the exchange.


Object Discovery Agent (ODA)The Object Discovery Agent (ODA) is a design-time tool used to create businessobject definitions from Ariba Buyer-specific meta-data. The ODA uses thatmeta-data to build the business object definitions.

Two types of meta-data are exported by the integration channel:v Class meta-data, which represents the business object defined in the Ariba Buyer

object model.v Message meta-data, which represents the integration messages defined in Ariba

Buyer. These messages refer to Buyer business objects; that is, Messagemeta-data refers to Class meta-data.

Meta-data can be exported from the primary node of an Ariba Buyer instancerunning in development mode. The ODA reads these files and uses the informationto create business object definitions in the integration broker repository. During runtime, the connector can use these definitions to transform message objects intoapplication-specific business objects.

Ariba Buyer provides an interface that notifies the integration channel about anychanges to the meta-data. The channel receives this information from the AMFthrough a listener and automatically saves it to the meta-data repository.

Note: You can regenerate the repository by shutting down the Ariba Buyer serverand running the initdb -reshapedb command. To regenerate the meta-data,the system must be in development mode. For details, refer to the AribaBuyer 8.0 documentation.


How the connector worksThe connector for Ariba Buyer is bi-directional. It can process events originatingfrom Ariba Buyer applications, as well as requests sent by the broker to theapplication.

For event notifications, Ariba Buyer provides a mechanism using message handlersin the integration channel. To send an event, an Ariba Buyer node invokes amessage handler on the associated channel instance, which in turn contacts theconnector. All events are thus sent to the connector without the need for any otherform of notification, such as polling.


For request processing, the connector for Ariba Buyer processes the requestscoming from the integration broker in the form of business objects. It sends amessage object to the Subscribe message handler in the integration channel, whichin turn sends it to the application.

The connector for Ariba Buyer follows the meta-data design principles forWebSphere Business Integration adapter connectors. This means new businessobjects can be defined without additional coding or customization at the connectorcode level. For more information, see Chapter 3, “Understanding business objects”,on page 17.

Processing eventsThe following sections describe how the connector processes application events.

Event detection and notificationNo event detection is required for Ariba Buyer.

The application notifies the integration channel of an event by sending it amessage object containing the event data. When the channel receives the messageobject, it sends it to the connector, where the business object handler converts themessage into an application-specific business object for transmission to theintegration broker. The channel’s message handlers can simultaneously receive andforward a number of events, each of which is sent by a different Buyer thread.

Ariba Buyer events may be asynchronous or synchronous. When the applicationsends an event of either type to the channel, it also stipulates the return businessobject that will deliver a response.

Synchronous events

When Ariba Buyer sends a synchronous event to the integration channel, it sendsthe message object to the connector and retains control of the Buyer thread while itwaits for a response. When the connector receives the response application-specificbusiness object, it transforms this object into a message object and sends it back tothe waiting channel node.

If the connector goes down before the synchronous response is returned to thechannel, the event generates an error. For more information, see Time-outs inChapter 5, “Troubleshooting and error handling”, on page 35.

Asynchronous events

When Ariba Buyer sends an asynchronous event to the integration channel, thechannel will start a timeout process if timeout is specified for the message. Thechannel then sends the message object to the connector and returns control back tothe Buyer thread that invoked it. When the connector receives the responseapplication-specific business object, it transforms this object into a message objectand sends it back to the originating channel node.

If no response is sent for an asynchronous event, or the response is sent very late,the event times out. For more information, see Time-outs in Chapter 5,“Troubleshooting and error handling”, on page 35.

Service Call Request processingWhenever a Service Call is initiated on Ariba Buyer, the connector receives theapplication-specific business object from the integration broker, transforms it into a

Chapter 1. Overview of the adapter 5

message object, and passes it to the first available node. The channel instance forthe receiving node receives the message object and passes the data to Ariba Buyerusing the Ariba Buyer-defined APIs.

Status updatesIn general, errors are logged by the failing component and the originatingcomponent is notified.

Errors that occur in the integration channel, as well as any messages, are logged bythe application API and appear in the Ariba Buyer log file(AribaBuyerNodexLog.txt).

Errors that occur in the connector, along with any messages, appear in theconnector log file, and the connector framework is informed. You specify the nameof this file in the Connector Configurator at system setup.

For more information, see Chapter 5, “Troubleshooting and error handling”, onpage 35.


Chapter 2. Installing and configuring the adapter

This chapter describes how to install and configure the IBM WebSphere BusinessIntegration adapter for Ariba Buyer and how to configure the application to workwith the adapter. It contains the following sections:v “Installing related software” on page 7v “Overview of the installation process” on page 8v “Installing the adapter” on page 8v “Configuring Ariba Buyer for the adapter” on page 10v “Configuring the adapter” on page 11v “Configuring the integration channel” on page 12v “Starting the adapter” on page 14v “Stopping the adapter” on page 15v “Using log and trace files” on page 15

Installing related softwareBefore you install the adapter, your system should have the following softwareinstalled and configured:

Platform software:

One of the following application platforms:v Windows: 2000, NT 4.0v UNIX: AIX 5.1, Solaris 7.0 or 8.0

WebSphere software:

One of the following integration brokers:v IBM WebSphere InterChange Server 4.2v IBM WebSphere MQ Integrator Broker 2.1

Note: For instructions on installing your integration broker and its prerequisites,see the following guides. For WebSphere InterChange Server (ICS), see IBMWebSphere InterChange Server System Installation Guide for UNIX or forWindows. For WebSphere MQ Integrator Broker, see IBM WebSphere BusinessIntegration Adapters Implementation Guide for MQ Integrator.

You may install the adapter before or after you install Ariba Buyer 8.0. However,the adapter must be installed before you configure the application. Theconfiguration process for Ariba Buyer needs to copy files from the adapterinstallation directory to the Ariba Buyer installation directory.

After you install the adapter, you are ready to configure Ariba Buyer 8.0. Fordetails, refer to the documentation for Ariba Buyer 8.0.


Overview of the installation processThese are the steps you follow to install the adapter for Ariba Buyer.1. Install the integration broker.2. Install Ariba Buyer.

Note: Select No when you are prompted to proceed to the Ariba Buyerconfiguration program at the end of the installation.

3. Install the adapter for Ariba Buyer.4. Configure and initialize Ariba Buyer.

It is assumed that steps 1 and 2 are complete at this time. The installationinstructions in this guide cover steps 3 and 4.

Installing the adapterThe adapter for Ariba Buyer is only available as an ESD (electronic softwaredelivery) download from the Web. Use Passport Advantage to download the setupfiles for IBM WebSphere Business Integration Adapter for Ariba Buyer to yoursystem. The product part number also refers to the ESD image.

The release notes for the installation are available on the InfoCenter website at:http://www.ibm.com/websphere/integration/wbiadapters/infocenter

Windows installation

If you are installing the adapter on a Windows system, the file download utilitycopies an executable file containing a set of installation files onto your machine.

To install the adapter:1. Double-click the executable file in your setup directory. It extracts several files,

including the setup file and a Read.me file.2. Run setupwin32.exe from the setup directory. The InstallShield appears.3. To install the adapter files, step through the screens by clicking Next>.

Note: You will be asked to select a file location. If you are running ICS, youmust install these files in the same product directory in which youinstalled ICS. This is \Crossworlds by default.

If you are running WebSphere MQ Integrator broker, you must installthese files in the same product directory in which you installed theWebSphere Business Integration adapter package. This is\WebSphereAdapters by default.

Use the browse button in the InstallShield to locate the correct directoryand select it.



UNIX installation

If you are installing the adapter on a UNIX system:1. Download the .tar executable file for AIX or Solaris to your setup directory.2. Extract the setup and Readme files by running this command:

tar -xvf <filename>.tar

3. Run the setup file.For Solaris: run setupsolarisSparc.bin

For AIX: run setupAIX.bin

Note: You will be asked to select a file location. If you are running ICS, you mustinstall these files in the same product directory in which you installed ICS.This is \Crossworlds by default.

If you are running WebSphere MQ Integrator broker, you must install thesefiles in the same product directory in which you installed the WebSphereBusiness Integration adapter package. This is \WebSphereAdapters bydefault.

Installed file structureTable 1 on page 10 shows the file structure used by the adapter and lists the filesthat are installed on the system.

Figure 2. InstallShield for Ariba Buyer

Chapter 2. Installing and configuring the adapter 9

Notes:

1. This document uses (\) backslashes as the convention for directory paths. ForUNIX installations, substitute slashes (/) for backslashes.

2. All product path names are relative to the directory where the product isinstalled on your system.

Table 1. Adapter files installed on system

Subdirectory of %Prod_Dir% Description

_uninstall Contains the files for uninstalling the adapter

connectors\Buyer Contains:

v The adapter CWBuyer. jar file, version 3.0.0, which has the connector code

v The start_Buyer.bat file (WIN) or start_Buyer.sh file (UNIX)

v The \Buyer directory that will be copied to the Ariba Buyer installationdirectory

connectors\messages Contains the BuyerConnector.txt file, which lists error and othermessages.

legal\license Contains a text file with the terms of the adapter license agreement.

ODA\Buyer Contains:

v The Object Discovery Agent BuyerODA.jar file, version 3.0.0, which hasthe ODA code

v The start_BuyerODA.bat file (WIN) or start_BuyerODA.sh file (UNIX)

ODA\messages Contains the BuyerODAAgent.txt file, which lists error and other messages.

repository\Buyer Contains the CN_Buyer.txt file, which specifies connector configurationproperties.

Completing the installationThe \Buyer subdirectory resides under the \connectors directory (see Table 1). Thefiles in this subdirectory contain certain configuration information for the adapterchannel.

To complete the installation, copy this subdirectory on top of the Ariba Buyer 8home directory and update the class path, as follows.1. Copy the \Buyer subdirectory from the source directory on top of \<Ariba

Buyer Server root>\; for example, \Ariba\app\Buyer\2. Modify \Ariba\app\Buyer\classes\classpath.txt by adding these entries:

#IBM ERP Channel implementation

classes\IBMChannel.jar

classes\ABCommon.jar

3. Save the file. You are now ready to configure Ariba Buyer.

Configuring Ariba Buyer for the adapterThe next task is to configure Ariba Buyer to recognize the adapter. You use theAriba Buyer Configure tool to set the correct enterprise application integration(EAI) channel in Ariba Buyer. as follows.1. In the Ariba Buyer Configuration window, check EAI Channel and click Next.2. Select your database, for example, IBM DB2 UDB, and click Next.3. Enter the database properties for your database and click Next.


4. If you have the Ariba Buyer 8 Hot Fix Pack 1 installed, select IBM WBIAdapter as your EAI Channel and set the Configuration File Location as:<Ariba Buyer Server root>/channels/IBM

5. If you do not have the Ariba Buyer 8 Hot Fix Pack 1 installed:Select Other as your EAI Channel.Set IBM as the channel name by setting the Configuration File Location as:<Ariba Buyer Server root>/channels/IBM

6. Continue with the configuration for Ariba Buyer 8.0.

Note: The adapter is only used if you select an ERP Type other than Basic CSVconfiguration during configuration.

Configuring the adapterThe connector component of the adapter has two types of configuration properties:standard configuration properties and application-specific configuration properties.You must set the values of these properties before running the connector.

Standard configuration propertiesTo configure standard connector properties, use the Connector Configurator tool.Details are given in Appendix B, “Connector Configurator”, on page 65. This toolprovides a graphical user interface for configuring the connector. Click on theStandard Config Properties tab to add or modify configuration properties.

When you have finished specifying values for the connector’s configurationproperties, Connector Configurator saves the values in the adapter repository (forICS) or generates a configuration file and places it in the adapter’s local repository(for WebSphere MQ Integrator Broker).

A connector obtains its configuration values at startup. During a run-time session,you may want to change the values of one or more connector properties.v Changes to some connector configuration properties, such as AgentTraceLevel,

are dynamic, taking effect immediately.v Changes to other connector properties are static, requiring component restart or

system restart after a change.

To determine whether a property is dynamic or static, refer to the update methodcolumn in Connector Configurator.

Application-specific configuration propertiesApplication-specific connector configuration properties provide information neededby the connector at run time. They also provide a way for you to change staticinformation or logic within the connector without having to recode and rebuild it.

To configure these properties, use Connector Configurator. Click the ApplicationConfig Properties tab to add or modify configuration properties. For moreinformation, see Appendix B, “Connector Configurator”, on page 65.

Table 2 lists the application-specific configuration properties for the connector,along with their descriptions and possible values.


Table 2. Application-specific configuration properties for Ariba Buyer

Property Description Possible values Default value Required

Nodes The Ariba Buyer nodenames and fully qualified

machine names

<url1>:Node1;<url2>:Node2;...<urln>:NodeN

None Yes

ConnectorPort The connector RMI port Any open port - mustmatch the value specified inthe Parameters.table file

2226 Yes

ChannelPort The channel RMI port Any open port - mustmatch the value specified inthe Parameters.table file

2225 Yes

DateFormats Specifies valid date formats <format>;<format>;... EEE MMM ddHH:mm:ss zyyyy;M/d/yy;M/d/yyyy;M-d-yy;M-d yyyy;yyyyMMdd

No

VariantMappings Correlates user-definedvariant names with specificERP types. Maps variantand partition-specificbusiness object names to amore generic businessobject name.

<variant name>=<varianttype prefix>;<variantname>=<variant typeprefix>;...

None No

Note: For more information on valid date formats, which are determined by theJava API, see the websitehttp://java.sun.com/j2se/1.3/docs/api/java/text/SimpleDateFormat.html.

Configuring the integration channelThe integration channel must be configured for two purposes:v Communicating with the connectorv Handling integration events

Configuring channel propertiesThe integration channel configuration properties provide the information necessaryfor the channel to communicate with the connector at run time. These propertiesare set in the Parameters.table text file, located in the Ariba Buyer installationdirectory:

\Ariba\app\Buyer\Server\config

To configure the integration channel properties, open the Parameters.table file andenter the property values.

Table 3 on page 13 lists the required configuration properties, along with adescription and possible value for each one.


Table 3. Application-specific configuration properties for the integration channel

Property Description Possible values Default value Required

ConnectorURL The hostname of themachine on which theconnector is running

Fully qualified machine nameor IP address

localhost Yes

ConnectorPort The connector RMI port Any open port - must matchthe value set for the connector

2226 Yes

ChannelPort The channel RMI port Any open port - must matchthe value set for the connector

2225 Yes

MetadataRepos The location where generatedmeta-data will be stored

Relative from\Ariba\app\Buyer\Server ora fully qualified directory path

“/channels/IBM/metadata”;

Yes

Configuring integration eventsEach integration event must be configured before it can be sent through theintegration channel. Events are configured in two configuration files,MessageDefinition.table and MessageConfiguration.table.

Ariba Buyer supplies a number of out-of-the-box integration events, which arelisted in the Ariba Buyer Configuration Reference Guide. However, events that are notconfigured on the integration channel will not be sent through the adapter forAriba Buyer.

The MessageDefinition.table file contains general information for each integrationevent in a given ERP variant type. Ariba Buyer supplies a table entry for a base setof out-of-the-box integration events for each of these variants.

The MessageConfiguration.table file contains more specific information, includingchannel-specific data, for each integration event in a given partition. An entry foreach event must be created in this table.

A sample MessageConfiguration.table entry is shown below.PurchaseOrderPush={

Channel={Name=IBM;Operation="Update Elements Only";Verb=Retrieve;Timeout=300000;

};LoggingName=PurchaseOrderEvent;MessageParameters={

Request={MergedSchemaName="ariba.integration.param.PurchaseOrderPush";Parameters={EventSource="ibmcsvp:PO:SAP3.1H";};SchemaName=ariba.integration.param.SimpleParams;

};};TopicName=PurchaseOrderPush;ExecutionNode="Node2";

};

Every MessageConfiguration.table entry contains a section for channel parameters,shown as the first subentry in the example above. Table 4 on page 14 lists the validparameters and values for the integration channel.


Table 4. Event configuration parameters for the integration channel

Parameter Description Possible values

Name Specifies the ERP integration channel name. IBM

Operation Specifies the operations that Ariba Buyer canperform. Refer to“Business object verbs” on page 19for more details.

Create, Delete, Load, Load and Delete,Update, Update and Delete,UpdateElementsOnly

Verb Specifies the operations that the destinationapplication can perform. Refer to“Business object verbs” on page 19for more details.

Create, Delete, Retrieve, UpdateABUpdate, Load, Update and Delete,UpdateElementsOnly

Timeout Specifies the timeout for an Ariba Buyer eventprocess. The value is designated in milliseconds.

Whole number >=0Default value is 0, which means notimeout for that event.

For complete details on configuring the other parameters for integration events,refer to the Ariba Buyer Configuration Reference Guide.

Starting the adapterTo start the adapter for Ariba Buyer, you must:1. Start Ariba Buyer 8.0, which starts up the integration channel.2. Start the connector.

Note: When you want to add or reload business object definitions, you add a thirdstep: starting the ODA.

Starting Ariba BuyerThe procedure for starting Ariba Buyer depends on the node configuration of yoursystem. Please refer to the documentation for Ariba Buyer 8.0 for details.

Each Buyer node starts an instance of the integration channel. When the channelstarts, it attempts to connect to the connector. The channel starts whether or notthe connector is running.

Starting Ariba Buyer connectorThe connector starts when the start_buyer.bat or start_buyer.sh script is run. Thestart_buyer script requires the BUYERPATH variable to be set for startup to occurcorrectly. It should point to <Ariba Server root>; for example,

set BUYERPATH=C:\Ariba\app\Buyer\Server

Note: If the Ariba Buyer application and the connector are installed on separatemachines, the file system of the Ariba Buyer machine must be mapped orotherwise made accessible to the file system of the machine on which theconnector is installed, so that BUYERPATH can be set.

If the connector is running with the WebSphere MQ Integrator broker, it alsorequires the -c option to be set, as shown below.

The start command for the connector has this format:


Table 5. Logging and tracing message levels for the integration channel

Message type Description Default

Information Logs key initialization and termination steps, message deliveryand receipts events.

On

Debug Logs method calls and critical points within each call. Off

Error Logs all error conditions within the channel or detected by it. On

The connector uses the adapter framework to log error, informational and tracemessages. Error and informational messages are recorded in a log file, and thetrace messages and trace level (0 to 5) are recorded in a trace file.

Table 6 describes the type of messages logged at each tracing level.

Table 6. Trace file tracing levels

Trace Level Description

0 v Logs errors and fatal errors from the Ariba Buyer ODA

v Logs warnings that require a system administrator’s attention

v Logs important messages from the application

1 Traces all entering and exiting messages for method

2 Traces the ODA’s properties and their values

3 Traces the names of all business objects

4 Traces business object properties and the values received

5 v Indicates the ODA initialization values for all of its properties

v Traces the business object definition dump

You configure both the log and trace files names, as well as the trace level, inConnector Configurator. Refer to Appendix B, “Connector Configurator”, on page65 for details.

The ODA has no logging capability; error messages are sent directly to the userinterface. Trace files and the trace level are configured in Business Object Designer.The process is described in “Configure the agent” on page 27. The ODA tracelevels are the same as the connector trace levels, shown in Table 6 above.

For more details on error handling and troubleshooting, refer to Chapter 5,“Troubleshooting and error handling”, on page 35.


Chapter 3. Understanding business objects

This chapter describes the structure of business objects, how the adapter processesthe business objects, and the assumptions the adapter makes about them.

The chapter contains the following sections:v “Defining meta-data” on page 17v “Overview of business object structure” on page 18v “Business objects for Ariba Buyer” on page 18v “Generating business objects” on page 23

Defining meta-dataThe adapter for Ariba Buyer is meta-data-driven. In the WebSphere businessintegration system, meta-data is defined as application-specific informationexported by Ariba Buyer that describes its data structures. The meta-data is used toconstruct business object definitions which the connector uses at run time to buildbusiness objects.

A meta-data-driven adapter handles each business object that it supports accordingto the meta-data encoded in the business object definition. This enables the adapterto handle new or modified business object definitions without requiringmodifications to the code. Any changes are made through the Object DiscoveryAgent in Business Object Designer.

Application-specific meta-data includes the structure of the business object and thesettings of its attribute properties. Actual data values for each business object areconveyed in message objects at run time.

The adapter makes assumptions about the structure of its supported businessobjects, the relationships between parent and child business objects, and the formatof the data. Therefore, it is important that the structure of the business objectexactly match the structure defined for the corresponding object within AribaBuyer or the adapter will not be able to process business objects correctly.

Note: The structure of the business object should never be modified usingBusiness Object Designer.

If you need to make changes to the business object structure, make them to thecorresponding object in Ariba Buyer and then export the changes to the file systemrepository for input into the ODA. Refer to Chapter 4, “Generating business objectdefinitions”, on page 25 for details.

For more information on modifying business object definitions, see WebSphereBusiness Integration Adapters Business Object Development Guide.


Overview of business object structureIn the WebSphere business integration system, a business object definition consistsof:v A type namev Supported verbsv Attributes

An application-specific business object is a particular instance of a business objectdefinition. It reflects a specific application’s data structure and attribute properties.

Some attributes, instead of containing data, point to child business objects orarrays of child business objects that contain the data for these objects. Keys relatethe data between the parent record and child records.

Business objects for adapters can be flat or hierarchical. A flat business object onlycontains simple attributes, that is, attributes that represent a single value (such as astring) and do not point to child business objects. A hierarchical business objectcontains both simple attributes and child business objects or arrays of childbusiness objects that contain attribute values.

A cardinality 1 container object, or single-cardinality relationship, occurs when anattribute in a parent business object contains a single child business object. In thiscase, the child business object represents a collection that can contain only onerecord. The attribute type is the same as that of the child business object.

A cardinality n container object, or multiple-cardinality relationship, occurs whenan attribute in the parent business object contains an array of child businessobjects. In this case, the child business object represents a collection that cancontain multiple records. The attribute type is the same as that of the array of childbusiness objects.

Business objects for Ariba BuyerThe structure of application-specific business objects in the WebSphere BusinessIntegration system is set by Ariba Buyer and mirrors the structure of the AribaBuyer message object. Ariba Buyer currently supports two types of message object:v Request-Response: Used to send data to an ERP application or to request data

from onev Subscribe: Used to receive unsolicited data from an ERP application

These message types are converted to business objects of one type or the other.Most Ariba Buyer events are of the request-response type.

Business objects inherit their names from the matching Ariba Buyer messageobjects. The names combine structural divisions, using the Ariba variant andpartition names, and topic name. For example, SAP_NA_PurchaseOrderPush.

Required fields for business objectsBusiness objects contain two sets of fields:v A set of required data fields common to all, andv An additional set of fields that varies according to the message type


The common fields are described in Table 7, and the additional fields in Table 8and Table 9.

Note: The additional fields in these two tables are mutually exclusive. You woulduse one set or the other, but not both.

Table 7. Required fields for all business objects

Required field Type Description

Variant String Name of the variant that sent or will receive this message.

Partition String Name of the partition that sent or will receive this message.

TopicName String Uniquely identifies an event. Default key value when creating businessobject definitions.

ReplyKey String Uniquely identifies the message. Generated by the integration channel forasynchronous events only.

Table 8 lists the additional fields required for all business objects ofRequest-Response type only.

Table 8. Required fields for Request-Response business objects

Required field Cardinality Type Description

RequestSchema 1 Specified by MergedSchemaName (if present)or SchemaName in MessageConfiguration.table.

Specifies request data types.

PullSchema_<n> N One PullSchema exists for eachSignature.Pull.Schema type defined inMessageDefinition.table.

Specifies response data types.

Table 9 lists the additional fields required for all business objects of Subscribe typeonly.

Table 9. Required fields for Subscribe business objects

Required field Cardinality Description

SubscribeSchema N An attribute specifies the inbound object type for each schemadefined in the MessageDefinition.table.

Business object verbsEvery business object contains a verb, which describes how the data in theapplication-specific business object should be handled by the receiving application.Ariba Buyer defines a set of operations that are similar to verbs, but that describeonly how incoming data should be loaded into the Ariba Buyer database.

Verbs and operations are handled as follows:v For synchronous Request-Response events: The Request application-specific

business object verb is set to the value of the Verb parameter defined in theChannels section of MessageConfiguration.table. The verb describes the intendedaction at the destination application. The action that is performed on the datareturned in the Response application-specific business object is the value of theOperation parameter defined in the Channels section ofMessageConfiguration.table. This sequence is illustrated in Figure 3 on page 20.

Chapter 3. Understanding business objects 19

v For asynchronous Request-Response events: The Request application-specificbusiness object verb is set to the value of the Verb parameter defined in theChannels section of MessageConfiguration.table. The verb describes the intendedaction at the destination application. The destination application sets the verb ofthe Response application-specific business object. The action that is performedon the data returned in the Response application-specific business object isdetermined by converting the verb in this application-specific business object tothe operation value given in Table 10 on page 21. This sequence is illustrated inFigure 4.

v For Subscribe events: The source application sets the business object verb. Theaction that is performed on the data received is determined by converting thebusiness object verb to the operation value given in Table 10 on page 21. Thissequence is illustrated in Figure 5 on page 21.

Ariba

Buyer

Destination

Application

SynchRREvent

Verb = X

Operation = Y

Buyer

Database

A

d

a

p

t

e

r

A

d

a

p

t

e

r

Adapter to sets Verb in

Request ASBO to MC.table

Verb

Adapter applies Verb in

Request ASBO to Destination

Application

Adapter applies Operation

in MC.table to Buyer

Request

ASBO

Response

ASBO

Broker

Request

ASBO

Response

ASBO

MessageConfiguration.table

Figure 3. Synchronous Request-Response events

Ariba

Buyer

Destination

Application

AsynchRREvent

Verb = X

Buyer

Database

A

d

a

p

t

e

r

A

d

a

p

t

e

r


Request ASBO to MC.table

Verb

Adapter applies Verb in

Request ASBO to Destination

Application

Adapter translates Verb in

Response ASBO to Buyer

Operation (See table)

Broker


Repsonse ASBO

Request

ASBO

Response

ASBO

Request

ASBO

Response

ASBO

MessageConfiguration.table

Figure 4. Asynchronous Request-Response events


Table 10 shows the correlation between incoming application-specific businessobject verbs and Ariba Buyer operations.

Table 10. Correlation between ASBO verbs and Ariba Buyer operations

Verb (WBI) Operation (Ariba Buyer) Action

Create Create Creates any new objects in Ariba Buyer.

Delete Delete Removes from Ariba Buyer any objects that are in the message.

Retrieve N/A Ariba Buyer cannot perform retrieves.

Update Load and Delete Updates new data values for existing objects, creates newobjects, and deletes objects in Ariba Buyer that do notexist in the incoming message.

ABUpdate Update Updates new data values for existing objects. Does notcreate new objects or delete objects in Ariba Buyer thatdo not exist in the incoming message.

Load Load Updates new data values for existing objects and creates newobjects.

Update and Delete Update and Delete Updates new data values for existing objects. If the objectdoes not exist in the incoming message, it is deletedfrom Ariba Buyer.

UpdateElementsOnly UpdateElementsOnly Updates vector objects.

Attribute propertiesThe connector has various properties that you can set on its business objectattributes. The tables below list the attributes and their values.

Table 11 lists simple attributes.

Table 11. Simple attributes

Attribute Property

Name Specifies the business object field name.

Type Specifies the business object field type.

MaxLength 255 by default.

IsKey Each business object must have at least one key attribute, which you specifyby setting the key property to true for an attribute.

IsForeighKey Not used.

Ariba

Buyer

Destination

ApplicationBuyer

Database

A

d

a

p

t

e

r

A

d

a

p

t

e

r

Adapter translates Verb in

Request ASBO to Buyer

Operation (See table)

Broker


Request ASBO

Request

ASBO

Request

ASBO

Figure 5. Subscribe events


Table 11. Simple attributes (continued)

Attribute Property

Is Required Not used.

AppSpecInfo Holds the original Java type.

DefaultValue Specifies a default value that the connector uses for a simple attribute inthe inbound business object if the attribute is not set and isa required attribute.

Table 12 shows the properties for child object attributes.

Table 12. Child object attributes

Attribute Description

Name Specifies the business object field name.

Type Specifies the business object field type.

ContainedObjectVersion

For all attributes that represent child business objects, this property specifies thechild’s business object version number.

Relationship If the child is a container attribute, this is set to Containment.

IsKey Set to true if the attribute name equals UniqueName, otherwise it is set to false.

IsForeighKey Not used.

Is Required Not used.

AppSpecInfo Holds the original Ariba Buyer field name.

Cardinality Set to N if the type represents an array or vector, otherwise set to 1.

Application-specific informationApplication-specific information provides the connector with application-dependent instructions on how to process business objects. If you extend or modifya business object definition, you must make sure that the application-specificinformation in the definition matches the syntax that the connector expects.

Application-specific information can be specified on the business object and also oneach business object attribute.

The application-specific information for the business object handles two keyproperties for the adapter for Ariba Buyer. They are:v The original object type namev The name of the collaboration used by the business object

Note: The system integrator must fill in the collaboration name. This value isnot used when WebSphere MQ Integrator is the broker. However, IBMrecommends that this value be set to match the name of the broker flowthat will handle this transaction within WebSphere MQ Integrator broker.

The application-specific information for the business object attributes holds theoriginal Ariba Buyer-specific java type.


Generating business objectsThe integration channel component of the adapter for Ariba Buyer runs in AribaBuyer itself. Once events have been configured for the integration channel, AribaBuyer exports application-specific meta-data through the channel to a file systemrepository. This meta-data is used by the Object Discovery Agent to create businessobject definitions, which are exported to the integration broker repository.

Each time an event occurs during run time, Ariba Buyer sends a message objectcontaining object-level data and information about the type of transaction. Theconnector maps this data to the corresponding business object definition, to createan application-specific business object. The connector sends these business objectson to the integration broker for processing. It also receives business objects backfrom the integration broker, which it passes back to Ariba Buyer.

Note: If the object model in Ariba Buyer is changed, use the ODA to modify theoriginal business object definition to reflect the update, or create a newdefinition. If the business object definitions in the integration brokerrepository do not match exactly the data that Ariba Buyer exports, theconnector is not able to create a business object and the transaction will fail.

Business Object Designer provides a graphical interface that enables you togenerate business object definitions for use at run time. For details, see Chapter 4,“Generating business object definitions”, on page 25


Chapter 4. Generating business object definitions

This chapter describes the Object Discovery Agent (ODA) for Ariba Buyer, andhow to use it to generate business object definitions for the IBM WebSphereBusiness Integration Adapter for Ariba Buyer.

This chapter contains the following sections:v “Overview of the ODA for Ariba Buyer” on page 25v “Generating Business Object Definitions” on page 25v “Uploading your files” on page 32

Overview of the ODA for Ariba BuyerAn ODA (Object Discovery Agent) enables you to generate application-specificbusiness object definitions. A business object definition is a template for a businessobject. The ODA examines specified application objects, “discovers” the elementsof those objects that correspond to business object attributes, and generatesbusiness object definitions to represent the information. Business Object Designerprovides a graphical interface to access the Object Discovery Agent and to workwith it interactively.

The Object Discovery Agent (ODA) for Ariba Buyer generates business objectdefinitions from meta-data exported by Ariba Buyer at initialization. The BusinessObject Designer wizard automates the process of creating these definitions. Youcan view or make modifications to a business object definition before you save it tothe server.

You use the ODA to generate business object definitions at two different stages:1. When the system is first set up: You must create a set of business object

definitions for all integration events defined on the integration channel.Business object definitions and broker collaborations and workflows must bedefined for all integration channel events that will be run as part of thedatabase initialization.

2. Whenever an object used in an integration channel event is modified inAriba Buyer: You must run the ODA in Business Object Designer to pick upthe changed meta-data for the object and export a new business objectdefinition to the broker repository.

Generating Business Object DefinitionsThis section describes how to use Ariba Buyer ODA in Business Object Designer togenerate business object definitions. For information on launching and usingBusiness Object Designer, see IBM WebSphere Business Integration Adapters BusinessObject Development Guide.

Starting the ODAThe ODA can be run from any machine that can mount the file system on whichthe meta-data repository resides, using the start_BuyerODA.bat (WIN) orstart_BuyerODA.sh (UNIX) start file. This file contains start parameters, includingthe paths to certain required Ariba Buyer and connector .jar files. These .jar filesmust also be accessible from the machine on which you are running the ODA.


The ODA for Ariba Buyer has a default name of BuyerODA. The name can bechanged by changing the value of the AGENTNAME variable in the start script.

To start the ODA, run this command:

start_BuyerODA <Ariba server root path>

For example,

start_BuyerODA C:\Ariba\app\Buyer\Server

Running Business Object DesignerBusiness Object Designer provides a wizard that guides you through the steps togenerate a business object definition using the ODA. The steps are as follows:

Select the agent

1. Start Business Object Designer.2. Select File > New Using ODA. The Business Object Wizard - Step 1 of 6 - Select

Agent screen appears.3. Select the ODA/AGENTNAME (from the start_BuyerODA script) in the

Located agents list and click Next.

Figure 6. Select Agent screen


Configure the agentThe Business Object Wizard - Step 2 of 6 - Configure Agent screen appears. The firsttime you open this screen, it is blank.

In this screen you:v Enter the path information that the ODA needs to locate the meta-data

repository and the message file.v Specify a trace message file; for example, BuyerODAtrace.txt.v Specify a tracing level (from 0 to 5).

Note: If the name of the message file is not correctly specified, the ODA will runwithout messages.

All messages displayed by the Buyer ODA appear in the BuyerODAAgent.txt file,which has a standard message file format. For more information on the range oftrace levels and their meaning, refer to “Using log and trace files” on page 15.

You can also can save all the values you enter on this screen to a profile. Instead ofre-typing all the data the next time you run the ODA, you simply select a profilefrom the drop-down menu and use the saved values.

You can save multiple profiles, each with a different set of specified values.

Figure 7. Configure Agent screen

Chapter 4. Generating business object definitions 27

1. Use the Profiles menu the first time you run the ODA to create a new profile.In successive uses, you may select an existing profile.

2. Type the name of each property, its value, type and description.

Note: If you use a profile, the property values are filled in for you.Table 13 lists the properties and their possible values.

Table 13. Property values for configuring the ODA

No. Property name Property type Description Required

1 MetadataRepos String Directory where the meta-data file repository resides.For example, C:\temp\metadata

Yes

2 TraceFileName String The name of the trace file. No

3 TraceLevel Integer Trace level for the ODA. Yes

4 MessageFile String The path to the message file. Yes

Note: The meta-data repository is always in the location specified for theMetadataRepos property, found in:<Ariba_server_root>/config/Parameters.table. You can set MetadataReposto this value, or copy the \metadata directory to another machine and resetthe MetadataRepos value accordingly. This is possible because there is nointeraction between the ODA and the application during the process ofgenerating business object definitions.

When you have finished, click Next.

Select a business objectThe Business Object Wizard - Step 3 of 6 - Select Source screen appears. Use thisscreen to select any number of MessageConfigurations for which the ODA willgenerate business object definitions.

The screen lists the variants that have been defined in Ariba Buyer (derived fromthe structure of the meta-data repository). If Ariba Buyer has not been initialized,the list will be empty.


v Expand a variant to see a list of its partitions.v Expand a partition to see a list of MessageConfigurations.1. Select the MessageConfigurations you want to use.2. Click Next.

Confirm selectionThe Business Object Wizard - Step 4 of 6 - Confirm source nodes for business objectdefinitions screen appears. It shows the MessageConfigurations you selected.

Figure 8. Select Source screen


Click Back to make changes or Next to confirm the list is correct.

Generate the business objectThe Business Object Wizard - Step 5 of 6 - Generating business objects... screen appears.

Figure 9. Confirm source nodes screen


The message states that the wizard is generating the business objects.

Save the a copy of the business object to a separate fileThe Business Object Wizard - Step 6 of 6 - Save business objects screen appears.

Figure 10. Generating business objects screen


You can optionally save the generated business object definitions to a file. To do so:1. Check Save business objects to a file. A dialog box appears.2. Type the location in which you want the copy of the new business object

definitions to be saved.

Business Object Designer saves the files to the specified location.

Note: If you create new custom objects in Ariba Buyer, you must add newbusiness object definitions for them, using the ODA as described in thischapter.

If you have finished working with the ODA, you can shut it down by checking“Shutdown ODA Buyer ODA” before clicking Finish.

Uploading your filesThe newly created business object definition files must be uploaded to theintegration broker once they have been created. The process depends on whetheryou are running ICS or the MQ Integrator Broker.

For ICS: If you have saved your business object definition files to a local machineand need to upload them to the repository on the server, refer to the ImplementationGuide for WebSphere InterChange Server.

Figure 11. Save business objects screen


For MQ Integration Broker: You must export the business object definitions out ofBusiness Object Designer and into the integration broker. For details, refer to theIBM WebSphere Business Integration Adapters Implementation Guide for MQ Integrator.


Chapter 5. Troubleshooting and error handling

This chapter describes how the adapter for Ariba Buyer handles errors. The threecomponents of the adapter generate logging and tracing messages. The chapterdescribes these messages by component The chapter contains the followingsections:v “Channel error handling” on page 35v “Tracing messages” on page 40v “Tips for troubleshooting” on page 41

Channel error handlingThe integration channel logs error messages using the Ariba Buyer API. It logs anyabnormal condition that it encounters during processing, regardless of the tracelevel. It writes the text to an Ariba Buyer log file located in <Ariba serverroot>\logs and named AribaBuyer<nodename>Log.txt; for example,AribaBuyerNode1Log.txt.

The message contains a detailed description of the condition and the outcome andmay also include extra information that may aid in debugging, such as businessobject dumps or stack traces (for exceptions).

Channel error messages are of two types:v Initialization errorsv Run-time errors

Channel initialization errors are usually fatal, and will prevent the Ariba Buyernode from starting. Table 14 lists possible errors and the action you can take toremedy each one.

Table 14. Channel initialization errors

Error message Description Corrective action

Error accessing RMIregistry on port xxx

Fatal error. If the ChannelRemote cannotbe started, the connector is not able tocommunicate with the channel.

Verify the ChannelPort parameterspecified in Parameters.table andchange it if necessary.

Error bindingChannelRemote object atregistry: <url>Exception: <message text>

Fatal error. If the ChannelRemote cannotbe started, the connector is not able tocommunicate with the channel.

Verify the ChannelPort parameterspecified in Parameters.table. Seethe Exception message for moreinformation.

Error initializingChannelRemote object.Exception: <xxx>

An error occurred when starting theintegration channel’s remote object.

Verify the ChannelPort parameterspecified in Parameters.table. Seethe Exception message for moreinformation.

Error creating file: xxx The channel receives an error whenattempting to create the specifieddirectory or file.

Verify that:

v There is enough disk space tostore files.

v The user has the authority tocreate files and directories.


Table 15 lists possible run-time errors and the action you can take to remedy eachone.

Table 15. Channel run-time errors


Exception processingMessage: <topic name>Exception <error text>

The message handler receives an errorwhen trying to send a message to theconnector.

See the error text for more information.

The specified reply keywas not found in the table.Key = xxx

The message handler receives a messagewith a key not found in the reply table.

Check log files to see if specified replykey was found and processed onanother node. If not, rerun the event.If a node has been stopped or shutdown, the reply key will be invalid.

Received Exceptionconnecting to Connectorremote object. Exception<error text>

Message handler’s reference to theconnector is missing or invalid.

Verify that:

v The ConnectorPort andConnectorURL parameters are

correct in Parameters.table.

v The Ariba Buyer connector has beenstarted.

The xxx parameter isnot specified.

The specified parameter is not foundin the message configuration ormessage definition.

Edit the message configuration ormessage definition accordingly.

xxx has a null value A parameter in the reply received fromthe connector has a null value.

Verify that this parameter is being setcorrectly by the map, adapter, orcollaboration.

Message Configurationnot found for <topicname> in partition:<partition name>

A message configuration entry cannotbe found for the specified topic namein the specified partition.

Verify that the specified partition existsin MessageConfiguration.table in theintegration channel directory.

Channel parameter <xxx>not set

The specified parameter has not beenset in the integration channel sectionof the Parameters.table file.

Add the parameter to Parameters.tablewith the correct value.

Processing for the Messagewith TopicName <xxx>has exceeded the timeoutinterval specified

A reply for the message with thespecified topic name has not beenreceived within the allotted time.

Verify that the Timeout parameter forthe specified topic name has been setcorrectly in MessageConfiguration.txt.

Check the integration channel andconnector log files for related errormessages.

ABRequestMessageHandler not found intable for:<partition - topic name>

A message handler cannot be found fora message with the specified topicname and partition.

Add an entry toMessageConfiguration.table for thespecified topic name and partition.

Reply for Message withTopicName <xxx> has nodata for definedPullSchema objects

The integration channel has received aresponse with missing data for thespecified message.

Verify that:

v The PullSchema(s) are defined inMessageDefinition.table.

v The PullSchema parameter is beingset correctly by the map, collaborationor adapter.


Connector error handlingThe connector logs any abnormal condition that it encounters during processing,regardless of the trace level. It writes the text to the connector log file.


Connector error messages are of two types:v Initialization errorsv Run-time errors

Table 16 lists possible initialization errors and the action you can take to remedyeach one.

Table 16. Connector initialization errors


An Exception occurredattempting to bind theABConnectorRemoteobject to the RMIRegistry usingname <name>Exception: <error text>

Fatal error. If the ConnectorRemotecannot be started, the channel is notable to communicate with theconnector.

Set the ConnectorPort property correctlyin the connector applicationconfiguration properties.


Could not connect to theremote object of theABChannel

The connector cannot connect to anychannel nodes at initialization.

Verify that:

v The Ariba Buyer server isstarted.

v The connector applicationconfiguration property Nodesis set correctly.

Error connecting to remoteobject <node name>,using URL: <url>

The connector cannot connect to thechannel’s remote object on the specifiedAriba Buyer node.

Set the Nodes property correctly in theconnector application configurationproperties.

Connector property notspecified: <name>

The specified property is not set. Set the named property correctly in theconnector application configurationproperties.

Table 17 lists possible run-time errors and the action you can take to remedy eachone.

Table 17. Connector run-time errors


Collaboration name notfound in Business Object:<name>

The connector attempts to send abusiness object that does not havethe collaborationapplication-specific property set.

Set the Collaboration property correctlyin the business object-level application-specific information in the specifiedbusiness object definition.

Connector failed to deliverbusiness object: <BOname>

The gotApplEvent returns an error. Check the log files for more information.

Chapter 5. Troubleshooting and error handling 37

Table 17. Connector run-time errors (continued)


Failed to deliver businessobject: <BO name>because the connector isnot active.

The gotApplEvent returns an error.Attempted to deliver a business object toan inactive connector.

Verify that the connector is active.

Connector failed to deliverbusiness object: <BOname> because nosubscription was found.

The gotApplEvent returns an error. Verify that the business object issubscribed to by a collaboration.

Invalid verb specified:<verb> for business object:<BO name>

The verb in a message sent to theconnector is not supported by thebusiness object.

Verify that:

v The Verb parameter is setcorrectly in

MessageConfiguration.table.

v All supported verbs are correctly setin the business object definition.

The attribute <xxx> wasnot found in the BusinessObject <BO name>

The connector is processing a messagecontaining a field that does not have acorresponding attribute in the businessobject definition.

Verify that the business objectdefinition is correctly set up.

The Buyer Connector doesnot poll. Set the Connectorproperty PollFrequency to“No” to avoid thismessage.

The Ariba Buyer connector does not poll. Set the connector standard propertyPollFrequency to No.

The business object<name> is not defined

A business object definition with thespecified name cannot be found.

Create the specified business object usingthe ODA.

The value specified forattribute <name> is not avalid type

The specified attribute in the messageobject does not have the same type asthe attributes in the business objectdefinition.

Verify the business object definition andrecreate it using the ODA if necessary.

The attribute: <name> wasnot found in the businessobject definition: <BOname>

The attribute specified in the messageobject is not in the specified businessobject definition.

Verify the business object definition andrecreate it using the ODA if necessary.

An error occurred duringthe processing of thebusiness object: <BOname>. Exception: <errortext>

An error occurred after the connectorsent the specified business object.

Check the error text for more information.

An Exception occurredunbinding the remoteobject from the RMIRegistry.Name <name>Exception: <error text>

There was a problem unbinding theconnector’s remote object from theregistry. This may prevent the connectorfrom binding its remote object to theRMI registry the next time theconnector is started.

Verify the ConnectorPort property in theconnector application configurationproperties. Check the error text formore information.

You may have to restart the systembefore attempting to start the connector.

A SpecNameNotFoundException occurred whenadding the child businessobject: <child BO name>to the business object:<parent BO name>

The connector is attempting to add thespecified child business object to ann-cardinality attribute of the specifiedparent business object.

Verify that the cardinality is correctly setfor the parent business object.


Table 17. Connector run-time errors (continued)


Exception occurredinstantiating class fortype: <name>.Exception: <error text>

The class specified in the attributesApp Spec Info could not be instantiated.

Verify that the specified class is in theclasspath.


No String constructorfound for type: <classname>

The class specified in the attributesApp Spec Info does not have aconstructor that accepts onestring parameter.

The class specified in the meta-datacannot be used if it does not have astring constructor.

An error occurred sendingobject to Channel onnode: <name>.Exception: <error text>

The specified error occurred on sendingan object to the channel.


Check the Ariba Buyer logs for moreinformation.

Reply key: <key> forobject not found inChannel on Node:<node name>

The connector has sent an object to thechannel with a reply key that the channeldoes not have in its table.

The reply key may be invalid, or mayexist on another node. Check the logs tosee if another node has processed theobject.

The request may have timed out and thereply key has been removed from thetable. Check the logs to verify.

An error occurred sendingthe business object: <BOname> to Channel. Checkthe logs for moreinformation.

An error occurred while sending thespecified business object to the channel.

Check the logs for more information.

An error occurred creatinga java.util.Date objectfrom the String “xxx”.Locale: <locale>

The Date string does not match thedefault format or the formats specifiedin the DateFormats parameter inthe connector applicationconfiguration properties.

Specify the correct format string in theconnector application configurationproperties.

See the API forjava.text.SimpleDateFormatfor information on specifying dateformat strings.

The business object forTopicName: <topic name>,variant: <variant name>,partition: <partitionname> is not defined

A matching business object definitioncould not be found for the specifiedtopic name, variant and partition.

Create a matching business objectdefinition using the ODA.

Specify a business object prefix in theVariantMappings connector applicationconfiguration property.

Variant prefix notspecified for variant:<variant name>

A prefix for the specified variant couldnot be found in the VariantMappingsconnector applicationconfiguration property.

Specify a business object prefix in theVariantMappings connector applicationconfiguration property.

ODA error handlingThe ODA logs error messages to the ODA log. It logs any abnormal condition thatit encounters during processing, regardless of the trace level.



Table 18 lists possible errors and the action you can take to remedy each one.

Table 18. ODA errors


The specified path doesnot exist: <path name>

The connector ODA property BuyerPathis not set or is invalid.

Verify that the BuyerPath property isset correctly.

File not found: <filename>

The specified meta-data file could notbe found.

Verify that the BuyerPath property isset correctly.

Regenerate the meta-data file fromAriba Buyer.

Class not found for file:<file name

The ABClassMeta class cannot be found,or the meta-data file was created with abacklevel ABClassMeta class

Verify that the ABClassMeta class is inthe class path.

Verify that the meta-data was generatedwith the latest ABClassMeta class.

IO Error reading file: <filename>

The ODA receives an error when readinga meta-data file.

Verify that the user has the authority toopen the file.

Verify that the file is not in use.

The ABClassMeta is nullfor class name: <classname> variant name:<variant name>

A meta-data file could not be foundfor the specified class and variant.

Regenerate the meta-data file fromAriba Buyer.

Error creating BusObjAttrfor <field name> in class<class name>

An error occurred when adding thespecified attribute to the business objectdefinition for the specified class.

Verify that:

v The field type is supportedby the business object.

v There is no duplicate attributename in the business object.

Error creating BusinessObject definition: <BOname>. Error Text: <errortext>

The ODA receives an error when creatinga business object definition.


Tracing messagesTracing is an optional debugging feature you can turn on to closely follow aconnector’s behavior. Tracing messages are configurable and can be changeddynamically. You set various levels depending on the desired detail. Tracemessages, by default, are written to STDOUT (screen). You can also configuretracing to write to a file.

Recommendation: Tracing should be turned off on a production system or set tothe lowest possible level to improve performance and decrease file size.

Table 19 on page 41 describes the types of tracing messages that the Ariba Buyerconnector outputs at each trace level. All the trace messages appear in the filespecified by the connector property TraceFileName. These messages are in additionto any tracing messages output by the IBM WebSphere Business IntegrationAdapter architecture.


Table 19. Tracing messages

Tracing Level Tracing Messages

Level 0 Message that identifies the connector version. No other tracing is done at this level.This message is always displayed; for example,

’2003/03/21 15:01:46.812: This is version 3.0 of the Adapter for Ariba Buyer’.

Level 1 Messages delivered each time the pollForEvents method is executed.

Level 2 v Messages logged each time a business object is posted to the integration brokerfrom gotApplEvent.

v Messages that indicate each time a business object request is received.

Level 3 Not applicable.

Level 4 v Application-specific information messages; for example, messages showingthe values returned by the functions that parse the business object’sapplication-specific information fields.

v Messages that identify when the connector enters or exits a function, whichhelps trace the process flow of the connector.

Level 5 v Messages that indicate connector initialization; for example, messagesshowing the value of each configuration property retrieved from the integrationbroker.

v Messages that comprise a business object dump. At this trace level, the connectoroutputs a textual representation of the business object before it begins processingthe object (showing the object the connector receives from thecollaboration), and after it has finished processing the object (showing theobject that the connector returns to the collaboration).

Tips for troubleshootingUse the following tips for troubleshooting problems:v If the channel is running remotely, try to ping the remote machine and also ping

this machine from the remote machine.v Check that the connector is running.v Check that the server is running.v Be sure the business object structure is consistent with the operation.


Appendix A. Standard configuration properties for connectors

Connectors have two types of configuration properties:v Standard configuration propertiesv Connector-specific configuration properties

This chapter describes standard configuration properties, applicable to allconnectors. For information about properties specific to the connector, see theinstalling and configuring chapter of its adapter guide.

The connector uses the following order to determine a property’s value (where thehighest numbers override the value of those that precede):1. Default2. Repository (relevant only if InterChange Server is the integration broker)3. Local configuration file4. Command line

Note: In this document backslashes (\) are used as the convention for directorypaths. For UNIX installations, substitute slashes (/) for backslashes and obeythe appropriate operating system-specific conventions.

New and deleted propertiesThe following are the standard properties that have been either added or deletedin the 2.2 release of the adapters.v New properties

CharacterEncodingLocalJVMMinHeapSizeJVMMaxHeapSizeJVMMaxStackSizeWireFormatMaxEventCapacityDuplicateEventEliminationjms.NumConcurrentRequestsContainerManagedEventsjms.Messagebrokername (replaces jms.BrokerName)

v Deleted properties

RequestTransportPingFrequencyTraceLevelAgentProxyTypeMaxThreadPoolSizeAnonymous ConnectionsGW NameAgent URL


Listener PortCertificate LocationLogFileNameTraceFileNamejms.BrokerName

Configuring Standard Connector Properties for WebSphereInterChange Server

This section describes standard configuration properties applicable to connectorswhose integration broker is WebSphere InterChange Server (ICS). Standardconfiguration properties provide information that is used by a configurablecomponent of InterChange Server called the connector controller. Like theconnector framework, the code for the connector controller is common to allconnectors. However, you configure a separate instance of the controller for eachconnector.

A connector, which consists of the connector framework and theapplication-specific component, has been referred to historically as the connectoragent. When a standard configuration property refers to the agent, it is referring toboth the connector framework and the application-specific component.

For general information about how connectors work with InterChange Server, seethe Technical Introduction to IBM WebSphere InterChange Server.

Important: Not all properties are applicable to all connectors that use InterChangeServer. For information specific to an connector, see its adapter guide.

You configure connector properties from Connector Configurator, which you accessfrom System Manager.

Note: Connector Configurator and System Manager run only on the Windowssystem. Even if you are running the connector on a UNIX system, you muststill have a Windows machine with these tools installed. Therefore, to setconnector properties for a connector that runs on UNIX, you must start upSystem Manager on the Windows machine, connect to the UNIXInterChange Server, and bring up Connector Configurator for the connector.

A connector obtains its configuration values at startup. If you change the value ofone or more connector properties during a runtime session, the property’s updatesemantics determine how and when the change takes effect. There are fourdifferent types of update semantics for standard connector properties:v Dynamic—The change takes effect immediately after it is saved.v Component restart—The change takes effect only after the connector is stopped

and then restarted in System Manager. This does not require stopping andrestarting the application-specific component or InterChange Server.

v Server restart—The change takes effect only after you stop and restart theapplication-specific component and InterChange Server.

v Agent restart—The change takes effect only after you stop and restart theapplication-specific component.


To determine the update semantics for a specific property, refer to the UpdateMethod column in the Connector Configurator window, or see the Update Methodcolumn of the table below.

The following table provides a quick reference to the standard connectorconfiguration properties. You must set the values of some of these propertiesbefore running the connector. See the sections that follow for explanations of theproperties.

Property Name PossibleValues

DefaultValue

UpdateMethod

Notes

AdminInQueue valid JMS queue name CONNECTORNAME /ADMININQUEUE

AdminOutQueue valid JMS queue name CONNECTORNAME/ADMINOUTQUEUE

AgentConnections 1-4 1 server restart multi-threadedconnector only

AgentTraceLevel 0-5 0 dynamic

ApplicationName application name the value that is specified for theconnector name

componentrestart

value required

BrokerType ICS, WMQI ICS is requiredif your brokeris ICS

CharacterEncoding ascii7, ascii8, SJIS,Cp949, GBK, Big5,Cp297,Cp273,Cp280,Cp284,Cp037, Cp437

ascii7 componentrestart

ConcurrentEventTriggeredFlows 1 to 32,767 no value componentrestart

ContainerManagedEvents JMS or no value JMS guaranteedevent delivery

ControllerStoreAndForwardMode true or false true dynamicControllerTraceLevel 0-5 0 dynamicDeliveryQueue CONNECTORNAME/DELIVERYQUEUE component

restartJMS transportonly

DeliveryTransport MQ, IDL, or JMS IDL componentrestart

FaultQueue CONNECTORNAME/FAULTQUEUE componentrestart

DuplicateEventElimination True/False False componentrestart

JMS transportonly,ContainerManagedEventsmust be<NONE>

JvmMaxHeapSize heap size in megabytes 128m componentrestart

JvmMaxNativeHeapSize size of stack in kilobytes 128k componentrestart

JvmMinHeapSize heap size in megabytes 1m componentrestart

jms.MessageBrokerName If FactoryClassName isIBM, usecrossworlds.queue.manager.If FactoryClassName isSonic, uselocalhost:2506.

crossworlds.queue.manager server restart JMS transportonly

jms.FactoryClassName CxCommon.Messaging.jms.IBMMQSeriesFactoryor CxCommon.Messaging.jms.SonicMQFactory orany Java class name

CxCommon.Messaging.jms.IBMMQSeriesFactory

server restart JMS transportonly

jms.NumConcurrentRequests positive integer 10 componentrestart

JMS transportonly

Appendix A. Standard configuration properties for connectors 45


DefaultValue

UpdateMethod

Notes

jms.Password Any valid password server restart JMS transportonly

jms.UserName Any valid name server restart JMS transportonly

Locale en_US , ja_JP, ko_KR,zh_C, zh_T, fr_F, de_D,it_I, es_E, pt_BRNote: These are only asubset of supportedlocales.

en_US componentrestart

LogAtInterchangeEnd true or false false componentrestart

MaxEventCapacity 1-2147483647 2147483647 dynamic RepositoryDirectoryvalue must be<REMOTE>

MessageFileName path/filename Connectorname.txt orInterchangeSystem.txt

componentrestart

MonitorQueue any valid queue name CONNECTORNAME/MONITORQUEUE componentrestart

JMS transportonly,DuplicateEventEliminationmust be True

OADAutoRestartAgent true or false false dynamicOADMaxNumRetry a positive number 1000 dynamicOADRetryTimeInterval a positive number in

minutes10 dynamic

PollEndTime HH:MM HH:MM componentrestart

PollFrequency a positive integer inmilliseconds

no (to disable polling)key (to poll only whenthe letter p is entered inthe connector’sCommand Promptwindow)

10000 dynamic

PollQuantity 1-500 1 componentrestart

Number ofitems to pollfromapplication

PollStartTime HH:MM(HH is 0-23, MM is0-59)

HH:MM componentrestart

RepositoryDirectory location whererepository is located

<REMOTE> componentrestart

<REMOTE>for ICS broker

RequestQueue valid JMS queue name CONNECTORNAME/REQUESTQUEUE componentrestart

ResponseQueue valid JMS queue name CONNECTORNAME/RESPONSEQUEUE componentrestart

RestartRetryCount 0-99 3 dynamicRestartRetryInterval a sensible positive value in

minutes1 dynamic

SourceQueue valid MQSeries queuename

CONNECTORNAME/SOURCEQUEUE componentrestart

Valid only ifdeliverytransport isJMS andContainerManagedEventsisspecified.

SynchronousRequestQueue CONNECTORNAME/SYNCHRONOUSREQUESTQUEUE

componentrestart

“SynchronousResponseQueue” onpage 62

CONNECTORNAME/SYNCHRONOUSRESPONSEQUEUE

componentrestart



DefaultValue

UpdateMethod

Notes

SynchronousRequestTimeout 0 componentrestart

“WireFormat” on page 63 CwXML, CwBO cwxml agent restart CwXML fornon-ICSbroker; CwBOifRepositoryDirectoryis <REMOTE>

AdminInQueueThe queue that is used by the integration broker to send administrative messagesto the connector.

The default value is CONNECTORNAME/ADMININQUEUE.

AdminOutQueueThe queue that is used by the connector to send administrative messages to theintegration broker.

The default value is CONNECTORNAME/ADMINOUTQUEUE.

AgentConnectionsThe AgentConnections property controls the number of IIOP connections openedfor request transport between an application-specific component and its connectorcontroller. By default, the value of this property is set to 1, which causesInterChange Server to open a single IIOP connection.

This property enhances performance for a multi-threaded connector by allowingmultiple connections between the connector controller and application-specificcomponent. When there is a large request/response workload for a particularconnection, the IBM WebSphere administrator can increase this value to enhanceperformance. Recommended values are in the range of 2 to 4. Increasing the valueof this property increases the scalability of the Visigenic software, which establishesthe IIOP connections. You must restart the application-specific component and theserver for a change in property value to take effect.

Important: If a connector is single-threaded, it cannot take advantage of themultiple connections. Increasing the value of this property causes therequest transport to bottleneck at the application-specific component.To determine whether a specific connector is single- or multi-threaded,see the installing and configuring chapter of its adapter guide.

AgentTraceLevelLevel of trace messages for the application-specific component. The default is 0.The connector delivers all trace messages applicable at the tracing level set orlower.

ApplicationNameName that uniquely identifies the connector’s application. This name is used bythe system administrator to monitor the WebSphere business integration systemenvironment. This property must have a value before you can run the connector.


BrokerTypeIdentifies the integration broker type that you are using. If you are using an ICSconnector, this setting must be ICS.

CharacterEncodingSpecifies the character code set used to map from a character (such as a letter ofthe alphabet, a numeric representation, or a punctuation mark) to a numeric value.

Note: Java-based connectors do not use this property. A C++ connector currentlyuses the value ASCII for this property. If you previously configured thevalue of this property to ascii7 or ascii8, you must reconfigure theconnector to use either ASCII or one of the other supported values. Todetermine whether a specific connector is written in Java or C++, see theinstalling and configuring chapter of its adapter guide.

Important: By default only a subset of supported character encodings display inthe drop list. To add other supported values to the drop list, you mustmanually modify the \Data\Std\stdConnProps.xml file in the productdirectory. For more information, see the appendix on ConnectorConfigurator.

Attention: Do not run a non-internationalized connector against InterChangeServer version 4.1.1 if you cannot guarantee that only ISO Latin-1 data will beprocessed.

The default value is ascii.

ConcurrentEventTriggeredFlowsDetermines how many business objects can be concurrently processed by theconnector controller for event delivery. Set the value of this attribute to the numberof business objects you want concurrently mapped and delivered. For example, setthe value of this property to 5 to cause five business objects to be concurrentlyprocessed. The default value is 1.

Setting this property to a value greater than 1 allows a connector controller for asource application to simultaneously map multiple event business objects, and tosimultaneously deliver them to multiple collaboration instances. Setting thisproperty to enable concurrent mapping of multiple business objects can speeddelivery of business objects to a collaboration, particularly if the business objectsuse complex maps. Increasing the arrival rate of business objects to collaborationscan improve overall performance in the system.

Note: To implement concurrent processing for an entire flow (from a sourceapplication to a destination application) also requires that the collaborationbe configured to use multiple threads and that the destination application’sapplication-specific component be able to process requests concurrently. Toconfigure the collaboration, set its Maximum number of concurrent eventsproperty high enough to use multiple threads. For an application-specificcomponent to process requests concurrently, it must be eithermulti-threaded, or be capable of using Connector Agent Parallelism and beconfigured for multiple processes (setting the Parallel Process Degreeconfiguration property greater than 1).


Important: To determine whether a specific connector is single- or multi-threaded,see the installing and configuring chapter of its adapter guide.

The ConcurrentEventTriggeredFlows property has no effect on connector polling,which is single-threaded and performed serially.

ContainerManagedEventsSetting this property to JMS allows a JMS-enabled connector with a JMS eventstore to provide guaranteed event delivery, in which an event is removed from thesource queue and placed on the destination queue as a single JMS transaction. Thisproperty can also be set to no value.

Notes:

1. When ContainerManagedEvents is set to JMS, you must also configure thefollowing properties to enable guaranteed event delivery: PollQuantity = 1 to500, SourceQueue = SOURCEQUEUE. In addition, you must configure a datahandler with the MimeType, DHClass, and DataHandlerConfigMOName(optional) properties. To set those values, use the Data Handler tab ofConnector Configurator. The fields for the values under the Data Handler tabwill be displayed only if you have set ContainerManagedEvents to JMS.

2. When ContainerManagedEvents is set to JMS, the connector does not call itspollForEvents() method, thereby disabling that method’s functionality.

The default value is JMS.

This property only appears if the DeliveryTransport property is set to the valueJMS.

ControllerStoreAndForwardModeSets the behavior of the connector controller after it detects that the destinationapplication-specific component is unavailable. If this property is set to true and thedestination application-specific component is unavailable when an event reachesInterChange Server, the connector controller blocks the request to theapplication-specific component. When the application-specific component becomesoperational, the controller forward the request to it.

Important: If the destination application’s application-specific component becomesunavailable after the connector controller forwards a service callrequest to it, the connector controller fails the request.

If this property is set to false, the connector controller begins failing all servicecall requests as soon as it detects that the destination application-specificcomponent is unavailable.

The default is true.

ControllerTraceLevelLevel of trace messages for the connector controller. The default is 0.

DeliveryQueueThe queue that is used by the connector to send business objects to the integrationbroker.

The default value is DELIVERYQUEUE.


DeliveryTransportSpecifies the transport mechanism for the delivery of events. Possible values are MQfor WebSphere MQ, IDL for CORBA IIOP, or JMS for Java Messaging Service.

If ICS is the broker type, the value of the DeliveryTransport property can be MQ,IDL, or JMS, and the default is IDL.

If WMQI is the broker type, JMS is the only possible Delivery Transport value.

The connector sends service call requests and administrative messages overCORBA IIOP if the value configured for the DeliveryTransport property is MQ orIDL.

WebSphere MQ and IDLUse WebSphere MQ rather than IDL for event delivery transport, unless you havecompelling reasons not to license and maintain two separate products. WebSphereMQ offers the following advantages over IDL:v Asynchronous communication – WebSphere MQ allows the application-specific

component to poll and persistently store events even when the server is notavailable.

v Server side performance – WebSphere MQ provides faster performance on theserver side. In optimized mode, WebSphere MQ stores only the pointer to anevent in the repository database, while the actual event remains in theWebSphere MQ queue. This saves the overhead of having to write potentiallylarge events to the repository database.

v Agent side performance – WebSphere MQ provides faster performance on theapplication-specific component side. Using WebSphere MQ, the connector’spolling thread picks up an event, places it in the connector’s queue, then picksup the next event. This is faster than IDL, which requires the connector’s pollingthread to pick up an event, go over the network into the server process, storethe event persistently in the repository database, then pick up the next event.

JMSEnables communication between the connector controller and client connectorframework using Java Messaging Service (JMS).

If you select JMS as the delivery transport, additional JMS properties such as″jms.MessageBrokerName,″ ″jms.FactoryClassName,″ ″jms.Password,″ and″jms.UserName,″ display in Connector Configurator. The first two of theseproperties are required for this transport.

Important: There may be a memory limitation if you use the JMS transportmechanism for a connector in the following environment:

v AIX 5.0v WebSphere MQ 5.3.0.1v InterChange Server (ICS) as the Integration broker

In this environment, you may experience difficulty starting the both the connectorcontroller (on the server side) and the connector (on the client side) due to memoryuse within the WebSphere MQ client. If your installation uses less than 768M ofprocess heap size, IBM recommends that you set:v The LDR_CNTRL environment variable in the CWSharedEnv.sh script.

This script resides in the \bin directory below the product directory. With a texteditor, add the following line as the first line in the CWSharedEnv.sh script:


export LDR_CNTRL=MAXDATA=0x30000000

This line restricts heap memory usage to a maximum of 768 MB (3 segments *256 MB). If the process memory grows more than this limit, page swapping canoccur, which can adversely affect the performance of your system.

v The IPCCBaseAddress property to a value of 11 or 12. For more information onthis property, see the System Installation Guide for UNIX.

Notes:

v If your installation uses more than 768M of process heap size, this resolutionwould adversely affect product performance.

v If you run on AIX 4.3.3, you do not need to set the LDR_CNTRL environmentvariable. However, you must set IPCCBaseAddress to a value of 11 or 12.

DuplicateEventEliminationSetting this property to true enables a JMS-enabled connector with a non-JMSevent store to ensure that duplicate events are not delivered to the delivery queue.To make use of this feature, during connector development a unique eventidentifier must be set as the business object’s ObjectEventId attribute in theapplication specific code.

This property can also be set to false.

Note: When DuplicateEventElimination is set to true, you must also configure theMonitorQueue property to enable guaranteed event delivery.

FaultQueueIf the connector experiences an error while processing a message then theconnector moves the message to the queue specified in this property, along with astatus indicator and a description of the problem.

The default value is CONNECTORNAME/FAULTQUEUE.

JvmMaxHeapSizeThe maximum heap size for the agent (in megabytes). This property is applicableonly if the RepositoryDirectory value is <REMOTE>.

The default value is 128m.

JvmMaxNativeStackSizeThe maximum native stack size for the agent (in kilobytes). This property isapplicable only if the RepositoryDirectory value is <REMOTE>.

The default value is 128k.

JvmMinHeapSizeThe minimum heap size for the agent (in megabytes). This property is applicableonly if the RepositoryDirectory value is <REMOTE>.

The default value is 1m.


jms.FactoryClassNameSpecifies the class name to instantiate for a JMS provider. You must set thisconnector property when you choose JMS as your delivery transport mechanism(DeliveryTransport).

The default is CxCommon.Messaging.jms.IBMMQSeriesFactory.

jms.MessageBrokerNameSpecifies the broker name to use for the JMS provider. You must set this connectorproperty when you choose JMS as your delivery transport mechanism(DeliveryTransport).

The default is crossworlds.queue.manager.

jms.NumConcurrentRequestsSpecifies the maximum number of concurrent service call requests that can be sentto a connector at the same time. Once that maximum is reached, new service callsblock and wait for another request to complete before proceeding.

The default value is 10.

jms.PasswordSpecifies the password for the JMS provider. A value for this property is optional.

There is no default.

jms.UserNameSpecifies the user name for the JMS provider. A value for this property is optional.


LocaleSpecifies the language code, country or territory, and, optionally, the associatedcharacter code set. The value of this property determines such cultural conventionsas collation and sort order of data, date and time formats, and the symbols used inmonetary specifications. For more information, see the overview chapter of theconnector guide for an internationalized connector.

A locale name has the following format:ll_TT.codeset

where:

ll a two-character language code (usually in lowercase)

TT a two-letter country or territory code (usually inupper case)

codeset the name of the associated character code set; thisportion of the name is often optional.

The default is en_US.


Important: By default only a subset of supported locales display in the drop list.To add other supported values to the drop list, you must manuallymodify the \Data\Std\stdConnProps.xml file in the product directory.For more information, see the appendix on Connector Configurator.

Attention: If the connector has not been internationalized, the only valid valuefor this property is en_US. Do not run a non-internationalized C++ connectoragainst InterChange Server version 4.1.1 if you cannot guarantee that only ISOLatin-1 data will be processed. To determine whether a specific connector has beeninternationalized, see the installing and configuring chapter of its connector guide.

LogAtInterchangeEndSpecifies whether to log errors to InterChange Server’s log destination, in additionto the location specified in the LogFileName property. Logging to the server’s logdestination also turns on email notification, which generates email messages forthe MESSAGE_RECIPIENT specified in the InterchangeSystem.cfg file when errors orfatal errors occur. As an example, when a connector loses its connection to itsapplication, if LogAtInterChangeEnd is set to true, an email message is sent to thespecified message recipient. The default is false.

MaxEventCapacityThe maximum number of events in the controller buffer. This property is used byflow control and is applicable only if the value of the RepositoryDirectory propertyis <REMOTE>.

The value can be a positive integer between 1 and 2147483647. The default value is2147483647.

MessageFileNameThe name of the connector message file. The standard location for the message fileis \connectors\messages. Specify the message filename in an absolute path if themessage file is not located in the standard location.

If a connector message file does not exist, the connector usesInterchangeSystem.txt as the message file. This file is located in the productdirectory.

Important: To determine whether a specific connector has its own message file, seethe installing and configuring chapter of its adapter guide.

OADAutoRestartAgentSpecifies whether the Object Activation Daemon (OAD) automatically attempts torestart the application-specific component after an abnormal shutdown. Theproperties “OADMaxNumRetry” and “OADRetryTimeInterval” on page 54 arerelated to this property. This property is required for automatic restart.

The default value is false.

OADMaxNumRetrySpecifies the maximum number of times that the OAD automatically attempts torestart the application-specific component after an abnormal shutdown.



OADRetryTimeIntervalSpecifies the number of minutes of the retry time interval that the OADautomatically attempts to restart the application-specific component after anabnormal shutdown. If the application-specific component does not start within thespecified interval, the OAD repeats the attempt as many times as specified in“OADMaxNumRetry” on page 53.

The default is 10.

PollEndTimeTime to stop polling the event queue. The format is HH:MM, where HH represents0-23 hours, and MM represents 0-59 seconds.

You must provide a valid value for this property. The default value is HH:MM, butmust be changed.

PollFrequencyThe amount of time between polling actions. Set PollFrequency to one of thefollowing values:v The number of milliseconds between polling actions.v The word key, which causes the connector to poll only when you type the letter

p in the connector’s Command Prompt window. Enter the word in lowercase.v The word no, which causes the connector not to poll. Enter the word in

lowercase.

The default is 10000.

Important: Some connectors have restrictions on the use of this property. Todetermine whether a specific connector does, see the installing andconfiguring chapter of its adapter guide.

PollStartTimeThe time to start polling the event queue. The format is HH:MM, where HH represents0-23 hours, and MM represents 0-59 seconds.


RequestQueueThe queue that is used by the integration broker to send business objects to theconnector.

The default value is REQUESTQUEUE.

RepositoryDirectoryThe location of the repository from which the connector reads the XML schemadocuments that store the meta-data of business object definitions.

When the integration broker is ICS, this value must be set to <REMOTE> becausethe connector uses the InterChange Server repository to obtain itsconnector-definition information


ResponseQueueDesignates the JMS response queue, which delivers a response message from theconnector framework to the integration broker. When the integration broker isInterChange Server, InterChange Server sends the request and waits for a responsemessage in the JMS response queue.

RestartRetryCountSpecifies the number of times the connector attempts to restart itself. When usedfor a parallel connector, specifies the number of times the master connectorapplication-specific component attempts to restart the slave connectorapplication-specific component.

The default is 3.

RestartRetryIntervalSpecifies the interval in minutes at which the connector attempts to restart itself.When used for a parallel connector, specifies the interval at which the masterconnector application-specific component attempts to restart the slave connectorapplication-specific component.

The default is 1.

SourceQueueDesignates the JMS source queue for the connector framework in support ofguaranteed event delivery for JMS-enabled connectors that use a JMS event store.For further information, see “ContainerManagedEvents” on page 49.

The default value is SOURCEQUEUE.

SynchronousRequestQueueDelivers request messages that require a synchronous response from the connectorframework to the broker. This queue is necessary only if the connector usessynchronous execution. With synchronous execution, the connector frameworksends a message to the SynchronousRequestQueue and waits for a response backfrom the broker on the SynchronousResponseQueue. The response message sent tothe connector bears a correlation ID that matches the ID of the original message.

SynchronousResponseQueueDelivers response messages sent in reply to a synchronous request from the brokerto the connector framework. This queue is necessary only if the connector usessynchronous execution.

SynchronousRequestTimeoutSpecifies the time in minutes that the connector waits for a response to asynchronous request. If the response is not received within the specified time thenthe connector moves the original synchronous request message into the fault queuealong with an error message.



TraceFileNameThe name of the file where the application-specific component writes tracemessages. Specify the filename in an absolute path. The default is STDOUT.

WireFormatMessage format on the transport.

Possible values are:v CwXMLif the broker is not ICS.v CwBOif the value of RepositoryDirectory is <REMOTE>.

Configuring Standard Connector Properties for WebSphere MQIntegrator

This section describes standard configuration properties applicable to adapterswhose integration broker is WebSphere MQ Integrator Broker. For information onusing WebSphere Integrator Broker, see the Implementation Guide for WebSphere MQIntegrator Broker.

Important: Not all properties are applicable to all connectors that use WebSphereMQ Integrator Broker. For information specific to a connector, see itsadapter user guide.

You configure connector properties from Connector Configurator.

Note: Connector Configurator runs only on the Windows system. Even if you arerunning the connector on a UNIX system, you must still have a Windowsmachine with this tool installed. Therefore, to set connector properties for aconnector that runs on UNIX, you must run Connector Configurator on theWindows computer and copy the configuration files to the UNIX computerusing FTP or some other file transfer mechanism. For more informationabout Connector Configurator, see Appendix B, ″Connector Configurator.″

A connector obtains its configuration values at startup. If you change the value ofone or more connector properties during a runtime session, you must restart theconnector. Standard configuration properties provide information that is used bythe adapter framework and connector framework, and is common to allconnectors.

Standard Connector PropertiesThe following table provides a quick reference for standard connectorconfiguration properties. See the sections that follow for explanations of theproperties.

Name Possible Values Default Value

AdminInQueue valid JMS queue name CONNECTORNAME/ADMININQUEUEAdminOutQueue valid WebSphere MQ

queue nameCONNECTORNAME/ADMINOUTQUEUE

AgentTraceLevel 0-5 0ApplicationName application name AppNameConnectorBrokerType WMQI WMQI



CharacterEncoding ASCII, SJIS, Cp949, GBK,Big5, Cp297, Cp273,Cp280, Cp284, Cp037,Cp437Note: These are only asubset of supportedvalues.

ASCII

ContainerManagedEvents JMS or no value JMSDeliveryQueue valid WebSphere MQ

queue nameCONNECTORNAME/DELIVERYQUEUE

DeliveryTransport JMS JMSDuplicateEventElimination true, falseFaultQueue valid WebSphere MQ

queue nameCONNECTORNAME/FAULTQUEUE

jms.FactoryClassName CxCommon.Messaging.jms.IBMMQSeriesFactoryjms.MessageBrokerName If FactoryClassName is

IBM, usecrossworlds.queue.manager.If FactoryClassName isSonic, uselocalhost:2506.

crossworlds.queue.manager

jms.NumConcurrentRequests 10jms.Passwordjms.UserNameLocale en_US , ja_JP, ko_KR,

zh_C, zh_T, fr_F, de_D,it_I, es_E, pt_BRNote: These are only asubset of supportedlocales.

en_US

MessageFileName path/filename InterchangeSystem.txtPollEndTime HH:MM HH:MMPollFrequency milliseconds/key/no 10000PollStartTime HH:MM HH:MMRepositoryDirectory path/directory name Note:

Typically you mustchange this value fromthe default to whateverpath and directory namewas actually used whenyou installed the theconnector files.

C:\crossworlds\Repository

RequestQueue valid WebSphere MQqueue name

CONNECTORNAME/REQUESTQUEUE

ResponseQueue RESPONSEQUEUERestartRetryCount 0-99 3RestartRetryInterval an appropriate integer

indicating the number ofminutes between restartattempts

1

SourceQueue valid WebSphere MQqueue name

CONNECTORNAME/SOURCEQUEUE

SynchronousRequestQueue valid WebSphere MQqueue name

SynchronousResponseQueue valid WebSphere MQqueue name



SynchronousTimeout an appropriate integerindicating the number ofminutes the connectorwaits for a response to asynchronous request

0

WireFormat CwXML CwXML

AdminInQueueThe queue that is used by the integration broker to send administrative messagesto the connector.

The default value is CONNECTORNAME/ADMININQUEUE.

AdminOutQueueThe queue that is used by the connector to send administrative messages to theintegration broker.

AgentTraceLevelLevel of trace messages for the connector’s application-specific component. Thedefault is 0. The connector delivers all trace messages applicable at the tracinglevel set or lower.

ApplicationNameName that uniquely identifies the connection to the application. This name is usedby the system administrator to monitor the connector’s environment. When youcreate a new connector definition, this property defaults to the name of theconnector; when you work with the definition for an IBM WebSphere-deliveredconnector, the property is also likely to be set to the name of the connector. Set theproperty to a value that suggests the program with which the connector isinterfacing, such as the name of an application, or something that identifies a filesystem or website in the case of technology connectors.

BrokerTypeThis property is set to the value WMQI for connectors that are configured to useWebSphere MQ Integrator Broker as the integration broker.

CharacterEncodingSpecifies the character code set used to map from a character (such as a letter ofthe alphabet, a numeric representation, or a punctuation mark) to a numeric value.

Note: Java-based connectors do not use this property. A C++ connector currentlyuses the value ASCII for this property. If you previously configured thevalue of this property to ascii7 or ascii8, you must reconfigure theconnector to use either ASCII or one of the other supported values. Todetermine whether a specific connector is written in Java or C++, see theinstalling and configuring chapter of its adapter guide.

Important: By default only a subset of supported character encodings display inthe drop list. To add other supported values to the drop list, you mustmanually modify the \Data\Std\stdConnProps.xml file in the productdirectory. For more information, see the appendix on ConnectorConfigurator.


Attention: Do not run a non-internationalized connector against InterChangeServer version 4.1.1 if you cannot guarantee that only ISO Latin-1 data will beprocessed.

The default value is ascii.

ContainerManagedEventsSetting this property to JMS enables a JMS-enabled connector with a JMS eventstore to provide guaranteed event delivery, in which an event is removed from thesource queue and placed on the destination queue as a single JMS transaction. Thisproperty can also be set to no value.

Notes:

1. When ContainerManagedEvents is set to JMS, you must also configure thefollowing properties to enable guaranteed event delivery: PollQuantity = 1 to500, SourceQueue = SOURCEQUEUE. In addition, you must configure a datahandler with the MimeType, DHClass, and DataHandlerConfigMOName(optional) properties.

2. When ContainerManagedEvents is set to JMS, the connector does not call itspollForEvents() method, thereby disabling that method’s functionality.

The default value is JMS.

DeliveryQueueThe queue that is used by the connector to send business objects to the integrationbroker.

The default value is CONNECTORNAME/DELIVERYQUEUE.

DeliveryTransportSpecifies the transport mechanism for the delivery of events. The property defaultsto the value JMS, indicating that the Java Messaging Service (JMS) is used forcommunication with WebSphere MQ Integrator. This property must be set to JMSwhen WebSphere MQ Integrator Broker is the integration broker. Otherwise, theconnector cannot start.

DuplicateEventEliminationSetting this property to true enables a JMS-enabled connector with a non-JMSevent store to ensure that duplicate events are not delivered to the delivery queue.To make use of this feature, during connector development a unique eventidentifier must be set as the business object’s ObjectEventId attribute in theapplication specific code.

This property can also be set to false.

Note: When DuplicateEventElimination is set to true, you must also configure theMonitorQueue property to enable guaranteed event delivery.

FaultQueueIf the connector experiences an error while processing a message then theconnector moves the message to the queue specified in this property, along with astatus indicator and a description of the problem.

The default value is CONNECTORNAME/FAULTQUEUE.


jms.FactoryClassNameSpecifies the class name to instantiate for a JMS provider.

The default is CxCommon.Messaging.jms.IBMMQSeriesFactory.

jms.MessageBrokerNameSpecifies the broker name to use for the JMS provider.

The default is crossworlds.queue.manager.

jms.NumConcurrentRequestsSpecifies the maximum number of concurrent service call requests that can be sentto a connector at the same time. Once that maximum is reached, new service callsblock and wait for another request to complete before proceeding.


jms.PasswordSpecifies the password for the JMS provider. A value for this property is optional.


jms.UserNameSpecifies the user name for the JMS provider. A value for this property is optional.


LocaleSpecifies the language code, country or territory, and, optionally, the associatedcharacter code set. The value of this property determines such cultural conventionsas collation and sort order of data, date and time formats, and the symbols used inmonetary specifications. For more information, see the overview chapter of theconnector guide for an internationalized connector.

A locale name has the following format:ll_TT.codeset

where:

ll a two-character language code (usually in lowercase)

TT a two-letter country or territory code (usually inupper case)

codeset the name of the associated character code set; thisportion of the name is often optional.

The default is en_US.

Important: By default only a subset of supported locales display in the drop list.To add other supported values to the drop list, you must manuallymodify the \Data\Std\stdConnProps.xml file in the product directory.


Attention:

v WebSphere MQ Integrator supports only one locale at a time. Ensure that everycomponent of the installation (for example, all adapters, applications, and theintegration broker itself) is set to the same locale.

v If the connector has not been internationalized, the only valid value for thisproperty is en_US. Do not run a non-internationalized C++ connector againstInterChange Server version 4.1.1 if you cannot guarantee that only ISO Latin-1data will be processed. To determine whether a specific connector has beeninternationalized, see the installing and configuring chapter of its connectorguide.

MessageFileNameThe name of the connector message file. The standard location for the message fileis \connectors\messages. Specify the message filename in an absolute path if themessage file is not located in the standard location. This property defaults to thevalue InterchangeSystem.txt for new connector definitions and should be changedto the name of the message file for the specific connector.

PollEndTimeTime to stop polling the event queue. The format is HH:MM, where HH represents0-23 hours, and MM represents 0-59 seconds.


PollFrequencyThe amount of time between polling actions. Set the PollFrequency to one of thefollowing values:v The number of milliseconds between polling actions.v The word key, which causes the connector to poll only when you type the letter

p in the connector’s Command Prompt window. Enter the word in lowercase.v The word no, which causes the connector not to poll. Enter the word in

lowercase.

The default is 10000.

Important: Some connectors have restrictions on the use of this property. Todetermine whether a specific connector does, see the installing andconfiguring chapter of its adapter guide.

PollStartTimeThe time to start polling the event queue. The format is HH:MM, where HH represents0-23 hours, and MM represents 0-59 seconds.


RepositoryDirectoryThe path and name of the directory from which the connector reads the XMLschema documents that store the meta-data of business object definitions.

The default value is C:\crossworlds\repository. You must change this to thedirectory path that you are using for the \repository directory for your connector.Typically that path is established when you install the adapter product; for


example, C:\WebSphereAdapters\repository. The value must be a directory path.Do not use <REMOTE> as the RepositoryDirectory value for a connector that isnot using ICS as the broker.

RequestQueueThe queue that is used by the integration broker to send business objects to theconnector.

The default value is CONNECTORNAME/REQUESTQUEUE.

ResponseQueueDesignates the JMS response queue, which delivers a response message from theconnector framework to the integration broker.

RestartRetryCountSpecifies the number of times the connector attempts to restart itself. The defaultvalue is 3, indicating that the connector tries to restart 3 times. For instance, if aconnector is unable to log in to an application it fails to start, but with thisproperty set to the value 3 the connector tries a total of three times to start. Whenused in conjunction with the “RestartRetryInterval” property, this behavior enablesa connector to make several attempts at communicating with an application thatmight not reliably have a connection available all the time.

RestartRetryIntervalSpecifies the interval in minutes at which the connector attempts to restart itself.The default value is 1, indicating that the connector waits 1 minute in between itsrestart attempts.

SourceQueueDesignates the JMS source queue for the connector framework in support ofguaranteed event delivery for JMS-enabled connectors that use a JMS event store.For further information, see “ContainerManagedEvents” on page 49.

The default is CONNECTORNAME/SOURCEQUEUE.

SynchronousRequestQueueDelivers request messages that require a synchronous response from the connectorframework to WebSphere MQ Integrator Broker. This queue is necessary only if theconnector uses synchronous execution. With synchronous execution, the connectorframework sends a message to the SynchronousRequestQueue and waits for aresponse back from WebSphere MQ Integrator Broker on theSynchronousResponseQueue. The response message sent to the connector bears acorrelation ID that matches the ID of the original message.

SynchronousResponseQueueDelivers response messages sent in reply to a synchronous request fromWebSphere MQ Integrator Broker to the connector framework. This queue isnecessary only if the connector uses synchronous execution.

SynchronousTimeoutSpecifies the time in minutes that the connector waits for a response to asynchronous request. If the response is not received within the specified time thenthe connector moves the original synchronous request message into the fault queuealong with an error message.



WireFormatThe data format for messages exchanged by the connector. The default value CwXMLis the only valid value, and directs the connector to compose the messages in XML.


Appendix B. Connector Configurator

Before you can use a connector, you must create a connector configuration file thatsets the properties for the connector, designates the business objects and anymeta-objects that it supports, and sets logging and tracing values that theconnector will use at runtime. The configuration file may also contain propertiesfor the use of messaging and data handlers required by your connector.

Use Connector Configurator to create and modify the configuration file for yourconnector. If a configuration file has previously been created for your connector,you can use Connector Configurator to open the file and modify its settings. If noconfiguration file has yet been created for your connector, you can use ConnectorConfigurator to both create the file and set its properties.

When you complete a connector configuration file, the file is saved as an XMLdocument. You will save the XML document either as a project in System Manager(if ICS is your broker) or as a file with a *.cfg extension in a directory folder (ifWebSphere MQ Integrator Broker is your broker, or if you are using the file as alocal configuration file for ICS).

This appendix describes how to use Connector Configurator to:v Create a connector-specific property template for configuring your connectorv Create a configuration filev Set properties in a configuration file

Connector Configurator runs only in a Windows environment. If you are runningthe connector itself in a UNIX environment, use Connector Configurator in theWindows system in the network to modify the configuration file. Then copy thefile to your UNIX environment.

Note: Some properties in the connector configuration file use directory paths, andthese paths default to the Windows convention for directory paths. If youuse the connector configuration file in a UNIX environment, revise anydirectory path constructs in the configuration properties to match the UNIXconvention for directory paths.

Using Connector Configurator in an internationalized environmentConnector Configurator is internationalized and handles character conversionbetween the configuration file and the integration broker. Connector Configuratoruses native encoding. When it writes to the configuration file, it uses UTF-8encoding.

Connector Configurator supports non-English characters in:v All value fieldsv Log file and trace file path (specified in the Trace/Log files tab)

The drop list for the CharacterEncoding and Locale standard configurationproperties displays only a subset of supported values. To add other values to thedrop list, you must manually modify the \Data\Std\stdConnProps.xml file in theproduct directory.


For example, to add the locale en_GB to the list of values for the Locale property,open the stdConnProps.xml file and add the line in boldface type below:<Property name="Locale" isRequired="true" updateMethod="component restart">

<ValidType>String</ValidType><ValidValues>

<Value>ja_JP</Value><Value>ko_KR</Value><Value>zh_CN</Value><Value>zh_TW</Value><Value>fr_FR</Value><Value>de_DE</Value><Value>it_IT</Value><Value>es_ES</Value><Value>pt_BR</Value><Value>en_US</Value><Value>en_GB</Value>

<DefaultValue>en_US</DefaultValue></ValidValues>

</Property>

Starting Connector ConfiguratorConnector Configurator can be started and run in either of two modes:v Launched from System Managerv Independent of System Manager (stand-alone mode)

Running Configurator from System ManagerWhen you run Connector Configurator in conjunction with System Manager, youcanv Save connector configuration files (XML documents with the extension *.cfg) to a

directory that you specify, andv Save connector configuration files as components of System Manager projects. If

you are using ICS as your broker, this is a mandatory step before you deployyour configuration into the ICS.

Note: When you save a configuration file as a component of a System Managerproject, the file is stored in the designated project as an XML document filewith the extension *.con. It is not advisable to open the *.con file and edit itdirectly; instead, make any changes by opening the component in SystemManager.

To run Connector Configurator with System Manager, do any of the following:v In System Manager, right-click on the Connector folder of the Integration

Components Library (to create a new configuration), or right-click on aconnector configuration component within the Connector folder (to edit anexisting configuration), or

v From the System Manager menu, choose Tools>Connector Configurator, orv With System Manager already running, from Start>Programs choose IBM

WebSphere InterChange Server>IBM WebSphere Business IntegrationToolset>Development>Connector Configurator.

For details about using projects in System Manager and deploying to InterChangeServer, see the Implementation Guide for WebSphere InterChange Server.


Running Configurator independently of System ManagerWhen you run Connector Configurator without connecting to System Manager,you can save a connector configuration file (an XML document with the extension*.cfg) to a directory that you specify, but you cannot save or open a SystemManager project.

When you are creating a connector for use with a broker other than ICS, you donot need to connect to System Manager at any point in order to use the file. If youare creating a connector configuration for use with ICS as the broker, you may stillfind it useful on occasion to run Connector Configurator independently, and thenconnect to System Manager when you are ready to save the configuration file as acomponent of a System Manager project.

Choosing your brokerConnector Configurator can be used to configure connectors either for use withICS as the broker, or with WebSphere MQ Integrator Broker (also referred to asWMQI) as the broker.

Before you begin to configure the connector, you must choose the mode ofConnector Configurator that is appropriate for your broker. The mode that youchoose determines the properties that Connector Configurator will include in theconfiguration file. Choosing a broker is a mandatory step when you begin theprocess of creating a completely new configuration file. After a configuration filehas been created, you can optionally change the designated broker mode, using astandard configuration property. (This makes it possible to use an existingconfiguration file as a starting point for creating a configuration file that will beused with a different broker. However, be aware that revising a configuration filefor use with a different broker typically involves changing other configurationproperties as well, and not just the broker mode property.)

To choose a broker when you create a new configuration file (mandatory):v In the Connector Configurator home menu, choose File>New>Connector

Configuration. The New Connector Dialog displays.v In the Integration Broker field, choose either WMQI connectivity (for WebSphere

Integrator Broker) or ICS connectivity, according to the broker you are using.v Complete the remaining fields of the New Connector dialog, as described later

in this chapter for your specific broker.

To change your broker selection within an existing configuration file (optional):v Open the existing configuration file in Connector Configurator.v Select the Standard Properties tab.v In the Broker Type field of the Standard Properties tab, choose the value that is

appropriate for your broker. If you change the existing value, the available tabsand field selections of the properties screen will immediately refresh, to showonly those tabs and fields that appropriate for a configuration using the brokeryou have selected.

After you have chosen your broker type, you can complete the remainingConnector Configurator tasks for configuring your connector. When you save theconnector configuration file, Connector Configurator will save it in the brokermode that you have already selected. The title bar of Connector Configuratoralways displays the broker mode (such as ICS or WMQI) that ConnectorConfigurator is currently using.

Appendix B. Connector Configurator 67

After you have completed the configuration file and set its properties, it will needto be deployed to the appropriate location for your connector.v If you are using ICS as your broker, save the configuration in a System Manager

project, and use System Manager to load the file into InterChange Server.v If you are using WebSphere MQ Integrator Broker as your broker, manually

copy the configuration file to its appropriate location, which must match exactlythe configuration file location specified in the startup file for your connector.

For further information about deployment, see the Implementation Guide forWebSphere InterChange Server (for using the connector with ICS as the broker), orthe Implementation Guide for WebSphere MQ Integrator Broker (for using the connectorwith MQ Integrator as the broker).

Using a connector-specific property templateTo create a configuration file for your connector, you can start with a previouslycreated connector configuration file (*.cfg), a connector definition file (*.txt) or arepository file (*.in or *.out), if any of these already exists for your connector. Forinstructions on using such existing files, see “Using an existing file” on page 72.

If none of those files exist, or if they are too dissimilar to the configurationrequirements of your connector, you can start instead by creating a template forthe connector-specific properties of your connector. You’ll create properties in thetemplate, define general characteristics and values for those properties, and specifyany dependencies between the properties. Then you’ll save the template and use itas the base for creating a new connector configuration file.

Creating a template of connector-specific propertiesTo create a template:1. Choose File>New>Connector-Specific Property Template.2. The Connector-Specific Property Template dialog appears, with the following

fieldsv Name

Enter a unique name that identifies the connector, or type of connector, forwhich this template will be used. You will see this name again when youopen the dialog for creating a new configuration file from a template.

v Find Template, and Template NameThe names of all currently available templates are displayed in the TemplateName display. Look for an existing template that would make a goodstarting point for your new connector template (such as a template whoseproperty definitions are a subset of the properties used by your connector).To see the connector-specific property definitions that are contained in anytemplate, select that template’s name in the Template Name display. A list ofthe property definitions contained in that template will appear in theTemplate Preview display.If you do not see any template that displays the connector-specific propertiesthat are used by your connector, you will need to create one. ConnectorConfigurator provides a template named None, containing no propertydefinitions, as a default choice.Choose a template from the Template Name display, enter that templatename in the Find Name field (or highlight your choice in Template Name),and choose Next.


Specifying general characteristicsThe Properties - Connector-Specific Property Template dialog appears. The dialoghas tabs for General characteristics of the defined properties and for Valuerestrictions. The General display has the following fields:v Edit properties

Use the buttons provided (or right-click within the Edit properties display) toadd a new property to the template, to edit or delete an existing property, or toadd a child property to an existing property.A child property is a property that is an attribute of another property--the″parent″ property. The parent property can obtain values, or child properties, orboth. These property relationships are commonly referred to as ″hierarchical″properties. Later, when you create a configuration file from these properties,Connector Configurator will identify hierarchical property sets with a plus signin a box at the left of any parent property.

v Property typeChoose one of these property types: Boolean, String, Integer, or Time.

v FlagsYou can set Standard Flags (IsRequired, IsDepracated, IsOverridden) or CustomFlags (for Boolean operators) to apply to this property

After you have made selections for the general characteristics of the property,choose the Value tab.

Specifying valuesThe Value tab enables you to set the maximum length, the maximum multiplevalues, a default value, or a value range for the property. To do so:1. Choose the Value tab. The display panel for Value replaces the display panel

for General.2. Select the name of the property in the Edit properties display.3. In the fields for Max Length and Max Multiple Values, make any necessary

changes. Note that the changes will not be accepted until and unless you alsoopen the Property Value dialog for the property, described in the next step.

4. Right-click the box in the left-hand corner of the Value display panel. AProperty Value dialog displays. Depending on the type of the property, thedialog allows you to enter either a value, or both a value and range. Enter theappropriate value or range, and click OK.

5. The Value panel refreshes to display any changes you made in Max Length andMax Multiple Values, and it displays a table with three columns:The Value column shows the value that you entered in the Property Valuedialog, and any previous values that you created.The Default Value column allows you to designate any of the values as thedefault.The Value Range shows the range that you entered in the Property Valuedialog.After a value has been created and appears in the grid, it can be edited fromwithin the table display. To make a change in an existing value in the table,select an entire row by clicking on the row number. Then right-click in theValue field and choose EditValue.


Setting dependenciesAfter you have finished making changes in both the General and the Value tabs,choose Next. The Dependencies dialog appears.

A dependent property is a property that is included in the template and used inthe configuration file only if the value of another property meets a specificcondition. To designate a property as being dependent and set the condition uponwhich it depends, do this:1. In the Available Properties display, select the property that will be made

dependent.2. In the Select Property field, use the drop-down menu to select the property that

will hold the conditional value.3. In the Condition Operator field, choose one of the following:

== (equal to)/= (not equal to)> (greater than)< (less than)>= (greater than or equal to)<=(less than or equal to)

4. In the Conditional Value field, enter the value that is required in order for thedependent property to be included in the template.

5. With the dependent property highlighted in the Available Properties display,click an arrow to move it to the Dependent Property display.

6. Click Finish. Connector Configurator stores the information you have enteredas an XML document, under \data\app in the\bin directory where you haveinstalled Connector Configurator.

Creating a configuration file from a connector-specifictemplate

After a connector-specific template has been created, you can use it to create aconfiguration file:1. Choose File > New>Connector Configuration.2. The New Connector dialog appears, with the following fields:

v NameEnter the name of the connector. Names are case-sensitive. The name youenter must be unique, must end with the word “connector”, and must beconsistent with the file name for a connector that is installed on the system;for example, enter PeopleSoftConnector if the connector file name isPeopleSoft.jar.

Important: Connector Configurator does not check the spelling of the namethat you enter. You must ensure that the name is correct.

v System ConnectivityChoose ICS or choose WMQI (for WebSphere MQ Integrator Broker)connectivity.

v Select Connector-Specific Property TemplateType the name of the template that has been designed for your connector.The names of all available templates are displayed in the Template Name


display. When you select a name in the Template Name display, the PropertyTemplate Preview display shows the connector-specific properties that havebeen defined in that template.After you have chosen the template you want to use, choose OK.

3. A configuration screen will display for the connector that you are configuring.The title bar of the configuration screen shows the broker that you are usingand the name that you have given to the connector. You can fill in all the fieldvalues to complete the definition now, or you can save the file and completethe fields later.When you are using the configuration screen, you can, if you wish, addadditional connector-specific properties, as described under “Settingapplication-configuration properties (ICS)” on page 74. Any such additionsbecome part of the configuration file that you are creating, but do not affect thetemplate that you used in creating the file.

4. To save the file, choose File > Save > to File or File > Save > Save to the project.To save to a project, you must be using ICS as the broker, and System Managermust be running. If you save as a file, the Save File Connector dialog displays.Choose *.cfg as the file type, verify in the File Name field that the name isspelled correctly and has the correct case, navigate to the directory where youwant to locate the file, and choose Save. The status display in the messagepanel of Connector Configurator indicates that the configuration file wassuccessfully created.

Important: The directory path and name that you establish here must matchthe connector configuration file path and name that you supply inthe startup file for the connector.

5. To complete the connector definition, enter values in the fields for each of thetabs of the Connector Configurator window, as described for your broker laterin this chapter.

Using Connector Configurator with ICS as the brokerTo use Connector Configurator to configure a connector that will be used with ICS,first select ICS as the broker mode in which you are running ConnectorConfigurator, as described under“Choosing your broker” on page 67.

In a typical ICS implementation, the configuration file that you create withConnector Configurator is not put into use until after you have deployed it to theICS server. You will perform that deployment (described in the ImplementationGuide for WebSphere InterChange Server) after you have finished using ConnectorConfigurator to complete the connector configuration file.

Completing a configuration fileThis topic assumes that you already have a starting point for your connectorconfiguration, either from an existing file (a connector definitions file, a repositoryfile, or a *.cfg file) or from an existing project in System Manager. If you do not,see “Creating a template of connector-specific properties” on page 68.

When you open a configuration file or a connector from a project, the ConnectorConfigurator window displays the configuration screen, with the attributes andvalues that Connector Configurator finds in the connector definition file.

The title of the configuration screen displays the type of the broker and the nameof the connector as specified in the file. Make sure the title indicates the


appropriate type for your broker--either ICS or WebSphere MQ Integrator Broker(for WMQI). If it does not, change the broker value before you configure theconnector. To do so:1. Under the Standard Properties tab, select the value field for the BrokerType

property. In the drop-down menu, select the value WMQI or ICS.2. The Standard Properties tab refreshes to display properties associated with the

selected broker. When you save the file, you retain this broker selection. Youcan save the file now or proceed to complete the remaining configurationfields, as described in “Setting the configuration file properties (WebSphere MQIntegrator Broker)” on page 78.

3. When you have finished making entries in the configuration fields, chooseFile>Save>To Project or File>Save>To File.If you are saving to file, choose *.cfg as the extension, choose the correctlocation for the file and choose Save.If multiple connector configurations are open, choose Save All to File to save allof the configurations to file, or choose Save All to Project to save all ICSconnector configurations to a System Manager project.Before it saves the file, Connector Configurator validates that values have beenset for all required Standard properties. If a required Standard property ismissing a value, Connector Configurator displays a message that the validationfailed. You must supply a value for the property in order to save theconfiguration file.

Using an existing fileYou may have an existing file available in one or more of the following formats:v A connector definition file. This is a text file that lists properties and applicable

default values for a specific connector. Some connectors include such a file in a\repository directory in their delivery package (the file typically has theextension .txt; for example, CN_XML.txt for the XML connector).

v An ICS repository file. Definitions used in a previous ICS implementation of theconnector may be available to you in a repository file that was used in theconfiguration of that connector. Such a file typically has the extension .in or.out.

v A previous configuration file for the connector. Such a file typically has theextension *.cfg.

Although any of these file sources may contain most or all of the connector-specificproperties for your connector, the connector configuration file will not be completeuntil you have opened the file and set properties, as described later in this chapter.

To use an existing file to configure a connector, you must open the file inConnector Configurator, revise the configuration, and then save the file as aconfiguration file (*.cfg file).

Follow these steps to open a *.txt, *.cfg, or *.in file from a directory:1. In Connector Configurator, choose File > Open > From File.2. In the Open File Connector dialog, choose one of the following file types to see

the available files:v Configuration (*.cfg)v ICS Repository (*.in, *.out)

Choose this option if a repository file was used to configure the connector inan ICS environment. A repository file may include multiple connectordefinitions, all of which will display when you open the file.


v All files (*.*)Choose this option if a *.txt file was delivered in the adapter package forthe connector, or if a definition file is available under another extension.

3. In the directory display, navigate to the appropriate connector definition file,select it, and choose Open.

Using an existing System Manager projectFollow these steps to open a connector configuration from a System Managerproject:1. Start System Manager. A configuration can be opened from or saved to System

Manager only if System Manager has been started.2. Start Connector Configurator.3. Choose File > Open > From Project.

Setting the configuration file properties (ICS)The topics in this section apply if you are using InterChange Server as theintegration broker. If you are using WebSphere MQ Integrator Broker as theintegration broker, see “Setting the configuration file properties (WebSphere MQIntegrator Broker)” on page 78. When you create and name a new connectorconfiguration file, or when you open an existing connector configuration file,Connector Configurator displays a configuration screen with tabs for the categoriesof required configuration values.

Connector Configurator requires values for properties in all of these categories:1. Standard Properties2. Connector-Specific Properties3. Supported Business Objects4. Associated Maps5. Resources6. Trace/Log File values7. Messaging (where applicable)8. Data handlers (applicable for connectors that use JMS messaging with

guaranteed event delivery)

Note: For connectors that use JMS messaging, an additional category may display,for configuration of data handlers that convert the data to business objects.

Important: Connector Configurator accepts property values in either English ornon-English character sets. However, the names of both standard andconnector-specific properties, and the names of supported businessobjects, must use the English character set only.

Standard properties differ from connector-specific properties as follows:v Standard properties of a connector are shared by both the application-specific

component of a connector and its broker component. All connectors have thesame set of standard properties. These properties are described in Appendix A ofeach adapter guide. You can change some but not all of these values.

v Application-configuration (application-specific) properties apply only to theapplication-specific component of a connector, that is, the component thatinteracts directly with the application. Each connector has application-specificproperties that are unique to its application. Some of these properties provide


default values and some do not; you can modify some of the default values. Theinstallation and configuration chapter of each adapter guide describes theapplication-specific properties and the recommended values.

The fields for Standard Properties and Connector-Specific Properties arecolor-coded to show which are configurable:v A field with a grey background indicates a standard property. You can change

the value but cannot change the name or remove the property.v A field with a white background indicates an application-specific property. These

properties vary according to specific needs of the application or connector. Youcan change the value and delete these properties.

v Value fields are configurable.v The Update Method field is informational and not configurable. This field

specifies the action required to activate a property whose value has changed.

Setting standard connector properties (ICS)To change the value of a standard property:1. Click in the field whose value you want to set.2. Either enter a value, or choose from the drop-down menu if one appears.3. After entering all values for the standard properties, you can do one of the

following:v To discard the changes, preserve the original values, and exit Connector

Configurator, choose File > Exit (or close the window), and choose No whenprompted to save changes.

v To enter values for other categories in Connector Configurator, choose the tabfor the category. The values you enter for Standard Properties (or othercategory) are retained when you move to the next category; when you closethe window, you are prompted to either save or discard the values that youentered in all of the categories as a whole.

v To save the revised values, choose File > Exit (or close the window) andchoose Yes when prompted to save changes. Alternatively, choose Save > ToFile from either the File menu or the toolbar.

Setting application-configuration properties (ICS)For application-specific configuration properties, you can add or change propertynames, configure values, delete a property, and encrypt a property:1. Right click in the top-left portion of the grid. A pop-up menu bar will appear.

Select Add to add a property or Add Child to add a child property for aproperty.

2. Enter a value for the property or child property.3. To encrypt a property, click the Encrypt box.4. Choose to save or discard changes, as described for Setting Standard Connector

Properties.

The Update Method displayed for each property indicates whether a component oragent restart is necessary to activate changed values.

Important: Changing a preset application-specific connector property name maycause a connector to fail. Certain property names may be needed bythe connector to connect to an application or to run properly.


Encryption for connector properties (ICS)Application-specific properties can be encrypted by clicking the Encrypt check boxin the Edit Property window. To decrypt a value, click to clear the Encrypt checkbox, enter the correct value in the Verification dialog box, and choose OK. If theentered value is correct, the value is decrypted and displays. The adapter guide foreach connector contains a list and description of each property and its defaultvalue.

If a property has multiple values, the Encrypt check box will appear for the firstvalue of the property. When you click the Encrypt check box, all values of theproperty will encrypted. To decrypt multiple values of a property, click to clear theEncrypt check box of the first value of the property, and then enter the correctvalue of the first value in the Verification dialog box. If the input value is a match,all multiple values will decrypt.

Update method (ICS)When WebSphere MQ Integrator Broker is the integration broker, connectorproperties are static. The Update Method is always Connector Restart. In otherwords, for changes to take effect, you must restart the connector after saving therevised connector configuration file.

Specifying supported business object definitions (ICS)This topic assumes that you have already created or acquired the intendedbusiness objects, created or acquired maps for them, and have saved both thebusiness object definitions and map definitions into System Manager projects.

Before you can make use of a connector (and before you can bind the connectorwith a collaboration’s ports), you must make selections under the SupportedBusiness Objects tab to specify the business objects that the connector will use. Youmust specify both generic business objects and corresponding application-specificbusiness objects, and you must specify associations for the maps between thebusiness objects.

Note: Some connectors require that certain business objects be specified assupported in order to perform event notification or additional configuration(using meta-objects) with their applications. For more information, see theConnector Development Guide for C++ or the Connector Development Guide forJava.

To specify that a business object definition is supported by the connector, or tochange the support settings for an existing business object definition, choose theSupported Business Objects tab and use the following fields:

Business object nameThese instructions assume that you started Business Object Designer with SystemManager running.

To designate that a business object definition is supported by the connector:1. Click in an empty field of the Business Object Name list. A drop-down list

displays, showing all the business object definitions that exist in the SystemManager project.

2. Click on a business object to add it.3. Set the Agent Support (described below) for the business object.


4. In the File menu of the Connector Configurator window, choose Save to Project.The revised connector definition, including designated support for the addedbusiness object definition, is saved to the project in System Manager.

To delete a business object from the supported list:1. To select a business object field, click the number to the left of the business

object2. From the Edit menu of the Connector Configurator window, choose Delete

Row. The business object is removed from the list display.3. From the File menu, choose Save to Project.

Note that deleting a business object from the supported list does not affect thecode of the connector, nor does it remove the business object definition itself fromSystem Manager. It does, however, change the connector definition and make thedeleted business object unavailable for use in this implementation of thisconnector.

Agent supportIndicating Agent Support for a business object means that the system will attemptto use that business object for delivering data to an application via the connectoragent.

Typically, application-specific business objects for a connector are supported bythat connector’s agent, but generic business objects are not.

To indicate that the business object is supported by the connector agent, put acheck in the Agent Support box. Note that the Connector Configurator windowdoes not validate your Agent Support selections.

Maximum transaction levelThe maximum transaction level for a connector is the highest transaction level thatthe connector supports.

For most connectors Best Effort is the only possible choice, because mostapplication APIs do not support the Stringent level.

You must restart the server for changes in transaction level to take effect.

Note: For this release, maximum transaction level of a connector is always BestEffort.

Associated maps (ICS)Each connector supports a list of business object definitions and their associatedmaps that are currently active in InterChange Server. This list displays when youselect the Associated Maps tab.

The list of business objects contains the application-specific business object whichthe agent supports and the corresponding generic object that the controller sendsto the subscribing collaboration. The association of a map determines which mapwill be used to transform the application-specific business object to the genericbusiness object or the generic business object to the application-specific businessobject.


If you are using maps that are uniquely defined for specific source and destinationbusiness objects, the maps will already be associated with their appropriatebusiness objects when you open the display, and you will not need (or be able) tochange them.

If more than one map is available for use by a supported business object, you willneed to explicitly bind the business object with the map that it should use.

The Associated Maps tab displays the following fields:v Business Object Name

These are the business objects supported by this connector, as designated in theSupported Business Objects tab. If you designate additional business objectsunder the Supported Business Objects tab, they will be reflected in this list afteryou save the changes by choosing Save to Project from the File menu of theConnector Configurator window.

v Associated MapsThe display shows all the maps that have been installed to the system for usewith the supported business objects of the connector. The source business objectfor each map is shown to the left of the map name, in the Business Object Namedisplay.

v ExplicitIn some cases, you may need to explicitly bind an associated map.Explicit binding is required only when more than one map exists for a particularsupported business object. When InterChange Server boots, it tries toautomatically bind a map to each supported business object for each connector.If more than one map takes as its input the same business object, the serverattempts to locate and bind one map that is the superset of the others. If there isnot a map that is the superset of the others, the server will not be able to bindthe business object to a single map, and you will need to set the bindingexplicitly.To explicitly bind a map:1. In the Explicit column, place a check in the check box for the map you want

to bind.2. Select the map that you intend to associate with the business object3. In the File menu of the Connector Configurator window, choose Save to

Project.4. Deploy the project to InterChange Server.5. Reboot the InterChange Server for the changes to take effect.

Resources (ICS)The Resource tab allows you to set a value that determines whether and to whatextent the connector agent will handle multiple processes concurrently usingconnector agent parallelism. Not all connectors support this feature, and use of thisfeature is not usually advised for connector agents that were designed in Java to bemulti-threaded, since it is usually more efficient to use multiple threads thanmultiple processes.

Setting trace/log file values (ICS)When you open a connector configuration file or a connector definition file,Connector Configurator uses the logging and tracing values of that file as defaultvalues. You can change those values in Connector Configurator.


To change the logging and tracing values:1. Choose the Trace/Log Files tab.2. For either logging or tracing, you can choose to write messages to one or both

of the following:v To console (STDOUT): Writes logging or tracing messages to the STDOUT

display.v To File: Writes logging or tracing messages to a file that you specify. To

specify the file, choose the directory button (ellipsis), navigate to thepreferred location, provide a file name, and choose Save. Logging or tracingmessage are written to the file and location that you specify.

Note: Both logging and tracing files are simple text files. You can use the fileextension that you prefer when you set their file names. For tracingfiles, however, it is advisable to use the extension .trace rather than.trc, to avoid confusion with other files that might reside on thesystem. For logging files, .log and .txt are typical file extensions.

Configuring messagingThe messaging properties are available only if you have set MQ as the value of theDeliveryTransport standard property and ICS as the broker type. These propertiesaffect how your connector will use queues.

Data handlersThe data handlers section is available for configuration only if you have designateda value of JMS for DeliveryTransport and a value of JMS forContainerManagedEvents. See the descriptions under ContainerManagedEvents inAppendix A, Standard Properties, for values to use for these properties. Foradditional details, see the Connector Development Guide for C++or the ConnectorDevelopment Guide for Java.

Setting the configuration file properties (WebSphere MQ IntegratorBroker)

The topics in this section apply if you are using WebSphere MQ Integrator (alsoreferred to as WMQI) as the integration broker.

When you create and name a new connector configuration file, or when you openan existing connector configuration file, Connector Configurator displays aconfiguration screen with tabs for the categories of required configuration values.

Connector Configurator requires values for properties in all of these categories:1. Standard Properties2. Connector-Specific Properties3. Supported Business Objects4. Trace/Log File values5. Data Handlers (where applicable)

Note: For connectors that use JMS messaging, an additional category may display,for configuration of data handlers that convert the data to business objects.For information about the values to use in the Data Handlers category, seethe Connector Development Guide for C++ or the Connector Development Guidefor Java.


Important: Connector Configurator accepts property values in either English ornon-English character sets. However, the names of both standard andconnector-specific properties, and the names of supported businessobjects, must use the English character set only.

Standard properties differ from connector-specific properties as follows:v Standard properties of a connector are shared by both the application-specific

component of a connector and its broker component. All connectors have thesame set of standard properties. These properties are described in Appendix A ofeach adapter guide. You can change some but not all of these values.

v Application-configuration (application-specific) properties apply only to theapplication-specific component of a connector, that is, the component thatinteracts directly with the application. Each connector has application-specificproperties that are unique to its application. Some of these properties providedefault values and some do not; you can modify some of the default values. Theinstallation and configuration chapter of each adapter guide describes theapplication-specific properties and the recommended values.

The fields for Standard Properties and Connector-Specific Properties arecolor-coded to show which are configurable:v A field with a grey background indicates a standard property. You can change

the value but cannot change the name or remove the property.v A field with a white background indicates an application-specific property. These

properties vary according to specific needs of the application or connector. Youcan change the value and delete these properties.

v Value fields are configurable.v The Update Method field is informational and not configurable. This field

specifies the action required to activate a property whose value has changed.

Setting standard connector propertiesTo change the value of a standard property:1. Click in the field whose value you want to set.2. Either enter a value, or choose from the drop-down menu if one appears.3. After entering all values for the standard properties, you can do one of the

following:v To discard the changes, preserve the original values, and exit Connector

Configurator, choose File > Exit (or close the window), and choose No whenprompted to save changes.

v To enter values for other categories in Connector Configurator, choose the tabfor the category. The values you enter for Standard Properties (or othercategory) are retained when you move to the next category; when you closethe window, you are prompted to either save or discard the values that youentered in all of the categories as a whole.

v To save the revised values, choose File > Exit (or close the window) andchoose Yes when prompted to save changes. Alternatively, choose Save > ToFile from either the File menu or the toolbar.

Setting application-configuration propertiesFor application-specific configuration properties, you can add or change propertynames, configure values, delete a property, and encrypt a property:1. Click in the field whose name or value you want to set.


2. Enter a name or value.3. To encrypt a property, click the Encrypt box.4. Choose to save or discard changes, as described for Setting Standard Connector

Properties.

The Update Method displayed for each property indicates whether a component oragent restart is necessary to activatechanged values.

Important: Changing a preset application-specific connector property name maycause a connector to fail. Certain property names may be needed bythe connector to connect to an application or to run properly.

Encryption for connector propertiesApplication-specific properties can be encrypted by clicking the Encrypt check boxin the Edit Property window. To decrypt a value, click to clear the Encrypt checkbox, enter the correct value in the Verification dialog box, and choose OK. If theentered value is correct, the value is decrypted and displays. The adapter guide foreach connector contains a list and description of each property and its defaultvalue.

Update methodWhen WebSphere MQ Integrator Broker is the integration broker, connectorproperties are static. The Update Method is always Agent Restart. In other words,for changes to take effect, you must restart the connector agent after saving therevised connector configuration file.

Specifying supported business object definitionsThe procedures in this section assume that you have already created:v Business object definitionsv MQ message set files (*.set files)

The *.set files contain message set IDs that Connector Configurator requires fordesignating the connector’s supported business objects. See the ImplementationGuide for WebSphere MQ Integrator Broker for information about creating the MQmessage set files.

Each time that you add business object definitions to the system, you must useConnector Configurator to designate those business objects as supported by theconnector.

Important: If the connector requires meta-objects, you must create message set filesfor each of them and load them into Connector Configurator, in thesame manner as for business objects.

To specify supported business objects:1. Select the Supported Business Objects tab and choose Load. The Open Message

Set ID File(s) dialog displays.2. Navigate to the directory where you have placed the message set file for the

connector and select the appropriate message set file (*.set) or files.3. Choose Open. The Business Object Name field displays the business object

names contained in the *.set file; the numeric message set ID for each businessobject is listed in its corresponding Message Set ID field. Do not change themessage set IDs. These names and numeric IDs are saved when you save theconfiguration file.


4. When you add business objects to the configuration, you must load theirmessage set files. If you attempt to load a message set that contains a businessobject name that already exists in the configuration, or if you attempt to load amessage set file that contains a duplicate business object name, ConnectorConfigurator detects the duplicate and displays the Load Results dialog. Thedialog shows the business object name or names for which there are duplicates.For each duplicate name shown, click in the Message Set ID field, and choosethe Message Set ID that you wish to use.

Setting trace/log file valuesWhen you open a connector configuration file or a connector definition file,Connector Configurator uses the logging and tracing values of that file as defaultvalues. You can change those values in Connector Configurator.

To change the logging and tracing values:1. Choose the Trace/Log Files tab.2. For either logging or tracing, you can choose to write messages to one or both

of the following:v To console (STDOUT): Writes logging or tracing messages to the STDOUT

display.v To File: Writes logging or tracing messages to a file that you specify. To

specify the file, choose the directory button (ellipsis), navigate to thepreferred location, provide a file name, and choose Save. Logging or tracingmessage are written to the file and location that you specify.

Note: Both logging and tracing files are simple text files. You can use the fileextension that you prefer when you set their file names. For tracingfiles, however, it is advisable to use the extension .trace rather than.trc, to avoid confusion with other files that might reside on thesystem. For logging files, .log and .txt are typical file extensions.

Configuring data handlersThe data handlers section is available for configuration only if you have designateda value of JMS for DeliveryTransport and a value of JMS forContainerManagedEvents. See the descriptions under ContainerManagedEvents inAppendix A, Standard Properties, for values to use for these properties. Foradditional details, see the Connector Development Guide for C++ or the ConnectorDevelopment Guide for Java

Using standard and connector-specific properties with ConnectorConfigurator

Connector configuration properties include both standard configuration properties(the properties that all connectors have) and connector-specific properties(properties that are needed by the connector for a specific application ortechnology).

Because standard properties are used by all connectors, you do not need to definethose properties within your configuration file; Connector Configurator already hasthose definitions, and it incorporates them into your configuration file as soon asyou create the file. For standard properties, your only task is to use ConnectorConfigurator to set the values of the properties.


For connector-specific properties, however, you will need to both define theproperties and set their values. Connector Configurator provides the interface forperforming both of these tasks.

Completing the configurationAfter you have created a configuration file for a connector and modified it, makesure that the connector can locate the configuration file when the connector startsup. To do so, open the startup file used for the connector, and verify that thelocation and file name used for the connector configuration file match exactly thename you have given the file and the directory or path where you have placed it.


Appendix C. Connector feature list

This appendix details the features supported by the Ariba Buyer connector. Fordescriptions of these features, see “Appendix A: Connector feature checklist” inIBM WebSphere Business Integration Adapters Connector Development Guide.

Event notification featuresThe following table details the event notification features supported by theconnector.

Category Feature Support Notes

Connector properties Event distribution N/A Currently, all events from an Ariba Buyerinstance (even if multi-node and/or multi-server) go through a single multi-threadedconnector instance.

Ariba Buyer provides event notification, sono event polling or event table is required.

PollQuantity N/A Ariba Buyer provides event notification, sono event polling or event table is required.

Event table Event status values N/A Ariba Buyer provides event notification, sono event polling or event table is required.

Object key N/A Ariba Buyer provides event notification, sono event polling or event table is required.

Object name N/A Ariba Buyer provides event notification, sono event polling or event table is required.

Priority N/A Ariba Buyer provides event notification, sono event polling or event table is required.

Misc. Archiving N/A Ariba Buyer keeps track of event status,thus there is no need to archive events.

CDK methodgotApplEvent

No gotApplEvent() is called, but not from withinpollForEvents() because the connector doesnot poll. It is event-driven.

Delta event notification Full

Event sequence N/A Ariba Buyer provides event notification, soan event table is not needed. No otherexplicit sequencing is required.

Future event processing N/A Ariba Buyer has the ability to scheduleevents. The connector only receives eventsat times when the event should be sent.

In-Progress event recovery N/A The connector does not implement thisfunctionality because Ariba Buyer handlesrecovery of failed events.

Ariba Buyer provides event notification, sono event polling or event table is required.



Physical delete event No Although the connector will forward therequest as a BO with the Delete verb, itcannot identify key values nor set non-keyvalues to CxIgnore.However, the intended effect can be achievedby the solution integrator if desired.

RetrieveAll Partial The connector does not support theRetrieveAll feature. However, whenAriba Buyer sends data to the connectorfor event notification, it does send everyfield in the hierarchical business objectthat has its metadataIntegratable flagset to true in the Ariba Buyer objectmodel.

Smart filtering N/A Ariba Buyer provides event notification, sono event polling or event table is required.

Verb stability N/A Ariba Buyer provides event notification, sono event polling or event table is required.

Service call request handling featuresThe following table details the service call request handling features supported bythe connector.


Create Create verb Full A Create can be performed in several ways.Refer to the User Guide for details.

Delete Delete verb No The Ariba Buyer interface does not supporta physical Delete verb.

Logical delete Partial Ariba Buyer only supports logical deletes.The connector requests that Buyer performits delete (logical) as a result of a Deleteverb. There is no field in the interface thatcan be “updated” to reflect logical deletion,thus the Update verb cannot be used toperform a logical delete in Ariba Buyer.

Exist Exist verb N/A The Ariba Buyer interface does not supportthe Exist verb.

Misc Attribute names Full

Business object names Full

Retrieve Retrieve verb N/A The Ariba Buyer interface does not supportthe Retrieve verb.

RetrieveByContent Ignore missing child object N/A The Ariba Buyer interface does not supportRetrieveByContent.

Multiple results N/A The Ariba Buyer interface does not supportRetrieveByContent.

RetrieveByContent verb N/A The Ariba Buyer interface does not supportRetrieveByContent.

Update After-image support Full

Delta support Full



KeepRelations N/A The Ariba Buyer interface does not supportthis feature.

Verbs Retrieve verb N/A The Ariba Buyer interface does not supportthe Retrieve verb.

Subverb support No The connector does not reference the verbfield of child business objects. It applies theverb specified in the parent business objectto all child business objects.

Verb stability Full

General featuresThe following table details the general features supported by the connector.


Business objectattributes

Foreign key No

Foreign key attributeproperty

N/A No validations are done by the connector.The Ariba Buyer interface does not useforeign keys.

Key No

Max Length No

Metadata-driven design Full

Required No

Connection lost Connection lost on poll N/A The connector does not poll for events; it isevent-driven.

Connection lost on requestprocessing

Partial The connector does not shut down.However, an exception is returned tothe message broker.

Connection lost while idle No The connection is not monitored while idle.

Connector properties ApplicationPassword N/A No application password is required.

ApplicationUserName N/A No application user name is required.

UseDefaults No

Message tracing General messaging Full

generateMsg() No The adapter does call generateMsg() fortracing; messages are obtained from messagefiles.

Trace level 0 Full

Trace level 1 Full

Trace level 2 Full

Trace level 3 N/A Foreign keys are not used.

Trace level 4 Full

Trace level 5 Full

Misc. CDK method LogMsg Full

Appendix C. Connector feature list 85


Java Package Names No The Java package naming standard adheredto is:com.ibm.adapters.<app_name>

where <app_name> is “Buyer”.

Logging messages Full

NT service compliance Full

Transaction support N/A There is no transaction support in AribaBuyer.

Special value CxBlank processing Full

CxIgnore processing Full


Appendix D. Notices

IBM may not offer the products, services, or features discussed in this document inall countries. Consult your local IBM representative for information on theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the user’s responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not give youany license to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law:

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESSFOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express orimplied warranties in certain transactions, therefore, this statement may not applyto you.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM may make improvementsand/or changes in the product(s) and/or program(s) described in this publicationat any time without notice.

Any references in this information to non-IBM Web sites are provided forconvenience only and do not in any manner serve as an endorsement of those Websites. The materials at those Web sites are not part of the materials for this IBMproduct and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way itbelieves appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purposeof enabling: (i) the exchange of information between independently createdprograms and other programs (including this one) and (ii) the mutual use of theinformation which has been exchanged, should contact:

IBM RTP Laboratory3039 Cornwallis RoadP.O. BOX 12195


Raleigh, NC 27709-2195U.S.A

Such information may be available, subject to appropriate terms and conditions,including in some cases, payment of a fee.

The licensed program described in this document and all licensed materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Program License Agreement, or any equivalent agreementbetween us.

Any performance data contained herein was determined in a controlledenvironment. Therefore, the results obtained in other operating environments mayvary significantly. Some measurements may have been made on development-levelsystems and there is no guarantee that these measurements will be the same ongenerally available systems. Furthermore, some measurement may have beenestimated through extrapolation. Actual results may vary. Users of this documentshould verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers ofthose products, their published announcements or other publicly available sources.IBM has not necessarily tested those products and cannot confirm the accuracy ofperformance, compatibility or any other claims related to non-IBM products.Questions on the capabilities of non-IBM products should be addressed to thesuppliers of those products.

This information may contain examples of data and reports used in daily businessoperations. To illustrate them as completely as possible, the examples may includethe names of individuals, companies, brands, and products. All of these names arefictitious and any similarity to the names and addresses used by an actual businessenterprise is entirely coincidental.

All statements regarding IBM’s future direction or intent are subject to change orwithdrawal without notice, and represent goals and objectives only.

Programming interface informationProgramming interface information, if provided, is intended to help you createapplication software using this program.

General-use programming interfaces allow you to write application software thatobtain the services of this program’s tools.

However, this information may also contain diagnosis, modification, and tuninginformation. Diagnosis, modification and tuning information is provided to helpyou debug your application software.

Warning: Do not use this diagnosis, modification, and tuning information as aprogramming interface because it is subject to change.

Trademarks and service marksThe following terms are trademarks or registered trademarks of InternationalBusiness Machines Corporation in the United States or other countries, or both:


IBMthe IBM logoAIXCrossWorldsDB2DB2 Universal DatabaseMQIntegratorMQSeriesTivoliWebSphere

Lotus, Domino, Lotus Notes, and Notes Mail are trademarks of the LotusDevelopment Corporation in the United States, other countries, or both.Microsoft,Windows, Windows NT, and the Windows logo are trademarks of MicrosoftCorporation in the United States, other countries, or both.

MMX, Pentium, and ProShare are trademarks or registered trademarks of IntelCorporation in the United States, other countries, or both.

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in theUnited States, other countries, or both.

Other company, product or service names may be trademarks or service marks ofothers. IBM CrossWorlds Servers V4.1, IBM CrossWorlds Full Toolset V4.1, IBMCrossWorlds Connectors V4.1, IBM CrossWorlds Collaborations V4.1, WebSphereBusiness Integration Adapters, V2.0

Appendix D. Notices 89

��

Printed in U.S.A.

websphere business integration adapters - ibm · websphere business integration adapters adapter...

Documents