Adapter for MetaSolv TBS (Version 5.x) User Guide · blue text Blue text, which is visible only...

IBM WebSphere Business Integration Adapters

Adapter for MetaSolv TBS (Version 5.x)User GuideVersion 2.5.x

��

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

18April2003

This edition of this document applies to IBM WebSphere InterChange Server, version 4.2,WebSphere BusinessIntegration Adapters, version 2.2.0, and to all subsequent releases and modification until otherwise indicated in neweditions. .

To send us your comments about this document, email [email protected]. We look forward to hearingfrom 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 2000, 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 CrossWorlds Infrastructure version 4.1.1 and 4.2 (if the environment usesISO Latin-1 data only), WebSphere MQ Integrator version 2.1.0, and WebSphereMQ Integrator Broker, version 2.1.0. See Release Notes for any exceptions.

© Copyright IBM Corp. 2000, 2003 iii

iv Adapter for MetaSolv TBS (Version 5.x) User Guide

Contents

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

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

New in this release. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixConnector version 2.5.x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixConnector version 2.4.x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixConnector version 2.2.x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixConnector version 2.1.x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xConnector version 2.0.x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xConnector version 1.1.x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x

Chapter 1. Overview of the MetaSolv connector . . . . . . . . . . . . . . . . . . 1Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Business object request processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Event notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Supported verbs and PSR business processes . . . . . . . . . . . . . . . . . . . . . . . . 4

Chapter 2. Installing and configuring the connector . . . . . . . . . . . . . . . . . 5Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Installing the connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Installing and configuring of Gateway servers and databases . . . . . . . . . . . . . . . . . . . 5Setting up the Gateway servers in the MetaSolv application . . . . . . . . . . . . . . . . . . . 8Setting up the .ini file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Installing the connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Connector configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Startup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Chapter 3. Creating or modifying business objects. . . . . . . . . . . . . . . . . 13Creating objects for the connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Business object attribute properties . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Connector interactions with the integration broker . . . . . . . . . . . . . . . . . . . . . . 19

Appendix A. Standard configuration properties for connectors . . . . . . . . . . . 21New and deleted properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Configuring standard connector properties for WebSphere InterChange Server . . . . . . . . . . . . . 22Configuring standard connector properties for WebSphere MQ Integrator . . . . . . . . . . . . . . 34

Appendix B. Using Connector Configurator . . . . . . . . . . . . . . . . . . . . 43Using Connector Configurator in an internationalized environment. . . . . . . . . . . . . . . . . 43Starting Connector Configurator . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Choosing your broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Using a connector-specific property template . . . . . . . . . . . . . . . . . . . . . . . . 46Using Connector Configurator with ICS as the broker . . . . . . . . . . . . . . . . . . . . . 49Setting the configuration file properties (ICS) . . . . . . . . . . . . . . . . . . . . . . . . 51Setting the configuration file properties (WebSphere MQ Integrator Broker) . . . . . . . . . . . . . . 56Using standard and connector-specific properties with Connector Configurator. . . . . . . . . . . . . 59Completing the configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Appendix C. Connector feature list . . . . . . . . . . . . . . . . . . . . . . . 61

© Copyright IBM Corp. 2000, 2003 v

Business object request handling features . . . . . . . . . . . . . . . . . . . . . . . . . 61Event notification features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61General features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Programming interface information . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Trademarks and service marks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

vi Adapter for MetaSolv TBS (Version 5.x) User Guide

About this document

IBM(R) WebSphere(R) Business Integration Adapters supply integrationconnectivity for leading e-business technologies and enterprise applications.

This document describes the installation, configuration, and business objectdevelopment for the adapter for Metasolv TBS.

AudienceThis document is for WebSphere consultants and customers who are implementingthe connector as part of a WebSphere business-integration system. To use theinformation in this document, you should be knowledgeable in the following areas:v Connector developmentv Business object developmentv MetaSolv application architecture

Related documentsThe WebSphere business integration system documentation describes the featuresand components common to all installations, and includes reference material onspecific collaborations and connectors.

This document contains many references to two other documents: the SystemInstallation Guide for Windows or for UNIX and the System Implementation Guide forWebSphere InterChange Server. If you choose to print this document, you may wantto print these documents as well.

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 MQ Integrator Broker as your integration broker:

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

http://www.ibm.com/websphere/integration/wicserver/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.

bold Indicates a new term the first time that it appears.

© Copyright IBM Corp. 2000, 2003 vii

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

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

italic, italic Indicates a variable name or a cross-reference.blue text Blue text, which is visible only when you view the manual

online, indicates a cross-reference hyperlink. Click any bluetext to jump to the object of the reference.

ProductDir Product family is WBIA: Represents the directory where theIBM WebSphere Business Integration Adapters product isinstalled. The CROSSWORLDS environment variablecontains the ProductDir directory path, which isIBM\WebSphereAdapters by default.

viii Adapter for MetaSolv TBS (Version 5.x) User Guide

New in this release

Connector version 2.5.xUpdated in March, 2003. The “CrossWorlds” name is no longer used to describe anentire system or to modify the names of components or tools, which are otherwisemostly the same as before. For example “CrossWorlds System Manager” is now“System Manager,” and “CrossWorlds InterChange Server” is now “WebSphereInterChange Server.”

Due to testing limitations, only the following APIs are being supported in thecurrent release of MetaSolv:v exportCustomerAccountv exportCustomerAccountsv importNewCustomerAccountv importUpdatedCustomerAccountv exportServiceLocationsv exportCustServiceLocationsv exportAllServiceLocationsv importNewServiceLocationv importUpdatedServiceLocation

