Configuring the connector

Note:
Because the TPI connector and TPI server run in the same address space, it is inadvisable to run your TPI connector with the Parallel Process Degree Resource set to a value greater than 1. For more information on Parallel Process Degree see the System Administration Guide.

Before starting the connector, you must perform the following configuration tasks:

Creating the Trading Partner configuration file

The Trading Partner configuration file lists the MIME types used by each trading partner for XML, EDI, and binary formats. Each time the connector processes a document or a business object, it gets the MIME type from the trading partner configuration file. The MIME type is passed to the DataHandler class in order to call the correct data handler for a given document or business object.

The Trading Partner configuration file is a tab-delimited text file. Each line in the file contains a TPI trading partner ID followed by the MIME types used by that trading partner for XML, EDI and binary formats. The trading partner configuration file format is as follows:

Trading Partner ID <tab> XML MIME type <tab> EDI MIME type <tab> binary MIME type

To ensure proper formatting, create the file as a Microsoft Excel spreadsheet. Then Save the file as Text (Tab delimited). Figure 2 illustrates how to create the file in Excel.

Figure 2. Create the Trading Partner configuration file in Excel

Creating the Trading Partner Configuration File in Excel

The file can be saved to any directory on the machine where TPI is installed. The TradingPartnerConfigurationFile connector property holds the location of the file. For more information see "Connector-specific properties".

You can update the Trading Partner configuration file to add new partners or modify document information while the connector is running. It is not necessary to restart the connector in order to load the updates; the connector retrieves any updates to the configuration file during processing.

Configuring the connector to start the TPI Server

The TPI connector uses the JVM supplied with the TPI Server to run the TPI Server. Using this JVM, the TPI connector starts as a java process, and from within this process, starts the TPI Server. This behavior must be configured after connector installation by editing the connector startup file, start_TPI.bat on Windows NT, and start_TPI.sh on Solaris. Do the following steps to configure the connector to start up and shut down the TPI Server:

  1. Open the start_TPI file located in the \connectors\TPI directory.
  2. Change the value of the CYCLONEHOMEDIR attribute to the TPI home directory path.
  3. Save and close the file.

The JVM Supplied with the TPI Server must also be configured so that the TPI Adapter can successfully instantiate the TPI Server. To configure the TPI supplied JVM:

On Windows:

  1. Locate the \dependencies\win folder in the TPI Adapter's directory: %CROSSWORLDS%\connectors\TPI.
  2. Also locate the \cijre folder in the TPI home directory
  3. Copy the contents of the %CROSSWORLDS%\connectors\TPI\dependencies\win folder into the %CYCLONEHOMEDIR%\cijre folder.
  4. The following files should now exist in %CYCLONEHOMEDIR%\cijre

On Solaris:

  1. Locate the /dependencies/sol folder in the TPI Adapter's directory: ${CROSSWORLDS}/connectors/TPI.
  2. Also locate the /cijre folder in the TPI Server's home directory. This will be identified as ${CYCLONEHOMEDIR}.
  3. Copy the contents of the ${CROSSWORLDS}/connectors/TPI/dependencies/sol folder into the ${CYCLONEHOMEDIR}/cijre folder.
  4. The following files should now exist in ${CYCLONEHOMEDIR}/cijre

In addition to editing the startup file, you must set the following connector properties for the connector to successfully start the TPI Server:

See "Connector-specific properties" for more information.

Running the connector and TPI Server as a Windows service

You can run the TPI connector and server as a Windows service. After installing the connector as a service, you must also modify the start_TPI.bat file as follows:

>"%CONNDIR%"\connectors\TPI\TPITrace.txt

Setting connector configuration properties

You must set the connector's standard and connector-specific configuration properties before you can run it. Use one of the following tools to set a connector's configuration properties:

Standard connector properties

Standard configuration properties provide information that all connectors use. See Appendix A, Standard configuration properties for connectors for detailed information about these properties.

Important

Because the connector supports both the ICS and WebSphere MQ Integrator Broker integration brokers, configuration properties for both brokers are relevant to the connector.

In addition, refer to Table 1 for configuration information specific to the IBM WebSphere Business Integration Adapter for TPI. The information in this table supplements the information in the appendix

Table 1. Property information specific to this connector

Property Note
AgentConnections This connector is single threaded. Therefore, it cannot use the AgentConnections property.
CharacterEncoding Because this connector is Java-based, it does not use the CharacterEncoding property.
Locale Because this connector has been internationalized, you can change the value of the Locale property. See release notes for the connector to determine currently supported locales.
Note:
If you are using WebSphere MQ Integrator BrokerWebSphere MQ Integrator Broker as your broker, you must use the same locale for the adapter, the broker, and any applications.

Connector-specific properties

Connector-specific configuration properties provide information needed by the connector at runtime. Connector-specific properties also provide a way of changing the configuration or logic within the connector without having to recode and rebuild it

Table 2 lists the connector-specific properties for the connector. See the sections that follow for explanations of the properties.

Table 2. Connector-specific configuration properties

