adapter for peoplesoft (version 7.x) user guide · pdf fileviii adapter for peoplesoft...

IBM WebSphere Business Integration Adapters

Adapter for PeopleSoft (Version 7.x) UserGuideVersion 3.4.x

��

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

14March2003

This edition of this document applies to connector version 3.4.0 and to all subsequent releases and modificationsuntil otherwise indicated in new editions.

To send us your comments about this documentation, email [email protected]. We look forward tohearing from you.

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

© Copyright International Business Machines Corporation 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 versions2.2.0, IBM WebSphere InterChange Server versions 4.1.1 and 4.2, WebSphere MQIntegrator version 2.1.0, and WebSphere MQ Integrator Broker, version 2.1.0. SeeRelease Notes for any exceptions.

© Copyright IBM Corp. 2000, 2003 iii

iv Adapter for PeopleSoft (Version 7.x) User Guide

Contents

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

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

New in this release. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixNew in Release 3.4.x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixNew in Release 3.3.x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

Chapter 1. Overview of the connector . . . . . . . . . . . . . . . . . . . . . . . 1Communication between the connector and PeopleSoft . . . . . . . . . . . . . . . . . . . . . 1

Chapter 2. Installing and configuring the connector . . . . . . . . . . . . . . . . . 3Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Installing the connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Required modifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Event table structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Configuring the connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Starting the connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Chapter 3. Developing business objects for the connector . . . . . . . . . . . . . 11Business object application-specific text . . . . . . . . . . . . . . . . . . . . . . . . . . 11Modifying business objects for the connector . . . . . . . . . . . . . . . . . . . . . . . . 12Transaction processing for hierarchical business objects . . . . . . . . . . . . . . . . . . . . . 15

Appendix A. Standard Configuration Properties for Connectors . . . . . . . . . . . 17New and deleted properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Configuring Standard Connector Properties for WebSphere InterChange Server. . . . . . . . . . . . . 18Configuring Standard Connector Properties for WebSphere MQ Integrator . . . . . . . . . . . . . . 30

Appendix B. Connector Configurator . . . . . . . . . . . . . . . . . . . . . . . 39Using Connector Configurator in an internationalized environment. . . . . . . . . . . . . . . . . 39Starting Connector Configurator . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Choosing your broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Using a connector-specific property template . . . . . . . . . . . . . . . . . . . . . . . . 42Using Connector Configurator with ICS as the broker . . . . . . . . . . . . . . . . . . . . . 45Setting the configuration file properties (ICS) . . . . . . . . . . . . . . . . . . . . . . . . 47Setting the configuration file properties (WebSphere MQ Integrator Broker) . . . . . . . . . . . . . . 52Using standard and connector-specific properties with Connector Configurator. . . . . . . . . . . . . 55Completing the configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Appendix C. Connector Feature List . . . . . . . . . . . . . . . . . . . . . . . 57Business Object Request Handling Features. . . . . . . . . . . . . . . . . . . . . . . . . 57Event Notification Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57General Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Programming interface information . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Trademarks and service marks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

© Copyright IBM Corp. 2000, 2003 v

vi Adapter for PeopleSoft (Version 7.x) User Guide

About this document

IBM(R) WebSphere(R) InterChange Server and its associated toolset are used withIBM(R) WebSphere(R) Business Integration Adapters to provide business processintegration and connectivity among leading e-business technologies and enterpriseapplications.

This document describes the installation, configuration, and business objectdevelopment for the IBM WebSphere Business Integration Adapter for PeopleSoft7.x.

AudienceThis document is for IBM WebSphere Business Integration Adapter Frameworkconsultants and customers. To use the information in this document, you should beknowledgeable in the following areas:v Connector developmentv Business object developmentv PeopleSoft application architecturev PeopleSoft Tools

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 totwo other documents: the System Installation Guide for Windows or for UNIX andthe Implementation Guide for WebSphere InterChange Server. If you choose toprint this document, you may want to 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 MQ Integrator 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 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).

© Copyright IBM Corp. 2000, 2003 vii

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

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

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

viii Adapter for PeopleSoft (Version 7.x) User Guide

New in this release

New in Release 3.4.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.”

The IBM WebSphere Business Integration Adapter for PeopleSoft 7.x includes theconnector for PeopleSoft 7.x. 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 PeopleSoftv PeopleSoft ODAv A sample business object , included in the \connectors\PeopleSoft7\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.

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.

New in Release 3.3.xVersion 3.3.1 of the IBM CrossWorlds Connector for PeopleSoft 7.x includes thefollowing new features and changes:v Two new field mappings have been added to the Message Agent queues:

keylist and poll_delay.

© Copyright IBM Corp. 2000, 2003 ix

x Adapter for PeopleSoft (Version 7.x) User Guide

Chapter 1. Overview of the connector

This chapter describes the connector component of the IBM WebSphere BusinessIntegration Adapter for PeopleSoft 7.x. The connector enables a supportedintegration broker (InterChange Server or WebSphere MQ Integrator) to exchangebusiness objects with PeopleSoft 7.5 applications.

