Connector standard properties

This appendix describes the standard configuration properties for the connector component of the adapters in WebSphere Business Integration Server Express.

Not every connector makes use of all these standard properties. When you select an integration broker from Connector Configurator Express, you will see a list of the standard properties that you need to configure for your adapter.

For information about properties specific to the connector, see the relevant adapter user guide.

Configuring standard connector properties

Adapter connectors have two types of configuration properties:

This section describes the standard configuration properties. For information on configuration properties specific to a connector, see its adapter user guide.

Using Connector Configurator Express

You configure connector properties from Connector Configurator Express, which you access from System Manager. For more information on using Connector Configurator Express, refer to the Connector Configurator Express appendix.

Setting and updating property values

The default length of a property field is 255 characters.

The connector uses the following order to determine a property's value (where the highest number overrides other values):

  1. Default
  2. Repository
  3. Local configuration file
  4. Command line

A connector obtains its configuration values at startup. If you change the value of one or more connector properties during a run-time session, the property's Update Method determines how the change takes effect. There are four different update methods for standard connector properties:

To determine how a specific property is updated, refer to the Update Method column in the Connector Configurator Express window, or see the Update Method column in the Property Summary table below.

Summary of standard properties

Table 11 provides a quick reference to the standard connector configuration properties. Not all the connectors make use of all these properties, and property settings may differ from integration broker to integration broker, as standard property dependencies are based on RepositoryDirectory.

You must set the values of some of these properties before running the connector. See the following section for an explanation of each property.


Table 11. Summary of standard configuration properties

Property name Possible values Default value Update method Notes
AdminInQueue Valid JMS queue name CONNECTORNAME /ADMININQUEUE Component
restart
Delivery
Transport is
JMS
AdminOutQueue Valid JMS queue name CONNECTORNAME/ADMINOUTQUEUE Component
restart
Delivery
Transport is
JMS
AgentConnections 1-4 1 Component
restart
Delivery
Transport is
IDL
AgentTraceLevel 0-5 0 Dynamic
ApplicationName Application name Value specified for the
connector application name
Component
restart

BrokerType ICS ICS

CharacterEncoding ascii7, ascii8, SJIS, Cp949, GBK, Big5, Cp297, Cp273, Cp280, Cp284, Cp037, Cp437
Note:
This is a subset
of supported
values.
ascii7 Component
restart

ConcurrentEventTriggeredFlows 1 to 32,767 1 Component
restart
Repository
directory
is
<REMOTE>
ContainerManagedEvents No value or JMS No value Component
restart
Delivery
Transport is
JMS
ControllerStoreAndForwardMode true or false truetrue Dynamic Repository
directory
is
<REMOTE>
ControllerTraceLevel 0-5 0 Dynamic Repository
directory
is
<REMOTE>
DeliveryQueue
CONNECTORNAME/DELIVERYQUEUE Component
restart
JMS transport
only
DeliveryTransport IDL or JMS IDL Component
restart

DuplicateEventElimination true or false false Component
restart
JMS transport
only: Container
Managed Events
must be
<NONE>
EnableOidForFlowMonitoring true or false false Component
restart

FaultQueue
CONNECTORNAME/FAULTQUEUE Component
restart
JMS
transport
only
jms.FactoryClassName CxCommon.Messaging.jms .IBMMQSeriesFactory
or any Java class name
CxCommon.Messaging. jms.IBMMQSeriesFactory Component
restart
JMS transport
only
jms.MessageBrokerName crossworlds.queue. manager crossworlds.queue.manager Component
restart
JMS transport
only
jms.NumConcurrentRequests Positive integer 10 Component
restart
JMS transport
only
jms.Password Any valid password
Component
restart
JMS transport
only
jms.UserName Any valid name
Component
restart
JMS transport
only
JvmMaxHeapSize Heap size in megabytes 128m Component
restart
Repository
directory
is
<REMOTE>
JvmMaxNativeStackSize Size of stack in kilobytes 128k Component
restart
Repository
directory
is
<REMOTE>
JvmMinHeapSize Heap size in megabytes 1m Component
restart
Repository
directory
is
<REMOTE>
Locale en_US, ja_JP, ko_KR,
zh_CN, zh_TW, fr_FR, de_DE,
it_IT, es_ES, pt_BR
Note:
This is a
subset of the
supported
locales.
en_US Component
restart

LogAtInterchangeEnd true or false false Component
restart