Name Possible values Default value
ArchiveProcessedDocDir <valid directory path>
ArchiveProcessedDocInfo true or false true
BackupRequired true or false true
CycloneServerArgs Any valid TPI Server arguments that do not conflict with other arguments used by the connector. -appagent; -nogui; -console;
DataEncoding Any valid encoding name supported by the JVM. Defaults to the encoding type set by the operating system if no value is specified for this property
DataHandlerDefaultMO
MO_DataHandler_
Default
DefaultBinaryMimeType <valid MIME type>
DefaultEDIMimeType <valid MIME type>
DefaultVerb Any verb supported by the connector.
DefaultXMLMimeType <valid DataHandler class name>
DeliverOnArrival true or false false
DeliverOnArrivalThreads Any number between one and ten. 1
DocumentOutDir <valid directory path>
EventRecovery FailOnStartup, Reprocess, LogError, or Ignore FailOnStartup
MetaEventDir <valid directory path>
PollQuantity
25
TradingPartnerConfigurationFile <fully qualified filename>
WaitForController
500 milliseconds
WaitForMDN true or false true
ArchiveProcessedDocDir

The directory where processed document meta-events are archived. This property is required if the ArchiveProcessedDocInfo property is set to true.

ArchiveProcessedDocInfo

Determines whether the connector retains the meta-event once a document has been successfully processed and sent to the integration broker. If this property is set to false, the meta-events are deleted after processing. The default value is true.

BackupRequired

Determines whether the TPI Server backs up each document after sending it. If set to true, TPI backs up each document after sending. The default value is true.

ControllerWaitCount

Specifies the maximum number of times the connector checks the controller to see if it is active. This property is used in conjunction with the WaitForController property. Each time the connector checks the controller for activity, it waits for the amount of time specified by WaitForController. If the controller does not respond after the maximum number of attempts, event processing fails. The default value is 1.

CycloneServerArgs

A semicolon delimited list of arguments to be passed to the TPI Server at startup. This property is required. The default value is -appagent; -nogui; -console;.

DataEncoding

Specifies the type of data encoding used by the connector. Valid values include any encoding type supported by the JVM. You must set this property whenever non-ASCII character encoding is to be used. If the DataEncoding property is not set, the connector uses the encoding type specified at the operating system level.

DataHandlerDefaultMO

The default name of the meta-object for the connector to use to determine configuration of the data handler for each supported format. This property is required. The default value is MO_DataHandler_Default.

DefaultBinaryMimeType

MIME type for the data handler to use for Binary documents in case the trading partner is not configured in the trading partner configuration file. This property is required if binary MIME type is used in TPI. No default value is set for this property.

DefaultEDIMimeType

MIME type for the data handler to use for EDI documents in case the trading partner is not configured in the trading partner configuration file. This property is required if EDI MIME type is used in TPI. No default value is set for this property.

DefaultVerb

Specifies the verb to be set within an incoming business object, if it has not been set by the data handler during polling.

DefaultXMLMimeType

MIME type for the data handler to use for XML documents in case the trading partner is not configured in the trading partner configuration file. This property is required if XML MIME type is used in TPI. No default value is set for this property.

DeliverOnArrival

Specifies the method of event processing to be used. If DeliverOnArrival is set to false, events are processed one at a time; the PollForEvent thread retrieves an event from memory, processes it, and then retrieves the next event. If DeliverOnArrival is set to true, multiple events can be processed simultaneously. The number of events that can be processed in parallel is determined by the DeliverOnArrivalThreads property. The default value of DeliverOnArrival is false.

DeliverOnArrivalThreads

Specifies the number of threads allocated to simultaneous event processing. If the DeliverOnArrival property is set to true, set the DeliverOnArrivalThreads property to the number of threads you want to allocate to incoming events. The minimum value for parallel processing is 2; the maximum value is 10. By default, DeliverOnArrivalThreads is set to 1, and parallel processing is not enabled.

DocumentOutDir

The directory location where outbound documents are written temporarily before TPI processes them. In the event of a system failure, the documents can be recovered from this directory. This property is required.

EventRecovery

Determines behavior for event recovery. When restarted, a connector checks the Out Directory for files with the extension .inprogress. If this property is set to FailOnStartup, the connector fails to startup. If set to Reprocess, the connector resubmits these events to the server. If set to LogError, the connector logs an error, but does not shut down. If the set to Ignore, the connector ignores such events. The default value is FailOnStartup.

MetaEventDir

The directory used to persist the TPI event information for recovery purposes. This property is required.

PollQuantity

Specifies the number of events the connector retrieves each time it polls the event list. The default value is 25.

TradingPartnerConfigurationFile

Fully qualified name of the trading partner configuration file. This file contains the MIME types used for documents from each trading partner for Binary, XML, and EDI messages. The MIME type is used to call the correct data handler for each document. This property is required. If the property is not specified the connector will fail to start up.

WaitForController

Specifies the amount of time, in milliseconds, that the connector waits for the controller to become active. This property is used in conjunction with the ControllerWaitCount property. The default value is 500 milliseconds.

WaitForMDN

Determines whether the connector waits for an MDN from the trading partner, or returns from the request thread after passing the document to the TPI Server. The MDN indicates that at the protocol level the send was successfully initiated. The WaitForMDN attribute in the child meta-object can be set to override this property on a per business object basis. The default value is true.

Copyright IBM Corp. 1997, 2003