Connectors consist of two parts: the connector framework and theapplication-specific component. The connector framework, whose code is commonto all connectors, acts as an intermediary between the integration broker and theapplication-specific component. The application-specific component contains codetailor to a particular application. 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 connector framework and theapplication-specific component. It refers to both of these components as theconnector.

For more information about the relationship of the integration broker to theconnector, see the System Administration Guide, or the WebSphere Business IntegrationAdapters Implementation Guide for MQ Integrator.

The connector works with the following databases: Informix, SQLBase, Oracle,Sybase, Microsoft, DB2, DB2ODBC, DB2MDI, DB2400, DB2Unix.

Communication between the connector and PeopleSoft

Business object operationsThe connector inserts data into PeopleSoft by using the PeopleSoft Message AgentAPI and a set of message definitions for each business object.

Event notificationFor event notification, the connector uses PeopleCode to populate an event queuetable when an event of interest to the integration broker occurs in PeopleSoft. Theconnector polls the event queue table at a configurable interval, retrieves theevents by using the PeopleSoft Message Agent API, processes the events, andarchives the events.

Processed events and unsubscribed events are archived by means of PeopleCodeon the event work table. The code removes events from the event table and copiesthem to an archive table. The event and archive tables are installed with databaseupgrades for each database supported by the connector. See “Performing aselective application upgrade” on page 4 for information on the event queue table.

© Copyright IBM Corp. 2000, 2003 1

2 Adapter for PeopleSoft (Version 7.x) User Guide

Chapter 2. Installing and configuring the connector

This chapter describes how to install the IBM WebSphere Business IntegrationAdapter for PeopleSoft 7.x and how to configure the PeopleSoft application towork with the connector. It contains the following sections:v “Prerequisites”v “Installing the connector” on page 4v “Required modifications” on page 4v “Event table structure” on page 7v “Configuring the connector” on page 7v “Starting the connector” on page 9

PrerequisitesThis section describes the software components you must install and the tasks youmust perform before installing and running the connector.

Note: This connector works only with PeopleTools 7.55 and 7.57.

User account setupYou must create a user account in PeopleSoft for the connector. The user accountcan have any valid Peoplesoft username and password. It must have privileges toretrieve, insert, update and delete data from the appropriate application panels andthe cw event panel in the PeopleSoft system. For example, if the connector handlescustomer data, the connector’s user account must have privileges to access andmodify data in all relevant customer panels.

The user account must be configured so that it never times out. Since the connectoruses the Message Agent to insert and extract business objects from the PeopleSoftserver, the Message Agent must be running when the connector accesses thePeopleSoft system. If the connector times out, the Message Agent closes. As aresult, the connector logs an error message every time it accesses the PeopleSoftsystem — at every poll, retrieve, create, and update.

To configure the user account so that it never times out:1. Open the People Tools Security Administrator.2. Open the class which contains the user account.3. Select the Never Time-Out radio button in the Time-Out Minutes group box.

Upgrading from a previous versionIf you are upgrading from a previous version of the product, the configurationproperties in the repository definition file may have changed. See “Configuring theconnector” on page 7.

Deleting the previously installed connectorIf you have an earlier version of the connector installed, you must delete theconnector and as well as its customized components in the PeopleSoftenvironment. This includes all supporting menus, panels, records, event andarchive tables, and the IBM WebSphere business integration adaptor businessprocess.


Installing the connectorThe connector is installed during the software installation. For instructions oninstalling the software, see the IBM WebSphere Business Integration AdaptersImplementation Guide for MQ Integrator, or, for ICS, see the System InstallationGuide for UNIX or for Windows.

Configuring the connector as a windows serviceIf you want to run the connector as a Windows Service, perform the followingsteps after installation:1. From the Windows Start menu select Settings>Control Panel.2. In the Control Panel, double-click the Services icon. The Services window

appears.3. Select PeopleSoft Connector from the Service list.4. Click the Startup... button.5. Set Startup Type to Automatic.6. Set the LogOnAs option to This Account.7. Enter the integration-broker administrator’s logon ID and password. Click OK.

For more information, see the WebSphere Business Integration AdaptersImplementation Guide for MQ Integrator, or, for ICS, the System Installation Guidefor Windows.

Required modificationsThe connector installation includes a set of Data Mover data files containing menudefinitions, panel definitions, record definitions, and PeopleCode required tosupport the connector. These files are used to create the following:v Event queue tables that store event notifications, and an archive table that stores

processed events.v An Application Engine used to move events between event tables.v A derived work record for storing temporary values and PeopleCode.v A set of PeopleSoft message definitions for each business object/verb

combination. Message definitions are stored either in the Connector Integrationactivity in the IBM WebSphere business integration adaptor business processor, when ICS is the integration broker, in the activities and business processesassociated with supported collaborations. For example, message definitions forEmployee object/verb combinations are found in the CWEmployee activity in theCWEMPLOYEE business process.

Performing a selective application upgradeTo copy the required business-integration objects into the PeopleSoft database, youmust perform a selective application upgrade. The upgrade process involvescopying the objects from a source database, the application upgrade database(AUDB), to the target database in the PeopleSoft environment. For detailedinformation on Application Upgrader, see the PeopleSoft Administration Toolsguide.