Connector version 2.4.xThe changes to version 2.4.x of the connector do not affect the content of thisdocument.

Connector version 2.2.xThe IBM WebSphere Business Integration Adapter for MetaSolv TBS includes theconnector for MetaSolv TBS. This adapter operates with both the InterChangeServer (ICS) and WebSphere MQ Integrator integration brokers. An integrationbroker, which is an application that performs integration of heterogeneous sets ofapplications, provides services that include data routing.

This adapter includes:v An application component specific to MetaSolv TBSv A sample business object, included in the \connectors\MetaSolvTBS\samples

directoryv IBM WebSphere Adapter Framework, which consists of:

– Connector Framework– Development tools (including Business Object Designer and Connector

Configurator)– APIs (including ODK, JCDK, and CDK)

This manual provides information about using this adapter with both integrationbrokers: InterChange Server (ICS) and WebSphere MQ Integrator.

© Copyright IBM Corp. 2000, 2003 ix

Important: Because the connector has not been internationalized, do not run itagainst InterChange Server version 4.1.1 if you cannot guarantee thatonly ISO Latin-1 data will be processed.

Connector version 2.1.xThe changes made for version 2.1.0 of the connector do not affect the content ofthis document.

Connector version 2.0.xVersion 2.0.0 of the connector includes the following new features and changes:v The connector now supports MetaSolv 5.0 API.v The following connector properties have been removed: OrbixClasses,

ConnectorClasses, APIClasses, APIHost, APIServer, SQLNetConnectString.v New connector properties have been added: MSLVPSRIORfile, JDBCDriverClass,

DatabaseURL.v Oracle thin driver is the default JDBC driver to connect to the IBM CrossWorlds

database where event and archive tables reside.

Connector version 1.1.xVersion 1.1.0 of the connector includes the following new features and changes:v The connector now supports event notification through the MetaSolv API for the

PSR OrderEntry module.

x Adapter for MetaSolv TBS (Version 5.x) User Guide

Chapter 1. Overview of the MetaSolv connector

This chapter describes the connector component of the IBM WebSphere BusinessIntegration Adapter for MetaSolv TBS. The connector enables an integration brokerto exchange business objects with MetaSolv TBS 5.0.3.

Connectors consist of an application-specific component and the connectorframework. The application-specific component contains code tailored to aparticular application. The connector framework, whose code is common to allconnectors, acts as an intermediary between the integration broker and theapplication-specific component. The connector framework provides the followingservices between the integration broker and the application-specific component:v Receives and sends business objectsv Manages the exchange of startup and administrative messages

This document contains information about the application-specific component andconnector framework. It refers to both of these components as the connector.

For more information about the relationship of the integration broker to theconnector, see the IBM WebSphere InterChange Server System Administration Guide, orthe IBM WebSphere Business Integration Adapters Implementation Guide for WebSphereMQ Integrator Broker.

This chapter covers the following topics:v “Architecture”v “Business object request processing” on page 2v “Event notification” on page 2v “Supported verbs and PSR business processes” on page 4

ArchitectureFigure 1 shows the connector components and their relationships within theWebSphere business integration system. The figure assumes that WebSphereInterChange Server is being used as the integration broker.

© Copyright IBM Corp. 2000, 2003 1

Business object request processingThe connector processes business object requests that it receives from theintegration broker. When the connector receives a request to perform anapplication operation, it uses the Business Object Handler to extract the data fromthe application-specific business object, and communicates with the MetaSolvapplication by using the API provided by MetaSolv. The connector usesadapter-delivered meta-objects, business object definitions, attribute descriptions,and the values in a business object instance to generate function calls that accessthe MetaSolv application database tables, which are contained in an instance of anOracle database dedicated to the MetaSolv application. These function callsperform operations on the data in the database, as required by the business objectand verb that the connector is processing.

Event notificationEvent Notification in the connector is handled through the adapter-deliveredGateway Server. An event is triggered when a task is initiated in “Waiting” status.The MetaSolv Client sends the event to the Gateway Server or the PSR BillingGateway Server depending on the type of event. The Gateway Server reads theevent details from the Event Notification object and places the event in thebusiness-integration system’s event table. This table can be created in any Oracledatabase.

Figure 1. Architecture of the connector (with WebSphere InterChange Server the integration broker)

2 Adapter for MetaSolv TBS (Version 5.x) User Guide

Gateway serverGateway Servers are responsible for extracting event information from theMetaSolv Client event notification and creating an event in the event table. Thereare two adapter-delivered Gateway Servers:v CwGatewayServer handles the Gateway events related to Service Requests.v CwPSRBillingGatewayServer handles the Customer related events. Currently this

server handles only create events for customer and order.

These servers should run on the same machine as the MetaSolv Application Serveris running.

An event is triggered when a MetaSolv task gets initiated. The MetaSolv Clientthen sends the Service Request and/or Customer Gateway Event to theappropriate Gateway Server. When the event is successfully populated in the eventtable, a status of completed is returned to the MetaSolv Client via the MetaSolvApplication Server.

If the event does not get populated, a status of error is be returned to theMetaSolv Client. If the error is related to the WebSphere business-integrationsystem’s database, a notification e-mail is sent. The e-mail address must bespecified as a parameter in the CwGatewayServer.bat andCwPSRBillingGatewayServer.bat files.

If the MetaSolv Application Server is down, the status of the gateway events isWaiting until the MetaSolv Application Server is brought up.