MaxEventCapacity 1-2147483647 2147483647 Dynamic Repository
Directory is
<REMOTE>
MessageFileName Path or filename InterchangeSystem.txt Component
restart

MonitorQueue Any valid queue name CONNECTORNAME/MONITORQUEUE Component
restart
JMS transport
only:
DuplicateEvent
Elimination
must be true
OADAutoRestartAgent true or false false Dynamic Repository
Directory is
<REMOTE>
OADMaxNumRetry A positive number 1000 Dynamic Repository
Directory is
<REMOTE>
OADRetryTimeInterval A positive number in
minutes
10 Dynamic Repository
Directory is
<REMOTE>
PollEndTime HH:MM
(HH is 0-23, MM is 0-59)
HH:MM Component
restart

PollFrequency A positive integer in
milliseconds

no (to disable polling)

key (to poll only when
the letter p is entered in
the connector's
Command Prompt window)

10000 Dynamic
PollQuantity 1-500 1 Agent
restart
JMS transport
only:
Container
Managed
Events is
specified
PollStartTime HH:MM(HH is 0-23, MM is 0-59) HH:MM Component
restart

RepositoryDirectory Location of metadata
repository

Agent
restart
Set to
<REMOTE>
RequestQueue Valid JMS queue name CONNECTORNAME/REQUESTQUEUE Component
restart
Delivery
Transport is
JMS
ResponseQueue Valid JMS queue name CONNECTORNAME/RESPONSEQUEUE Component
restart
Delivery
Transport is
JMS:
RestartRetryCount 0-99 3 Dynamic
RestartRetryInterval A sensible positive
value in minutes:
1 - 2147483547
1 Dynamic
SourceQueue Valid JMS queue name
CONNECTORNAME/SOURCEQUEUE Agent
restart
Only if
Delivery
Transport is
JMS and
Container
Managed
Events is
specified
SynchronousRequestQueue Valid JMS queue name
CONNECTORNAME/ SYNCHRONOUSREQUESTQUEUE Component
restart
Delivery
Transport is
JMS
SynchronousRequestTimeout 0 - any number (millisecs) 0 Component
restart
Delivery
Transport is
JMS
SynchronousResponseQueue Valid JMS queue name
CONNECTORNAME/ SYNCHRONOUSRESPONSEQUEUE Component
restart
Delivery
Transport is
JMS
WireFormat CwBO CwBO Agent
restart

Standard configuration properties

This section lists and defines each of the standard connector configuration properties.

AdminInQueue

The queue that is used by the integration broker to send administrative messages to the connector.

The default value is CONNECTORNAME/ADMININQUEUE.

AdminOutQueue

The queue that is used by the connector to send administrative messages to the integration broker.

The default value is CONNECTORNAME/ADMINOUTQUEUE.

AgentConnections

The AgentConnections property controls the number of ORB connections opened by orb.init[].

By default, the value of this property is set to 1. There is no need to change this default.

AgentTraceLevel

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

ApplicationName

Name that uniquely identifies the connector's application. This name is used by the system administrator to monitor the WebSphere business integration system environment. This property must have a value before you can run the connector.

BrokerType

Identifies the integration broker that you are using, which is ICS.

CharacterEncoding

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

Note:
Java-based connectors do not use this property. A C++ connector currently uses the value ascii7 for this property.

By default, a subset of supported character encodings only is displayed in the drop list. To add other supported values to the drop list, you must manually modify the \Data\Std\stdConnProps.xml file in the product directory. For more information, see the appendix on using Connector Configurator Express in this guide.

ConcurrentEventTriggeredFlows

Determines how many business objects can be concurrently processed by the connector for event delivery. Set the value of this attribute to the number of business objects you want concurrently mapped and delivered. For example, set the value of this property to 5 to cause five business objects to be concurrently processed. The default value is 1.

Setting this property to a value greater than 1 allows a connector for a source application to map multiple event business objects at the same time and deliver them to multiple collaboration instances simultaneously. This speeds delivery of business objects to the integration broker, particularly if the business objects use complex maps. Increasing the arrival rate of business objects to collaborations can improve overall performance in the system.

To implement concurrent processing for an entire flow (from a source application to a destination application), you must:

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

ContainerManagedEvents

This property allows a JMS-enabled connector with a JMS event store to provide guaranteed event delivery, in which an event is removed from the source queue and placed on the destination queue as a single JMS transaction.