Before performing the application upgrade you must create and prepare the AUDBby performing the following steps:1. Create a new database to use as the upgrade database.


2. Launch the PeopleTools Data Mover by double clicking the PSDMT.EXE file.TheData Mover window appears.

3. Import the file %ProductDir%\connectors\PeopleSoft\dependencies\DataMover\CWUpgPrj.dat into the upgrade database.

4. In Data Mover, open the script %PeopleSoft%\script\auimport.dms.5. Run the script by selecting File>Run Script, or by clicking the Run Script

button. The message definition data is imported. Ensure that the SuccessfulCompletion message appears.

At this point, it is a good idea to run a comparison report between the AUDB andthe target database. However, if you are certain that there are nobusiness-integration objects in the target database, you can skip this report andperform the application upgrade.

Perform the application upgrade as follows:1. Log on to the AUDB.2. In the Application Designer, open the CWUpgPrj project.3. From the Tools menu, select Copy>Upgrade.4. Sign on to the target database by clicking Signon. The Signon screen is

displayed. Enter the name of the target database, operator ID, and password.5. In the Copy dialog box, select the Export Project check box. Make sure that all

other items in the list box are also selected, then click Copy.If PeopleSoft is the source application, you may skip the next two steps.

6. To complete the installation of the event tables, go to Data Designer andperform a SQL Table Create against XR_EVENT, XR_FUTURE_EVENT,TMP_FUTURE_EVENT, and XR_ARCHIVE.

7. Go to Data Designer and perform a SQL View Create against XR_SRCH.8. In the PeopleSoft Security Administrator, open the Operator class for the

connector and give this class the privileges to use all items in theEVENT_NOTIFICATION menu group.

To test that the application upgrade executed successfully:1. Close all PeopleSoft windows.2. Log out of the application, then log back in.3. Select the Start Menu, and confirm that the Event Notification menu is

displayed.

Importing the application engine

Note: The Application Engine is not required if the connector does not supportPeopleSoft as a target application.

The Application Engine is a batch process that moves events from the futureevents table to the event table. To import the Application Engine follow thesesteps:1. In your Data Mover window, import the file

%ProductDirS%\connectors\PeopleSoft\dependencies\DataMover \CWAE.dat intothe production database.

2. In Data Mover, open the script CWAEIn.dms.3. Run the script by selecting File>Run Script or by clicking the Run Script button.

Chapter 2. Installing and configuring the connector 5

4. When the script runs successfully, open the Process Scheduler and scheduleXR_MOVE to run at midnight every night. For information on using theProcess Scheduler, see the PeopleSoft Administration Tools manual.

Installing message definitionsNext you must import message definitions to support WebSphere BusinessIntegration Adapter Framework business objects. The message definitions enablethe connector to communicate with the PeopleSoft system via the Message AgentAPI. The import script file, CWBPIn.dms, is located in%ProductDirs%\connectors\PeopleSoft\dependencies\DataMover. This file containsthe following scripts:

Table 1. Message definition scripts

Script Message definitions

CWBP.dat Event notification message definitionsCWEMPL.dat Employee message definitionsCWDEPT.dat Department message definitionsCWEMPL_757.dat Employee message definitions for use with

PeopleTools 7.57

To import the message definitions into the PeopleSoft system, follow these steps:1. In the Data Mover window, open the .dms scripts for the business objects you

need to support.2. Run the scripts by selecting File>Run Script or by clicking the Run Script

button. Ensure that the Successful Completion message is displayed. Themessage definition data is imported.

Note: If the message definition import fails, use delbp.sql to delete all WebSphereBusiness Integration Adapter Framework message definitions, then repeatthe import steps. The delbp.sql file is located in%ProductDirs%\connectors\PeopleSoft\dependencies\DataMover.

Embedding PeopleCode into panelsTo enable triggering for Department and Employee business objects, you mustembed fields in certain panels. Table 2 details which embedded fields are requiredfor each business object.

Table 2. Business object triggering fields

Business object Use for Field name Panel Level

Department Eventnotification

DEPT_TRIGGER DEPT_TBLGBL_SBP Level 0

Employee Eventnotification

EMPL_PERS_TRIGGER PERSONAL_DATA2 Level 0

Employee Eventnotification

EMPL_JOB_TRIGGER JOB_DATA1 Level 0

Employee Request EMPL_OTHERPHONE PERSONAL_DATA2 Level 1 (phonescrollbar)

To embed fields in the appropriate panels:1. In Panel Designer, open the panel for the appropriate business object listed in

Table 2.2. On the menu bar, select Add >Edit Box.


3. Click on the panel to drop an edit box on the panel.4. Right click on the field and select Record from the popup menu.5. In the Edit Box Record dialog box, enter XR_EVENT_WRK for Record Name,

and enter the related Field Name from the table above.6. Click OK and right click on the Edit Box again.7. Select Use from the popup menu.8. Select the Invisible check box, and click OK.

Event table structureWhen an event occurs in the PeopleSoft application, the event is placed in an eventqueue table named XR_EVENT. The connector polls this table at a configurableinterval and processes the events sequentially.