The MetaSolv Client must be restarted Whenever the Gateway Servers arerestarted. MetaSolv Client gets a handle to the Gateway Server when it first sendsthe Gateway event. When a Gateway Server is restarted, the old handle is nolonger valid.

Note: Any change to the WebSphere business-integration system’s event tabledefinition affect the Gateway servers.

Processing application events

Event retrievalThe connector polls the event table at configurable intervals. The connector picksup all unprocessed events in the event table, processes them, and then archivesthem. The number of events a connector can process at any time is determined bythe PollQuantity connector property. The connector builds a query to extractevents from the event table.

Each time the connector is started, it updates the InProgress events toReadyForPoll and sets their priority to 0. This ensures that the status is updatedfor InProgress events in case the connector is abnormally shut down.

Create notificationWhen the connector encounters a Create event in the event table, it instantiates anobject of the type specified by the event, sets the doc number for the object, andretrieves it through the MetaSolv Application Server APIs. When it is retrieved, theobject is sent to the integration broker.

Chapter 1. Overview of the MetaSolv connector 3

Update notificationWhen the connector encounters an Update event in the event table, it instantiatesan object of the specified type, sets the doc number for the object, and retrieves itby using the MetaSolv APIs. When it is retrieved, the object is sent to theintegration broker.

ArchivingWhen an event is deleted from the event table it is placed in the archive table. Thearchive table provides a means of recovering events that are not successfullyprocessed, and a history of events that can be used to audit event processing.

To enable archiving, the ArchiveProcessed must be set to true. If theArchiveProcessed property is set to false:v If the event is successfully processed, it is deleted from the event table and

without being archived.v If the object in the event is not subscribed, the event remains in the event table

with a status of Unsubscribed.v If the object faces a problem while being processed it remains in the event table

with event status set to Ready for Poll.

The ArchiveProcessed property defines whether unsubscribed or unprocessedevents are archived. The archive table is specified through the configurationproperty ArchiveTableName.

Supported verbs and PSR business processesThe connector supports Create, Update and Retrieve for Event Notification andBusiness Object Request processing.

Note: The PSR Billing Gateway Server currently inserts only Create events forCustomer and Order.

The connector supports the following business processes:v Customer Accountv Service Locationv Order (Service Request)

For each of these PSR business processes, the connector contains a hard-codedmethod for each of the three verbs.


Chapter 2. Installing and configuring the connector

This chapter describes how to install and configure the connector and how toconfigure the MetaSolv application to work with the connector. The followingtopics are covered:v “Prerequisites”v “Installing the connector”v “Installing and configuring of Gateway servers and databases”v “Setting up the Gateway servers in the MetaSolv application” on page 8v “Setting up the .ini file” on page 8v “Installing the connector” on page 9v “Connector configuration” on page 9v “Startup” on page 11

Prerequisites

MetaSolv application requirementsThe connector supports business object processing and event publishing for thePSR (Product Service Requests) module in MetaSolv version 5.0.3.

In this document it is assumed that MetaSolv has been properly installed andconfigured with its prerequisite software and that there is a functioning MetaSolvApplication Server.

For more information about installing MetaSolv and its prerequisite software,consult the MetaSolv application documentation.

Connector third-party dependenciesThe connector uses JBroker, the Java version of CORBA from SilverStream. Thefollowing are requirements for running the connector:v Complete installation of the MetaSolv Application Serverv JBroker class libraries

Installing the connectorThe connector is installed during the product installation. For instructions oninstalling software, see the System Installation Guide for your platform.

Installing and configuring of Gateway servers and databasesThe CwGatewayServer and CwPSRBillingGatewayServer are the gateway eventhandling servers. They must run on the same machine where the MetaSolvApplication Server is running.

To set up the Gateway Servers:1. On the MetaSolv Application Server machine, create the following directories:

v \ProductDir

v \ProductDir\GWDependencies


v \ProductDir\GWServer

2. Copy the following files from%ProductDir%\Connectors\MetaSolvTBS\dependencies to the GWServersubdirectory on the MetaSolv Application Server machine:v CwGatewayServer.jar

v RunCwGatewayServer.bat

v CwPSRBillingGatewayServer.jar

v RunCwPSRBillingGatewayServer.bat

3. Start the MetaSolv Application Server.4. Set up event and archive tables:

a. Create an Oracle database instance for the event and archive tables. The sizeof the database depends on your event and archive volume. A minimum of2MB is recommended.

b. Locate the Event_Table.sql script files in the%ProductDir%\connectors\MetaSolv\dependencies directory.

c. Run the script in your new Oracle database instance to create event andarchive tables.

Table 1 describes the event and archive table schema.

Table 1. Event and archive table schema

Name Description Type Constraint

event_id Internal identifier of the event NUMBER Primary keyconnector_id Unique ID of the connector for

which the event is destined. Thisvalue is important when multipleconnectors poll the same table

NUMBER

object_key Primary key of the business object.Multiple keys can be concatenatedwith a colon or other configurabledelimiter, for example,1000065:10056:23333

VARCHAR Not null

object_name Name of the Business Object STRING Not nullobject_verb verb associated with the event STRING Not nullevent_priority Event priority (0 is the highest, n

is the lowest); which the connectoruses to pull events on a prioritybasis. The connector does not usethis value to lower or raisepriorities.

NUMBER Not null

event_time Date and time when the eventoccurred

DATE Default currentdate/time (forarchive table,actual eventtime)