This property only appears if the DeliveryTransport property is set to the value JMS.

The default value is No value.

When ContainerManagedEvents is set to JMS, you must configure the following properties to enable guaranteed event delivery:

You must also configure a data handler with the MimeType, DHClass, and DataHandlerConfigMOName (optional) properties. To set those values, use the Data Handler tab in Connector Configurator Express. The fields for the values under the Data Handler tab will be displayed only if you have set ContainerManagedEvents to JMS.

Note:
When ContainerManagedEvents is set to JMS, the connector does not call its pollForEvents() method, thereby disabling that method's functionality.

ControllerStoreAndForwardMode

Sets the behavior of the connector controller after it detects that the destination application-specific component is unavailable.

If this property is set to true and the destination application-specific component is unavailable when an event reaches InterChange Server Express, the connector controller blocks the request to the application-specific component. When the application-specific component becomes operational, the controller forwards the request to it.

However, if the destination application's application-specific component becomes unavailable after the connector controller forwards a service call request to it, the connector controller fails the request.

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

The default is true.

ControllerTraceLevel

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

DeliveryQueue

Applicable only if DeliveryTransport is JMS.

The queue that is used by the connector to send business objects to InterChange Server Express.

The default value is CONNECTORNAME/DELIVERYQUEUE.

DeliveryTransport

Specifies the transport mechanism for the delivery of events. Possible values are IDL for CORBA IIOP or JMS for Java Messaging Service. The default is IDL.

The connector sends service call requests and administrative messages over CORBA IIOP if the value configured for the DeliveryTransport property is IDL.

JMS

Enables communication between the connector and client connector framework 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, appear in Connector Configurator Express. The first two of these properties are required for this transport.

Important:
There may be a memory limitation if you use the JMS transport mechanism for a connector running on InterChange Server Express.

In this environment, you may experience difficulty starting both the connector controller (on the server side) and the connector (on the client side) due to memory use within the WebSphere MQ client.

DuplicateEventElimination

When you set this property to true, a JMS-enabled connector can ensure that duplicate events are not delivered to the delivery queue. To use this feature, the connector must have a unique event identifier set as the business object's ObjectEventId attribute in the application-specific code. This is done during connector development.

This property can also be set to false.

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

EnableOidForFlowMonitoring

When you set this property to true, the adapter framework will mark the incoming ObjectEventId as a foreign key for the purpose of flow monitoring.

The default is false.

FaultQueue

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

The default value is CONNECTORNAME/FAULTQUEUE.

JvmMaxHeapSize

The maximum heap size for the agent (in megabytes).

The default value is 128m.

JvmMaxNativeStackSize

The maximum native stack size for the agent (in kilobytes).

The default value is 128k.

JvmMinHeapSize

The minimum heap size for the agent (in megabytes).

The default value is 1m.

jms.FactoryClassName

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

The default is CxCommon.Messaging.jms.IBMMQSeriesFactory.

jms.MessageBrokerName

Specifies the broker name to use for the JMS provider. You must set this connector property when you choose JMS as your delivery transport mechanism (see DeliveryTransport).

The default is crossworlds.queue.manager.

jms.NumConcurrentRequests

Specifies the maximum number of concurrent service call requests that can be sent to a connector at the same time. Once that maximum is reached, new service calls block and wait for another request to complete before proceeding.

The default value is 10.

jms.Password

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

There is no default.

jms.UserName

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

There is no default.

Locale

Specifies the language code, country or territory, and, optionally, the associated character code set. The value of this property determines such cultural conventions as collation and sort order of data, date and time formats, and the symbols used in monetary specifications.

A locale name has the following format:

ll_TT.codeset

where:

ll
a two-character language code (usually in lower case)

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

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

By default, only a subset of supported locales appears in the drop list. To add other supported values to the drop list, you must manually modify the \Data\Std\stdConnProps.xml file in the product directory. For more information, see the appendix on using Connector Configurator Express in this guide.

The default value is en_US. If the connector has not been globalized, the only valid value for this property is en_US.

LogAtInterchangeEnd

Specifies whether to log errors to the integration broker's log destination. Logging to the broker's log destination also turns on e-mail notification, which generates e-mail messages for the MESSAGE_RECIPIENT specified in the InterchangeSystem.cfg file when errors or fatal errors occur.