The event queue table and archive queue table have the following structure.However, only the archive table has the PROCESS_KEY field.

Table 3. Event queue and archive queue table structure

Name Type Constraint Description

PROCESS_KEY Datetime Not NULL Unique key for the event result set.The key is the date and time stampwhen the event was processed. Usedby the archive table only.

CWPRIORITY char 3 Event priority.EVENT_KEY Datetime Not NULL Unique key for the event. The key is

the date and time stamp when theevent was processed.

OBJ_SETID char 5 TableSetID for the PeopleSoft object.OBJECT_ID char 18 Unique ID for the PeopleSoft object.OBJECT char 18 Name of the PeopleSoft object.DOVERB char 15 Name of the action taken on the

PeopleSoft object.KEYLIST char 51 List of non-primary object keys. Keys

are listed in name=value format anddelimited by a colon (:).

PRCS_FLG char 3 Process flag to indicate the state ofthe event. The values can be:

v N = Not processed

v P = Successfully processed

v NS = Event not subscribed to

v E = Error

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

A connector obtains its configuration values at startup. During a run-time session,you might want to change the values of one or more connector properties.Changes to some connector configuration properties, such as AgentTraceLevel, takeeffect immediately. Changes to other connector properties require componentrestart or system restart after a change. To determine whether a property is


dynamic (taking effect immediately) or static (requiring either connectorcomponent restart or system restart), refer to your integration broker’sadministration utility. For instance, if you are using ICS, see the Update Methodcolumn in the Connector Properties window of the System Manager.

Standard donnector propertiesStandard configuration properties provide information that all connectors use. SeeAppendix A, “Standard Configuration Properties for Connectors”, on page 17 fordocumentation of these properties.

Important: Because this connector supports all integration brokers, configurationproperties for all 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 at run time. Connector-specific properties also provide a way ofchanging static information or logic within the connector without having to recodeand rebuild the connector.

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

Table 4. Connector-specific configuration properties

Name Possible values Default value

ApplicationPassword PSApplicationUserName PSAppServerMachineNameOrIPConnectErrors Unable to connect to destination:ORACLE not

available:TNS:listener failed:Could notconnect to application server:Database accessis not allowed:Failed to establish MsgAPIservice context for operator

disableCrossReferencing True/False Enables or disables cross referencing. Thedefault is false, cross referencing isenabled.

PollQuantitiy 1 to 500 (maximum) 25PortNumber 7000PeopleToolsVersion 7.57Priority 0-n 0UseDefaults false

ApplicationPasswordThe Password for the connector’s user account.

ApplicationUserNameThe Name of the connector’s user account. ApplicationUserName is theOperatorID in PeopleSoft.

AppServerMachineNameOrIPThe Machine name or IP address of the machine name.


ConnectErrorsThe List of strings that cause the connector to terminate when the connection tothe PeopleSoft application or database is lost. These strings are written to theconnector log when the connection is lost. Additional strings can be specified;separate strings with colon (:) delimiters.

disableCrossReferencingTurns cross referencing on and off. The default value is False, cross-referencing isenabled.

PollQuantitiyThe number of events in the database table that the connector retrieves per pollinginterval.

PortNumberThe Port number for Message Agent requests.

PeopleToolsVersionThe version of PeopleTools, for example, 7.52.

PriorityThe priority level from 0-n, with 0 being the highest level. At each poll interval,the connector picks up events starting with the highest priority events andcontinuing with lower priority events until the number of events specified in thePollQuantity configuration property is met, or until there are no events in theevent table. The connector currently does not decrement priority.

UseDefaultsOn a Create operation, if UseDefaults is set to true or not set, the connector checkswhether a valid value or a default value is provided for each isRequired businessobject attribute. If a value is provided, the Create succeeds; otherwise, it fails. If theparameter is set to false, the connector checks only for valid values; the Createoperation fails if valid values are not provided.

Starting the connectorFor information on starting a connector, stopping a connector, and the connector’stemporary startup log file, see the WebSphere Business Integrator AdaptersImplementation Guide for MQ Integrator, or, for ICS, see the IBM WebSphereInterChange Server System Administration Guide.

Loss of connection to the applicationIf the connector determines that the connection with the application has been lost,the connector terminates and returns a status to the integration broker. TheConnectErrors property specifies which error strings cause the connector toterminate. For more information see “Connector-specific properties” on page 8.


Chapter 3. Developing business objects for the connector

This chapter describes how the WebSphere Business Integration Adapter forPeopleSoft 7.x processes business objects, and provides suggestions for developingand modifying business objects for the connector. It contains the followign sections:

“Business object application-specific text”

Business object application-specific textThe application-specific text in a business object is used to identify where data islocated in the application database. This section describes the application-specifictext format that the connector expects.

Object application-specific text formatThe connector uses application-specific text at the business-object level todetermine which PeopleSoft activity the connector uses for that business object. Tospecify this in application-specific text, use the name-value pair Activity= name.The naming convention for activities is CWbusiness object name. For example, forthe Employee business object, the PeopleSoft activity is named CWEmployee. Theapplication-specific text for this is:[BusinessObjectDefinition]Name = Psft_EmployeeVersion = 1.0.0AppSpecificInfo = Activity=CWEmployee...