event_status This attribute is used only in theevent table. 0 - Ready for poll 1 -Sent to InterChange Server 2 -Unsubscribed event 3 - In progress-1 = Error processing event -2 =Error sending event to theintegration broker

NUMBER Not null

event_comment Name of the tasks that have beencompleted

STRING


Table 1. Event and archive table schema (continued)

Name Description Type Constraint

archive_time Date and time when the event wasarchived (applies only to thearchive table)

DATE Archivedate/time

5. Locate runcwgatewayserver.bat and runcwpsrbillinggatewayserver.bat in the%ProductDir%\connectors\MetaSolv\dependencies directory. Edit the files toinclude the required path information and parameters as indicated in the filecomments.The following example illustrates how to set the parameters in the .bat files.Remember to set the directories specific to your environment. Do not delete thecomments provided in the .bat files. Table 2 describes the parameters in theGateway Server batch files.

setlocalset PATH=%PATH%set CROSSWORLDS=path to the CrossWorlds directory on the API Server machine which was created earlier.

REM name of the directory which contains the appserver.jar, jbroker.jar, jbroker_stubs.jar,JBrokerLicenses.class, mail.jar and activation.jarset DEPENDENCIES=xxxx

REM name of the directory which contains the jar of the gateway serverset SOURCE_DIR=xxxx

REM USER_NAME is the Event table user nameset USER_NAME=system

REM USER_NAME is the Event table passwordset PASSWORD=manager

REM DATABASE_URL is the URL for the event table databaseset DATABASE_URL=xxxx

REM EVENT_TABLE is the name of the Event tableset EVENT_TABLE=xworlds_events

REM GATEWAY_IOR is the name of the CrossWorlds gateway server IOR fileset GATEWAY_IOR=CwGatewayServer.ior

REM EMail ID of the database administratorset EMAIL_ID=xxxx

REM INI_FILE_NAME is the name of the INI file which has the events names and the BO namesset INI_FILE_NAME=GatewayEvents.ini

REM MAIL_SERVER is the name of the Mail Serverset MAIL_SERVER=xxxx

6. Save and close the files.7. Run runcwgatewayserver.bat and runcwpsrbillinggatewayserver.bat by

double-clicking on their file icons.

Table 2. Parameters for Gateway server batch files

Parameter Required Example Description

-u Yes -usystem Event table user name.-p Yes -pmanager Event table password.-n Yes -nevt SQL net connect string for event table

database name.

Chapter 2. Installing and configuring the connector 7

Table 2. Parameters for Gateway server batch files (continued)

Parameter Required Example Description

-t Yes -txworlds_events Event table name. The default value isxworlds_events.

-s Yes -sCWGatewayServer .ior Name of the IBM CrossWorlds GatewayServer IOR file.

-e Yes [email protected] Database Administrator’s e-mail ID.-m Yes cage Mail Server Name.-i For CwGatewayServer

onlyGatewayEvents.ini See “Setting up the .ini file” for more

information.

Setting up the Gateway servers in the MetaSolv application

Note: Before beginning, make sure the WM gateway Event Processing Preferenceis enabled.

To set up the Gateway Server:1. In the Work Management screen, select the Gateways tab.2. Click the New button on the Gateways tool bar.3. In the Name field, enter the name of the new gateway.4. In the Number of Retries field, enter the number of times the gateway event

server should attempt to connect with the Gateway Server before setting theevent status to error.

5. In the retry interval (secs) field, enter the number of seconds that you wantthe gateway event server to wait between retries.

6. In the Module field, select the name of the IDL module in which the WDImanager is defined.

7. In the Description field, enter a description of the gateway.8. In the Username and Password fields, enter the values that the gateway needs

to contact the Gateway Server. If no values are needed, leave these fieldsblank.

9. Save.10. Right click on your new gateway event and choose a new binding.11. Select the IOR radio button.12. Add the location where the gateway event server looks for the IOR file

generated by the external application.

Setting up the .ini fileThe Gateway Event names are not hardcoded in the MetaSolv application,therefore CwGatewayServer uses an .ini file to determine which Business Objectto retrieve based on the Gateway Event Name. You must create a text file with the.ini extension. This file must reflect the Gateway Event names in your MetaSolvapplication. The Gateway Event names must be linked to triggering tasks in theMetaSolv application. Changes to the names of Gateway Events in the MetaSolvClient also impact the Gateway Server.

Note: The .ini file is not required for the PSR Billing Gateway.

The format of entries in the .ini file is<Gateway_Event_Name><tab><Business_Object_Name>. For example:


PSR_CREATE_DD MetaSolv_ServiceRequest

Testing the Gateway serverUse the following procedure to test the Gateway Server:1. Start the CwGatewayServer or the CwPSRBillingGateway server by running the

runcwgatewayserver.bat and runcwpsrbillinggatewayserver.bat file on theMetaSolv Application Server machine.

2. From the MetaSolv Client, send a Gateway Event that is registered with theserver. If the Gateway Server is able to extract the event information and insertthe event into the event table, a status of complete is sent.v If the event is processed successfully, the server returns a status of

“Completed.”v If the event is errored, the server returns a status of “Errored.”v If no status is returned, the event is waiting for a response from the server.

Installing the connectorTo install the connector, do the following:1. Enter the DatabaseURL for accessing the database on which event and archive

tables reside. Oracle thin driver is the default JDBC driver for the connector.2. Ensure that the MetaSolv Application Server is running. The connector cannot

start if the MetaSolv Application Server is not running.3. In the MetaSolv Client machine, create a path to the IOR file in the MetaSolv