For example, when a connector loses its connection to its application, if LogAtInterChangeEnd is set to true, an e-mail message is sent to the specified message recipient. The default is false.

MaxEventCapacity

The maximum number of events in the controller buffer. This property is used by flow control.

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

MessageFileName

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

If a connector message file does not exist, the connector uses InterchangeSystem.txt as the message file. This file is located in the product directory.

Note:
To determine whether a specific connector has its own message file, see the individual adapter user guide.

MonitorQueue

The logical queue that the connector uses to monitor duplicate events. It is used only if the DeliveryTransport property value is JMS and DuplicateEventElimination is set to TRUE.

The default value is CONNECTORNAME/MONITORQUEUE

OADAutoRestartAgent

Specifies whether the connector uses the automatic and remote restart feature. This feature uses an MQ trigger to restart the connector after an abnormal shutdown, or to start a remote connector from System Monitor.

This property must be set to true to enable the automatic and remote restart feature.

The default value is false.

OADMaxNumRetry

Specifies the maximum number of times that the MQ-triggered OAD automatically attempts to restart the connector after an abnormal shutdown. The OADAutoRestartAgent property must be set to true for this property to take effect.

The default value is 1000.

OADRetryTimeInterval

Specifies the number of minutes in the retry-time interval for the MQ-triggered OAD. If the connector agent does not restart within this retry-time interval, the connector controller asks the OAD to restart the connector agent again. The OAD repeats this retry process as many times as specified by the OADMaxNumRetry property. The OADAutoRestartAgent property must be set to true for this property to take effect.

The default is 10.

PollEndTime

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

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

PollFrequency

The amount of time between polling actions. Set PollFrequency to one of the following values:

The default is 10000.

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

PollQuantity

Designates the number of items from the application that the connector should poll for. If the adapter has a connector-specific property for setting the poll quantity, the value set in the connector-specific property will override the standard property value.

PollStartTime

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

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

RequestQueue

The queue that is used by InterChange Server Express to send business objects to the connector.

The default value is CONNECTOR/REQUESTQUEUE.

RepositoryDirectory

The location of the repository from which the connector reads the XML schema documents that store the meta-data for business object definitions.

This value must be set to <REMOTE> because the connector obtains this information from the InterChange Server Express repository.

ResponseQueue

Applicable only if DeliveryTransport is JMS.

Designates the JMS response queue, which delivers a response message from the connector framework to the integration broker. InterChange Server Express sends the request and waits for a response message in the JMS response queue.

RestartRetryCount

Specifies the number of times the connector attempts to restart itself. When used for a parallel connector, specifies the number of times the master connector application-specific component attempts to restart the slave connector application-specific component.

The default is 3.

RestartRetryInterval

Specifies the interval in minutes at which the connector attempts to restart itself. When used for a parallel connector, specifies the interval at which the master connector application-specific component attempts to restart the slave connector application-specific component. Possible values ranges from 1 to 2147483647.

The default is 1.

SourceQueue

Applicable only if DeliveryTransport is JMS and ContainerManagedEvents is specified.

Designates the JMS source queue for the connector framework in support of guaranteed event delivery for JMS-enabled connectors that use a JMS event store. For further information, see ContainerManagedEvents.

The default value is CONNECTOR/SOURCEQUEUE.

SynchronousRequestQueue

Applicable only if DeliveryTransport is JMS.

Delivers request messages that require a synchronous response from the connector framework to the broker. This queue is necessary only if the connector uses synchronous execution. With synchronous execution, the connector framework sends a message to the SynchronousRequestQueue and waits for a response back from the broker on the SynchronousResponseQueue. The response message sent to the connector bears a correlation ID that matches the ID of the original message.

The default is CONNECTORNAME/SYNCHRONOUSREQUESTQUEUE

SynchronousResponseQueue

Applicable only if DeliveryTransport is JMS.

Delivers response messages sent in reply to a synchronous request from the broker to the connector framework. This queue is necessary only if the connector uses synchronous execution.

The default is CONNECTORNAME/SYNCHRONOUSRESPONSEQUEUE

SynchronousRequestTimeout

Applicable only if DeliveryTransport is JMS.

Specifies the time in minutes that the connector waits for a response to a synchronous request. If the response is not received within the specified time, then the connector moves the original synchronous request message into the fault queue along with an error message.

The default value is 0.

WireFormat

This is the message format on the transport. The setting isCwBO.

Copyright IBM Corp. 2004