The name parameter in the application-specific text must match the name of theactivity in PeopleSoft. This name-value pair is needed only for a top-level businessobject. The connector also uses application-specific text at the business-object levelto determine whether a business object will be processed by the connector. If theAppSpecificInfo field for the business object contains the string NoOp, the businessobject is not processed.

When using the NoOp string, the Activity name-value pair also needs to bespecified. In this case, the Activity name-value pair precedes the NoOp string and isdelimited by a colon. For example:[BusinessObjectDefinition]Name = Psft_DepartmentVersion = 1.0.0AppSpecificInfo = Activity=CWDepartment:NoOp...

Attribute application-specific text formatThe connector uses attribute application-specific text to retrieve keys for childobjects in hierarchical business objects.

As part of the connector installation, message definitions that support businessobject/verb combinations are imported into the PeopleSoft system. These messagedefinitions can contain one or more special fields that correspond to attributes in atop-level business object. Each special field is associated with PeopleCode thatgathers the keys to child objects.


When the connector receives an event notification and queries for the complete setof data for a business object, the PeopleCode executes to dynamically assemble thechild keys in the special fields. The connector then retrieves the value of eachspecial field, which is a list of child keys, into the attribute corresponding to thespecial field. The connector can parse the list to identify the specific key for aparticular attribute in a child object. The content of the special fields is not storedin the PeopleSoft database.

The following illustration shows example parent and child business objects and theformat of the application-specific text. The Psft_Employee parent business objectincludes the attribute OtherPhoneKeys, which corresponds to the special fielddefined in the message definition for this business object. The child object includesthe name of the special attribute in application-specific text for the key attribute.The connector identifies the key for the child object attribute from within theapplication-specific text.

When modifying business objects for the connector, key attributes in child objectsmust have application-specific text that points to a special attribute in the parentobject.

Verb application-specific text formatThe connector does not currently use the application-specific property for verbs.Leave this field blank when creating business object definitions.

Modifying business objects for the connector

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.

When modifying or extending a business object for the connector, if PeopleCode isused to assemble keys, you must modify the PeopleCode in the XR_EVENT_WRK

Name = OtherPhoneKeys AppSpecificInfo = ...

Psft_Employee

[Attribute]

Name = EmployeeId AppSpecificInfo = ...

[Attribute]

Object Definition

Psft_Employment Business

Psft_Employment

Name = EmployeeRecNum

AppSpecificInfo = ...

[Attribute]

Object Definition Psft_OtherPhones Business

Psft_OtherPhones

Name = PhoneType

AppSpecificInfo = OtherPhoneKeys...

[Attribute]

Object Definition

Name = EmploymentKeys AppSpecificInfo = ...

[Attribute]

Parent object

Psft_Job Business

Psft_Job

Name = EmployeeRecNum [Attribute]

Object Definition

IsKey = true IsKey = true AppSpecificInfo = EmploymentKeysIsKey = true

.... .... ....

Psft_Employee Business


table and the message definitions that were installed with the product. Forexample, to add a child business object to a hierarchical business object, you mustperform the following general steps:1. Modify the top-level business object to add two new attributes: the container

attribute for the child business object and an attribute to hold the child keys.2. Add the child business object. The key in the child business object must have

application-specific text that points to the attribute at the top-level object. Forexample, in the Psft_Employee business object, the child objectPsft_OtherPhones has the AppSpecificInfo field for the PhoneType attribute setto OtherPhoneKeys to point back to the top-level business object attributeOtherPhoneKeys.

3. Modify the PeopleCode in the XR_EVENT_WRK table to add a section thatconcatenates all the keys for the child objects. For the Psft_Employee businessobject, the PeopleCode for Psft_OtherPhones creates the stringCELL:FAX:HOME, where the keys are separated by colons.

4. Add a message definition for the child business object and modify the messagedefinition for the top-level business object. For example, the Psft_Employeebusiness object has the following message definitions for the child object:v Retrieve OtherPhonesv Create OtherPhonesv Update OtherPhones

5. Add OtherPhonesKeys to the Retrieve Employee message definition for thetop-level business object.

Rules for modifying business objectsFollow these rules when modifying business objects for the connector:

Objects spanning multiple panel groupsIf a top-level business object or child business object spans two different panelgroups, split the business object or child object into two business objects.

Effective dated and effective sequenced rows1. PeopleSoft application objects are designed to model the way the panel

processes data. A panel with effective dated information identifies the databaserecord that the effective dated information is stored in. This table/record musthave the EFFDT as one of its keys. For an example of this, compare thePsft_EffDtEmployee object to the record PS_PERS_DATA_EFFDT. This is themain record referenced on the effective dated subpanel within the employeepanel groups.

2. EffectiveSequence is part of the Job record key, which enables you to trackevents by sequence on the same effective date. Effective Sequence is a manualinput field used to track the multiple actions that occur on the same effectivedate. It does not have any automated database sequencing. For example, if youentered a “Posn Chg” action for an employee on 4/25/00, and no other actionhad been performed on that date, leave the Effective Sequence field at 0. If youlater entered a “Pay Rt Chg” action for the same employee on 4/25/00, set theEffective Sequence field to 1.