Application Server machine.4. Install the connector by running the WebSphere business-integration system’s

installation program and selecting the connector from the list of connectors.When you do this, the installation program installs the connector agent.jar intothe %ProductDir%\connector\<MetaSolvTBS> directory. The installation programadds an icon for the connector agent file to the WebSphere business-integrationsystem’s menu.

After installing the connector, set the connector configuration properties, asdescribed in the Connector Configuration section.

Connector configurationConnectors have two types of configuration properties: standard configurationproperties and connector-specific configuration properties. You must set the valuesof some of these properties before running the connector.

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. Changesto some connector configuration properties, such as AgentTraceLevel, take effectimmediately. Changes to other connector properties require component restart orsystem restart after a change. To determine whether a property is dynamic (takingeffect immediately) or static (requiring either connector component restart orsystem restart), refer to your integration broker’s administration utility. Forinstance, if you are using WebSphere InterChange Server, see the Update Methodcolumn in the Connector Properties window of the System Manager.

If you are using WebSphere MQ Integrator Broker as the integration broker, youconfigure connector properties from the Connector Configurator. If you are using


WebSphere InterChange Server as the integration broker, you configure connectorproperties from Connector Designer, which you access from System Manager.

Standard connector propertiesStandard configuration properties provide information that all connectors use. SeeAppendix A, “Standard configuration properties for connectors”, on page 21 fordocumentation of these properties.

Important: Because this connector supports all integration brokers, configurationproperties for al brokers are relevant to it.

Note: Because this connector is single threaded, it cannot take advantage of theAgentConnections property.

Connector-specific propertiesConnector-specific configuration properties provide information needed by theconnector agent at run time. Connector-specific properties also provide a way ofchanging static information or logic within the connector agent without having torecode and rebuild the agent.

Table 3 lists the connector-specific configuration properties for the connector. Seethe sections that follow for explanations of the properties.

Table 3. Connector-specific configuration properties

Name Possible values Default value Required

ArchiveProcessed true/false trueArchiveTableName Name of archive table xworlds_archive_eventsDatabaseURL metasolv:weblogic:oci:metasolv No default value Yes

EventDBBrand JDBC driver database type OracleEventDBPassword Event database password oracleEventDBUsername Login to event database username internalEventTableName Name of event table xworlds_eventsJDBCDriverClass Specifies the class name of the driver

weblogic.jdbc.oci.DriverNo default value Yes

MaxEvents Number of events per poll 25MSLVPassword MetaSolv server password asapMSLVPSRIORfile The API uses IOR files to route events

to/from the MetaSolv applicationH:\PSRSERVER.ior

MSLVUserName Username for MetaSolv server asap No

ArchiveProcessedSpecifies whether the connector archives events for which there are no currentsubscriptions. Set this property to true to cause events to be inserted into thearchive table after they are deleted from the event table.

ArchiveTableNameName of the archive table. The default value is xworlds_archive_events.

DatabaseURLURL String for accessing the WebSphere business-integration system’s database.There is no default value. URL should follow the Oracle thin driver’s format as thedefault driver is Oracle thin driver.


EventDBBrandDatabase type for the JDBC Driver. The default value is Oracle.

EventDBPasswordPassword for the login into the event table database. The default value is asap.

EventDBUsernameUser name for the login into the event table database. The default value is asap.

EventTableNameName of event queue table. The default value is xworlds_events.

JDBCDriverClassClass name of the JDBC driver. Use to connect to the database where event andarchive tables reside.

MaxEventsMaximum number of event processes during one poll. The default value is 25.

MSLVPasswordPassword for the login into the MetaSolv server. The default value is asap.

MSLVPSRIORfilePath to the PSR Server’s IOR file.

MSLVUserNameUsername for the login into the MetaSolv server. The default value is asap.

StartupFor information on starting a connector, stopping a connector, and the connector’stemporary startup file, see the IBM WebSphere Business Integration AdaptersImplementation Guide for WebSphere MQ Integration Broker, or, for WebSphereInterChange Server, see the IBM WebSphere InterChange Server System AdministrationGuide.


Chapter 3. Creating or modifying business objects

The connector is driven primarily by meta-data that is contained in WebSphereBusiness Integration Adapter business objects and meta-objects.

In WebSphere Business Integration Adapter business objects, meta-data is dataabout the application that is stored in a business object and that assists theconnector to interact with an application. A meta-data-driven connector handleseach business object that it supports based on meta-data encoded in the businessobject definition rather than on instructions hard-coded in the connector.

The connector makes assumptions about the structure of its business objects,including:v The format of the application-specific text.v The relationships between parent and child business objects.v The database representation of the business object.

The connector follows rules based on those assumptions, and when you create ormodify a business object for MetaSolv, the business object must conform to thoserules for the connector to process the business object correctly.

This chapter describes the assumptions the connector makes and how theconnector processes business objects. You can use this information as a guide tomodifying existing business objects for MetaSolv or as suggestions forimplementing new business objects. The following topics are covered:v “Creating objects for the connector”v “Business object attribute properties” on page 19v “Connector interactions with the integration broker” on page 19

Creating objects for the connectorTo use the connector for PSR, you need to create three types of objects:v Meta-objects, which tell the connector how to send a business object into the

MetaSolv API.v The application-specific business objects for the business processes that you

intend to use.

Creating meta-objectsThe connector uses the Java.Reflection class to dynamically call MetaSolv APIs toexchange data with the TBS application. To do this, the connector requiresmeta-objects. Meta-objects contain the information needed to build dynamic calls tothe MetaSolv API. The meta-objects must be loaded into the repository, along withthe application-specific business objects for MetaSolv.

You must create a meta-object for each top-level application-specific business objectand verb that you intend to use. You do not need to create individual meta-objectsfor child business objects. The meta-object is a flat, non-hierarchical object.

For example, the PSRCustomerAccount business object requires the followingmeta-objects, one for each of the PSRCustomerAccount verbs:


v MO_MetaSolvTBS_Customer_Createv MO_MetaSolvTBS_Customer_Updatev MO_MetaSolvTBS_Customer_Retrieve

The meta-objects all have a similar set of attributes and properties. You can use onemeta-object as a model for creating all others, with changes to just a few values.

The following example shows the MO_MetaSolvTBS_Customer_Create meta-object,with italics distinguishing the values that you can change if you use this text as amodel for another meta-object:[BusinessObjectDefinition]Name = MO_MetaSolvTBS_Customer_CreateVersion = 1.0.0[Attribute]Name = methodToCallType = StringCardinality = 1MaxLength = 255IsKey = trueIsForeignKey = falseIsRequired = falseAppSpecificInfo = importNewCustomerAccountIsRequiredServerBound = false[End]

[Attribute]Name = javaClassType = StringCardinality = 1MaxLength = 255IsKey = falseIsForeignKey = falseIsRequired = falseIsRequiredServerBound = false[End]

[Attribute]Name = PSRCustomerAccountType = MetaSolv_Connector_ObjectContainedObjectVersion = 1.0.0Relationship = ContainmentCardinality = 1MaxLength = 0IsKey = falseIsForeignKey = falseIsRequired = falseAppSpecificInfo = 7:MetaSolv.CORBA.WDIPSR.data.PSRCustomerAccountIsRequiredServerBound = false[End]

[Attribute]Name = ObjectEventIdType = StringCardinality = 1MaxLength = 255IsKey = falseIsForeignKey = falseIsRequired = falseIsRequiredServerBound = false[End]

[Verb]Name = Create[End]

[Verb]Name = Delete


[End]

[Verb]Name = Update[End]

[End]

Setting property values for meta-objectsThe following table describes the attribute properties that have different values fordifferent meta-objects, and how the connector interprets them:

Property Meaning

Name (For top-level Business ObjectDefinition)

Name of this meta-data business object

AppSpecificInfo (For the methodtoCallattribute)

The name of the method to be called inthe connector, such as:

ImportNewCustomerAccountName (For attribute that hasType=MetaSolv_Connector_Object; createsthe business object for a Create or Update)

The name of the business object beingreferenced by this meta-object, such as:

PSRCustomerAccountName (for the primary key in a Retrieve) A string that is the primary key value for

retrieving the business object. For example,for PSRCustomerAccount, the value is:

custAcctIDAppspecificInfo (For attribute that hasType=MetaSolv_Connector_Object)

The Java class for the business object beingreferenced, such as:

7:MetaSolv.CORBA.WDIPSR.data.PSRCustomerAccount

Supported methodsMeta-objects call specific methods that have been hard-coded in the connector. Youcan create meta-objects only for the PSR business processes and verbs for whichthe hard-coded methods exist in the connector. Currently, these include thefollowing:v importPSROrder

v importNewCustomerAccount

v importUpdatedCustomerAccount

v importNewServiceLocation

v importUpdatedServiceLocation

v exportAllServiceLocations

v exportOrder

v exportCustomerAccount

v export Customer Account

v export Customer Service Locations

v export-All Product Catalog

v get telnbrs

v export Item Spec

v export Item Spec Children

v export Value Order

v export Service Location

Chapter 3. Creating or modifying business objects 15

Creating the customer account and other business objectsThis section describes the basic procedure for creating a WebSphere BusinessIntegration Adapter business object that is application-specific for the PSR (ProductService Request) feature of the MetaSolv TBS application.

All MetaSolv TBS PSR business tasks require that a MetaSolv TBS CustomerAccount data entity exist. Consequently, a WebSphere Business Integration Adapterapplication-specific business object that corresponds to the Customer Account dataentity must be created before any other business objects can be used for PSR tasks.

The procedure for creating the business object includes the following general steps:1. Obtain the PSRTypes.idl file from the MetaSolv website.2. Locate the data for the PSRCustomerAccount structure in the PSRTypes.idl file.

The data may appear, for example, in a columnar format as illustrated below.In this example, the column on the right shows the name of a data field in thePSRCustomerAccount data entity; the column on the left shows the Type forthat data. (Note that this is an example only; it has been modified, and is notintended to show the actual data.) struct PSRCustomerAccount

long accessCustomerNumber;

AccountStatusEnum accountStatus;

string acctSecurity;

DateStruct extractCreationDt;

char middleInitial;

BillingAccountUnion billingAccount;

3. Create a CustomerAccount business object, with attributes that correspond tothe data in the PSRTypes.idl file. The names of the business object attributesmust match exactly the names of attributes in thePSRTypes.idl file. (To identifyrequired attributes and to select attributes that you want to use to accomplishspecific business tasks, you can open the CustomerAccount window inMetaSolv TBS PSR and correlate the fields displayed with items in thePSRTypes.idl file.)

4. Provide appropriate application-specific information in each AppSpecificInfofield of the business object. Use the syntax described in the next section, “Usingapplication-specific data”.

Note: The attributes in the WebSphere Business Integration Adapter businessobject should have the same case expected by the MetaSolv API. For furtherinformation about exact case structure in the MetaSolv API, consult theWDIPSR.idl file.