3. For all effective dated and effective sequenced rows, you must repeat effectivedate field or effective sequence twice in the message definition. This isnecessary only for Create operations in the message definition--for example,CreateJob.

4. For effective dated rows, list all fields that show up on the panel as attributesin the business object. When inserting new rows into the database, the

Chapter 3. Developing business objects for the connector 13

connector follows the same behavior as if the user is online inserting a row bypressing the F7 key. In both cases, all the attributes in the scroll are copied intothe new scroll. If you do not specify all the attributes in the business object,you run the risk of unintentionally copying data from a previous row into thenew row.

5. For effective dated rows, you need to specify the attribute application-specifictext to be EFFDT in the Business Object.

6. For effective dated rows, you need an extra message definition. The name ofthe message definition has to be the business object name + EFFDT. Theattributes are the keys (input) and EFFDT (output). For example:Message Definition = RetrieveJobEFFDTAttributes = EmployeeId (input)

EmployeeRecNum (input)JobEffectiveOnDate (output)

Message definitions1. Because the Message Agent processes data in the same order as the online

panels, the order of fields in the message definition is important only for fieldsrequiring validation from previously entered data. Otherwise, the order of thefields listed on the Message Definition is not important.

2. In the message definitions, the message Output All Occurrences works only forLevel 1 fields. See Create Message Definitions in the Peoplebooks DevelopmentTools for more information. If you need to retrieve a Level 2 or Level 3 row,you must create a new panel to move the Level 2 or Level 3 fields to Level 1.

Business object attributesAttributes must exist in both the business object and the message definition.Attribute names must be spelled consistently. The order of attributes in thebusiness object is not important.

Child business object keysChild business objects do not need to repeat the keys that already exist in theparent business objects. When the connector processes a hierarchical businessobject, the connector first obtains the keys that are stored in the parent businessobjects, then processes the child business objects. However, the keys must berepeated in the Message Agent definition.

Attribute namesDo not use EFFDT or EFFSEQ as the attribute name.

AppSpecificInfoYou can have only two identifiers for AppSpecificInfo. They must be delimited bya colon (:). For example:AppSpecificInfo = EFFDT:Additional PayKeys

Event notificationsTo process event notifications, the connector takes the value of OBJECT_ID in theevent table and stores it in a field called [business object name]Id. This fieldname might differ from the actual name of the key in PeopleSoft. For example, inPeopleSoft 7.5, the key for the Item table is InvItemId, but the connector requiresthat the name of the key in the Item business object be ItemId.

Attribute names in business objects and message definitionsThe connector requires that there be an exact match in attribute names between thebusiness object and the message definitions for each verb for that object. For


example, there must be an exact match between the attribute names in Psft_Itemand the attribute names in the following message definitions:v Create Itemv Retrieve Itemv Update Item

As you update message definitions, make sure that the spelling and capitalizationof the attribute names matches the attributes in the business object. These messagedefinitions can be found in the IBM WebSphere business integration businessprocess and the Connector Integration activity.

Transaction processing for hierarchical business objectsIf a failure occurs when the connector is processing a hierarchical business objectwith a Create or Update verb, one or more child business objects may not beprocessed.

The connector does not define a transaction as an operation on a completehierarchical business object. Instead, the connector defines a separate transactionfor each operation on individual parent or child business objects in a hierarchicalbusiness object. When the connector receives a business object with a Create verb,it first processes the parent business object and then processes each individualchild business object. Under normal conditions, it begins a transaction for eachbusiness object in the hierarchy, creates the entity in the application, and commitsthe transaction.

If the connector succeeds in creating one or more child entities, and a failureoccurs during the creation of another child entity, the connector rolls back theCreate operation for this particular business object by backing out the entity. Theconnector continues processing child business objects until all the remainingentities have been created. Because there was a failure, the connector returnsBON_FAIL to the integration broker for the overall operation on the business object.In addition, the Create or Update operation in the application may be incomplete.This scenario is similar for an Update transaction.

When the connector returns BON_FAIL, the complete hierarchical business object isplaced in the unprocessed events queue. A system administrator needs to check thedestination application and resolve the problem that caused the failure. Then thesystem administrator needs to resubmit the business object to the connector.Because the connector checks for the existence of application entities beforecreating them, the connector does not create duplicate data on a business objectresubmission for those child business objects that have already been created.

Chapter 3. Developing business objects for the connector 15

Appendix A. Standard Configuration Properties forConnectors

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 Name


Agent URLListener PortCertificate LocationLogFileNameTraceFileNamejms.BrokerName

Configuring Standard Connector Properties for WebSphereInterChange Server

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

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

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

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

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

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

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

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

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

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


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

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

Property Name PossibleValues

DefaultValue

UpdateMethod

Notes

AdminInQueue valid JMS queue name CONNECTORNAME /ADMININQUEUE

AdminOutQueue valid JMS queue name CONNECTORNAME/ADMINOUTQUEUE

AgentConnections 1-4 1 server restart multi-threadedconnector only