Using application-specific data

Data transformations: The connector extracts data from a business object in anall-String data format. In that process, the following data transformations takeplace:v The connector converts all dates to date structures.v For Enumerated types, the connector uses the value definitions in the IDL files

to convert String values from the business object into valid CORBAenumerations.

v Primary data attributes are grouped together in object and sub-object structures.


The following table shows special considerations for using application-specific datatypes:

Data type Comments

String The String is copied. Single quotation marksare replaced with a space, because the APIcannot handle single quotation marks.

Long If the string representing the attribute valueis not of the correct number format, an errormessage is logged and processing of thebusiness object stops.

Float If the string representing the attribute valueis not of the correct number format, an errormessage is logged and processing of thebusiness object stops.

Character The first character of the value of thebusiness object attribute is used.

Enumeration The connector uses the values defined in theIDL files and converts them into a validCORBA enumeration, and also converts abusiness object sent through CORBA backinto a string representation.

AppSpecificInfo format: The connector requires that the text strings in theAppSpecificInfo field be structured in the following format:v A numeral represents the intended data type.v A colon follows the numeral.v Data other than the data type (such as a class package or an Enumerated type)

is appended after the colon.

The syntax for this format is:data_type:class_package (if required)

The following table shows the numerals that indicate specific data types for theMetaSolv API, and indicates whether additional data needs to be appended:

Numeral Data type Additional data (if required)

0 Integer/Long none1 Float/Double none2 Character none3 String none4 Enumerated Type class package5 Date Structure class package6 Object/Seq class package7 Union class package8 Other

For example, to represent a long data type, in the AppSpecificInfo field of thebusiness object, you enter:0:

Similarly, the character and string data types are represented in theAppSpecificInfo field by the following:


2:3:

If the data type is an enumerated type, a date structure, or a MetaSolv object orunion, the full class package must appear in the AppSpecificInfo field. The classpackage tells the connector how to locate the associated Java file that it will beworking with. For example, for a date structure, enter5:MetaSolv.CORBA.WDIPSR.data.DateStruct in the AppSpecificInfo field, becausethat is the full class package to the DateStruct class that enables MetaSolv tohandle date structures.

Not all attributes or sub-objects within the MetaSolv API are supported for bothexporting from and importing into the MetaSolv API. In order to allow the use ofthe same business object in both directions, it is necessary to avoid the setting ofnon-supported fields. This is achieved by an additional parameter in theapplication-specific information, as described in the following table:

Character Meaning

N Not supported in the APII Supported only during importE Supported only during exportA Supported during import and export (Default)

This attribute is specified at the third place in the AppSpecificInfo field (forexample, 0::I indicates an integer value that is supported only during inboundoperations).

If this meta attribute is not specified, the connector assumes that the attribute issupported during import and export.

Business object structure for MetaSolv TBSWebSphere Business Integration Adapter business objects are hierarchical: parentbusiness objects can contain child business objects, which can in turn contain childbusiness objects, and so on.

For the connector, the containment relationship between a parent and a childbusiness object can have cardinality 1 or cardinality n. In addition, the connectorsupports a parent/child object relationship of type Union:v A cardinality 1 container occurs when an attribute in a parent business object

references a single child object.v A cardinality n container object occurs when an attribute in the parent business

object references an array of child business objects. The array can contain zero ormore child business objects.

v A container that has the type Union can contain child business objects ofdifferent types. The child object that is being used in the relationship is definedby a type attribute of its parent. This type is usually used to implement a childobject that has a cardinality of 1, but that is optional for its parent.


Business object attribute propertiesBusiness object architecture defines various properties that apply to attributes. Thissection describes how the connector interprets several of these properties anddescribes how to set them when modifying a business object.

Property Meaning

Default Value Used when the attribute in the businessobject is not set, and the Required property isset to True.

Max Length v The maximum length of the attribute asdefined by the application attributedefinition. That is, if the correspondingcolumn for an attribute is defined asvarchar(40) in the Oracle database forMetaSolv TBS, then the Max Length valuein the business object is 40.

v If the connector receives a business objectwith attribute values that exceed the limitset in the Max Length field of the businessobject, the values are truncated before theconnector passes the data to the MetaSolvAPI, and a warning message is written tothe connector log.

Name Name of the attribute as it appears in theMetaSolv TBS API.

Type All simple types are of type String.Foreign Key Not used.Key Defines the Key value of the business object.Required

Note: The connector does not support specifying an attribute that represents achild business object or an array of child business objects as a key attribute.

Special attribute values

IsIgnore, IsBlankThe MetaSolv API requires that every attribute be specified when the API object issent to the server. For both CxIgnore and CxBlank, the connector uses theWebSphere Business Integration Adapter-defined blank value.

The connector uses IsBlank as the business object equivalent of a fixed-lengthstring, up to the maximum length of the attribute.

Date FormatThe connector expects dates in the WebSphere Business Integration Adaptergeneric date format (YYYYMMDD hhmmss). However, the time information isignored, because the MetaSolv API does not support time.

Connector interactions with the integration brokerThe connector handles business objects in response to requests from the integrationbroker.


Business object retrievalWhen the connector receives an integration broker’s request to retrieve a businessobject, it returns a business object that corresponds exactly to the current MetaSolvapplication database representation of that business object. That is, for each simpleattribute of each individual business object within a hierarchical business object,there is a value from a corresponding attribute in the MetaSolv database. Inaddition, the connector populates hierarchical business object containers with theexact number of individual business objects that exist in the application.