AgentTraceLevel 0-5 0 dynamic

ApplicationName application name the value that is specified for theconnector name

componentrestart

value required

BrokerType ICS, WMQI ICS is requiredif your brokeris ICS

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

ascii7 componentrestart

ConcurrentEventTriggeredFlows 1 to 32,767 no value componentrestart

ContainerManagedEvents JMS or no value JMS guaranteedevent delivery

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

restartJMS transportonly

DeliveryTransport MQ, IDL, or JMS IDL componentrestart

FaultQueue CONNECTORNAME/FAULTQUEUE componentrestart

DuplicateEventElimination True/False False componentrestart

JMS transportonly,ContainerManagedEventsmust be<NONE>

JvmMaxHeapSize heap size in megabytes 128m componentrestart

JvmMaxNativeHeapSize size of stack in kilobytes 128k componentrestart

JvmMinHeapSize heap size in megabytes 1m componentrestart

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

crossworlds.queue.manager server restart JMS transportonly

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

CxCommon.Messaging.jms.IBMMQSeriesFactory

server restart JMS transportonly

jms.NumConcurrentRequests positive integer 10 componentrestart

JMS transportonly

Appendix A. Standard Configuration Properties for Connectors 19


DefaultValue

UpdateMethod

Notes

jms.Password Any valid password server restart JMS transportonly

jms.UserName Any valid name server restart JMS transportonly

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

en_US componentrestart

LogAtInterchangeEnd true or false false componentrestart

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

MessageFileName path/filename Connectorname.txt orInterchangeSystem.txt

componentrestart

MonitorQueue any valid queue name CONNECTORNAME/MONITORQUEUE componentrestart

JMS transportonly,DuplicateEventEliminationmust be True

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

minutes10 dynamic

PollEndTime HH:MM HH:MM componentrestart

PollFrequency a positive integer inmilliseconds

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

10000 dynamic

PollQuantity 1-500 1 componentrestart

Number ofitems to pollfromapplication

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

HH:MM componentrestart

RepositoryDirectory location whererepository is located

<REMOTE> componentrestart

<REMOTE>for ICS broker

RequestQueue valid JMS queue name CONNECTORNAME/REQUESTQUEUE componentrestart

ResponseQueue valid JMS queue name CONNECTORNAME/RESPONSEQUEUE componentrestart

RestartRetryCount 0-99 3 dynamicRestartRetryInterval a sensible positive value in

minutes1 dynamic

SourceQueue valid MQSeries queuename

CONNECTORNAME/SOURCEQUEUE componentrestart

Valid only ifdeliverytransport isJMS andContainerManagedEventsisspecified.

SynchronousRequestQueue CONNECTORNAME/SYNCHRONOUSREQUESTQUEUE

componentrestart

“SynchronousResponseQueue” onpage 36

CONNECTORNAME/SYNCHRONOUSRESPONSEQUEUE

componentrestart



DefaultValue

UpdateMethod

Notes

SynchronousRequestTimeout 0 componentrestart

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

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

The default value is CONNECTORNAME/ADMININQUEUE.

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

The default value is CONNECTORNAME/ADMINOUTQUEUE.

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

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

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

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

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


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

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

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

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

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

The default value is ascii.

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

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

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


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

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

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

Notes:

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

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

The default value is JMS.

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

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

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

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

The default is true.

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

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

The default value is DELIVERYQUEUE.


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

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

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

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

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

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

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

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

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

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

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

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

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

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


export LDR_CNTRL=MAXDATA=0x30000000

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

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

Notes:

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

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

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

This property can also be set to false.

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

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

The default value is CONNECTORNAME/FAULTQUEUE.

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

The default value is 128m.

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

The default value is 128k.

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

The default value is 1m.


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

The default is CxCommon.Messaging.jms.IBMMQSeriesFactory.

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

The default is crossworlds.queue.manager.

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

The default value is 10.

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

There is no default.

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


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

A locale name has the following format:ll_TT.codeset

where:

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

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

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

The default is en_US.


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

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

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

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

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

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

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

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

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

The default value is false.

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



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

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

The default value is SOURCEQUEUE.

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

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

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



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

WireFormatMessage format on the transport.

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

Configuring Standard Connector Properties for WebSphere MQIntegrator

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

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

You configure connector properties from Connector Configurator.

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

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

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

Name Possible Values Default Value

AdminInQueue valid JMS queue name CONNECTORNAME/ADMININQUEUEAdminOutQueue valid WebSphere MQ

queue nameCONNECTORNAME/ADMINOUTQUEUE

AgentTraceLevel 0-5 0ApplicationName application name AppNameConnectorBrokerType WMQI WMQI



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

ASCII

ContainerManagedEvents JMS or no value JMSDeliveryQueue valid WebSphere MQ

queue nameCONNECTORNAME/DELIVERYQUEUE

DeliveryTransport JMS JMSDuplicateEventElimination true, falseFaultQueue valid WebSphere MQ

queue nameCONNECTORNAME/FAULTQUEUE

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

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

crossworlds.queue.manager

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

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

en_US

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

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

C:\crossworlds\Repository

RequestQueue valid WebSphere MQqueue name