Verb determinationIn the WebSphere Business Integration Adapter business object structure, eachindividual business object within a hierarchical business object contains its ownverb. If the connector receives from the integration broker a business object thathas different verbs for parent and child business objects, the connector uses onlythe verb of the top-level parent business object in processing the business object.Verbs of child business objects are ignored by the connector if they differ from theverb of the parent business object.

After-images versus deltasThe connector is implemented to handle after-image business objects.


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 WebSphere InterChangeServer

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 dynamicApplicationName application name the value that is specified for the

connector namecomponentrestart

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,ContainerManagedEvents mustbe <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. IfFactoryClassName isSonic, uselocalhost:2506.

crossworlds.queue.manager server restart JMS transportonly

jms.FactoryClassName CxCommon.Messaging.jms.IBMMQSeriesFactory orCxCommon.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 23


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 when theletter p is entered in theconnector’s CommandPrompt window)

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 where repositoryis 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 queue name CONNECTORNAME/SOURCEQUEUE componentrestart

Valid only ifdeliverytransport isJMS andContainerManagedEvents isspecified.

SynchronousRequestQueue CONNECTORNAME/SYNCHRONOUSREQUESTQUEUE

componentrestart



Defaultvalue

Updatemethod

Notes

“SynchronousResponseQueue” onpage 40

CONNECTORNAME/SYNCHRONOUSRESPONSEQUEUE

componentrestart

SynchronousRequestTimeout 0 componentrestart

“WireFormat” on page 41 CwXML, CwBO cwxml agent restart CwXML fornon-ICSbroker; CwBOif RepositoryDirectory is<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 either


multi-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 to ensure thatduplicate events are not delivered to the delivery queue. To make use of thisfeature, during connector development a unique event identifier must be set as thebusiness object’s ObjectEventId attribute in the application 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” on page 32 and “OADRetryTimeInterval” onpage 32 are related 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”.

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

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 WMQICharacterEncoding 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.IBMMQSeriesFactory

jms.MessageBrokerName If FactoryClassName isIBM, 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


Name Possible values Default value

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 must


manually 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 to ensure thatduplicate events are not delivered to the delivery queue. To make use of thisfeature, during connector development a unique event identifier must be set as thebusiness object’s ObjectEventId attribute in the application 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 27.

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. Using 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. Using Connector Configurator 45

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

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 52. 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 45.

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

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

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 56. 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 connector. For descriptions ofthese features, see “Appendix A: Connector Feature Checklist” in the ConnectorDevelopment Guide for Java.

Business object request handling featuresTable 4 lists business object request handling features supported by the connector.

Table 4. Business object request handling features

Category Feature Support Notes

MetaSolv Subcategory Feature Name Support (seekey)

Notes

Create Create verb FullDelete Delete verb N/A Application does not support delete.

Logical delete NoExist Exist verb N/AMisc Attribute names Full

Business object names FullRetrieve Ignore missing child object N/A The MetaSolv application does not accept

some objects if all children are not present. Anexample is Account, which is not createdunless the billing/service category andaddress are present.

RetrieveByContent Ignore missing child object N/A The MetaSolv application does not acceptsome objects if all children are not present. Anexample is Account, which is not createdunless the billing/service category andaddress are present.

Multiple results NoRetrieveByContent verb No

Update After-image support FullDelta support NoKeepRelations No

Verbs Retrieve verb FullSubverb support N/AVerb stability Full

Event notification featuresTable 5 lists the event notification features supported by the connector.

Table 5. Event notification features


Connector Properties Event distribution PartialPollQuantity Full

Event table Event status values FullObject key FullObject name FullPriority Full

Misc. Archiving Full


Table 5. Event notification features (continued)


CDK methodgotApplEvent

Full

Delta event notification NoEvent sequence NoFuture event processing NoIn-Progress event recovery FullPhysical delete event NoRetrieveAll FullSmart filtering N/AVerb stability Full

General featuresTable 6 lists the general features supported by the connector.

Table 6. General features


Business ObjectAttributes

Foreign key No

Foreign Key attributeproperty

No

Key FullMax Length FullMeta-data-driven design FullRequired Full

Connection Lost Connection lost on poll FullConnection lost on requestprocessing

No

Connection lost while idle FullConnector Properties ApplicationPassword Full

ApplicationUserName FullUseDefaults Full

Message Tracing General messaging Partial The connector supports all tracing, with thefollowing modifications: level 3=process ofbusiness object subobject method entry andexit, level 4=processing attribute, level5=loading classes.

generateMsg() NoTrace level 0 PartialTrace level 1 PartialTrace level 2 PartialTrace level 3 PartialTrace level 4 PartialTrace level 5 Partial

Misc. CDK method LogMsg FullJava Package Names FullLogging messages Full What is logged depends on the trace level.NT service compliance FullTransaction support Full

Special Value CxBlank processing NoCxIgnore processing Full Connector will ignore the attribute with the

value CxIgnore


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 WebSphere InterChange Server V4.2, IBM WebSphere BusinessIntegration Toolset V4.2, IBM WebSphere Business Integration Adapters V2.2, IBMWebSphere Business Integration Collaborations V4.2.

Notices 65

��

Printed in U.S.A.

Adapter for MetaSolv TBS (Version 5.x) User Guide · blue text Blue text, which is visible only...

Documents

Transcript of Adapter for MetaSolv TBS (Version 5.x) User Guide · blue text Blue text, which is visible only...