CONNECTORNAME/REQUESTQUEUE

ResponseQueue RESPONSEQUEUERestartRetryCount 0-99 3RestartRetryInterval an appropriate integer

indicating the number ofminutes between restartattempts

1

SourceQueue valid WebSphere MQqueue name

CONNECTORNAME/SOURCEQUEUE

SynchronousRequestQueue valid WebSphere MQqueue name

SynchronousResponseQueue valid WebSphere MQqueue name



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

0

WireFormat CwXML CwXML

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

The default value is CONNECTORNAME/ADMININQUEUE.

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

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

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

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

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

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

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


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

The default value is ascii.

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

Notes:

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

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

The default value is JMS.

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

The default value is CONNECTORNAME/DELIVERYQUEUE.

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

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

This property can also be set to false.

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

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

The default value is CONNECTORNAME/FAULTQUEUE.


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

The default is CxCommon.Messaging.jms.IBMMQSeriesFactory.

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

The default is crossworlds.queue.manager.

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


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


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


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

A locale name has the following format:ll_TT.codeset

where:

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

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

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

The default is en_US.

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


Attention:

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

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

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

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


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

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

lowercase.

The default is 10000.

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

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


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

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


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

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

The default value is CONNECTORNAME/REQUESTQUEUE.

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

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

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

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

The default is CONNECTORNAME/SOURCEQUEUE.

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

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

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



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


Appendix B. Connector Configurator

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

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

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

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

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

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

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

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

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


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

<ValidType>String</ValidType><ValidValues>

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

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

</Property>

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

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

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

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

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

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

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

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

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

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


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

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

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

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

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

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

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

in this chapter for your specific broker.

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

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

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

Appendix B. Connector Configurator 41

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

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 48. 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 41.

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

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

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

Business Object Request Handling FeaturesTable 5 details the business object request handling features supported by theconnector.

Table 5. Business Object Request Handling Features

Category Feature Support Notes

Create Create verb FullDelete Delete verb Partial The Delete verb is supported.

Logical delete FullExist Exist verb NoMisc Attribute names Full

Business object names FullRetrieve Ignore missing child object FullRetrieveByContent Ignore missing child object Full

Multiple results NoRetrieveByContent verb No

Update After-image support FullDelta support NoKeepRelations No

Verbs Retrieve verb FullSubverb support NoVerb stability Full

Event Notification FeaturesTable 6 details the event notification features supported by the connector.

Table 6. Event Notification Features


Connector Properties Event distribution NoPollQuantity Full

Event Table Event status values PartialObject key FullObject name FullPriority Full

Misc. Archiving FullCDK methodgotApplEvent

Partial Called from doVerbFor as well.

Delta event notification NoEvent sequence Partial Exists in the event table but is not used.Future event processing FullIn-Progress event recovery Partial Please see the connector documentation for

more information.Physical delete event No


Table 6. Event Notification Features (continued)


RetrieveAll FullSmart filtering NoVerb stability Full

General FeaturesTable 7 details the general features supported by the connector.

Table 7. General Features


Business ObjectAttributes

Foreign key No

Foreign Key attributeproperty

No

Key Full Key attributes are used for object retrieval.Max Length NoMeta-data-driven design FullRequired Full The connector fails a Create operation if a

business object does not have a valid value ora default value for a Required attribute.

Connection Lost Connection lost on poll FullConnection lost on requestprocessing

Full

Connection lost while idle FullConnector Properties ApplicationPassword Full

ApplicationUserName FullUseDefaults Full

Message Tracing General messaging Partial Tracing approximates the specified levels.generateMsg() Partial Generate message is used for some tracing.Trace level 0 PartialTrace level 1 PartialTrace level 2 PartialTrace level 3 PartialTrace level 4 PartialTrace level 5 Partial

Misc. CDK method LogMsg Partial Some strings are hard coded.Java Package Names N/ALogging messages FullNT service compliance Full


Table 7. General Features (continued)


Transaction support No For the connector, a transaction is not definedas an operation on a complete hierarchicalbusiness object. Instead, the connector definesa separate transaction for each operation onindividual parent or child business objects ina hierarchical business object. When theconnector receives a business object with aCreate verb, it first processes the parentbusiness object and then processes eachindividual child business object. Undernormal conditions, the connector begins atransaction for each business object in thehierarchy, creates the entity in the application,and commits the transaction. If the connectorsucceeds in creating one or more childentities, and a failure occurs during thecreation of another child entity, the connectorrolls back the Create operation for thisparticular business object by backing out theentity. The connector continues processingchild business objects until all the remainingentities have been created. Because there wasa failure, the connector returns FAIL to theintegration broker for the overall operation onthe business object. In addition, the Create orUpdate operation in the application may beincomplete. This scenario is similar for anUpdate transaction.

Special Value CxBlank processing FullCxIgnore processing Full

Appendix C. Connector Feature List 59

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 AdaptersV4.2, IBMWebSphere Business Integration Collaborations V4.2

Notices 63

��

Printed in U.S.A.

adapter for peoplesoft (version 7.x) user guide · pdf fileviii adapter for peoplesoft...

Documents