Adapter for Spirent Applications

IBM(R) WebSphere(R) Business Integration Adapter for Spirent Applications includes the connector for Spirent Flow. This adapter operates with the WebSphere InterChange Server (ICS),WebSphere MQ Integrator Broker(R), and WebSphere Application Server integration brokers. An integration broker is an application that integrates heterogeneous sets of applications and provides services that include data routing.

This adapter includes the following elements:

This manual provides information about using this adapter with WebSphere InterChange Server (ICS) integration brokers: WebSphere MQ Integrator Broker and WebSphere Application Server.

Overview of the connector

This section provides an overview of the connector component of the IBM WebSphere Business Integration Adapter for Spirent Applications. Connectors consist of two parts: the application-specific component and the connector framework. The application-specific component contains code tailored to a particular application. The connector framework, whose code is common to all connectors, acts as an intermediary between the integration broker and the application-specific component. The connector framework provides the following services between the integration broker and the application-specific component:

This document contains information about the connector framework and the application-specific component, which it refers to as the connector. The connector enables WebSphere InterChange Server (ICS) or WebSphere MQ Integrator Broker or WebSphere Application Server to communicate with Spirent applications, REACT 2.900 and Flow 1.300, through the exchange of business objects.

REACT is an application for interactive and automated testing of a wide variety of network services. Flow receives test requests from external systems and performs testing using REACT. Flow provides Hekimian Trouble Interface (HTI) as a remote access interface for external systems. HTI handles test request/test response transactions with the external systems. The connector uses HTI to send test requests and receive the responses.

The communications between the connector and HTI are established over CORBA. The connector sends the test requests to HTI. After the test requests are processed by REACT, HTI sends back the test results as responses.

Connector components

The IBM WebSphere Business Integration Adapter for Spirent Applications consists of a connector, two databases, and HTI modules. The following diagram shows the architecture of all components. The connector is provided as a Java(TM) JAR file that implements the business object verb support and the polling mechanism for event notification.

This diagram shows the relationships of all components included in the IBM WebSphere Business Integration Adapter for Spirent Applications.

Connector

The connector, which is written in Java, complies with the IBM business integration standards for adapters. The connector receives the test request for Spirent from the integration broker and sends the test request to Flow via the HTI. The connector is notified of the response by Flow, generates the business object corresponding with the response, and then sends the business object to the integration broker. The connector also generates logging and tracing messages that it writes to a file or the connector console, or sends to the integration broker.

Databases

The connector internally uses two database tables for event storing and archiving:

The connector supports three database applications for the tables; DB2, Oracle, and Microsoft SQLServer.
The event store table has the following schema:

Event store table schema
Column DB2 type  Oracle type Microsoft SQLServer type Description
event_id varchar(16) varchar(16) varchar(16) Unique ID. Used as primary key.
event_data clob(10000) long text Test results in the form of XML strings generated from tag and value pairs sent from Flow
stored_time timestamp date datetime Time when the connector receives the event from Flow

The archive table has the following schema:

Archive table schema
Column DB2 type  Oracle type Microsoft SQLServer type Description
event_id varchar(16) varchar(16) varchar(16) Unique ID. Used as primary key.
event_data clob(10000) long text Test results in the form of XML string generated from tag and value pairs sent from Flow
event_result integer integer integer Event status as defined by IBM WebSphere Business Integration Adapter framework
stored_time timestamp date datetime Time when the connector receives the event from Flow
processed_time timestamp date datetime Time when the connector process the event

How the connector works

This section describes how the connector interacts with the REACT and Flow Spirent applications, and how the connector processes business object requests and event notifications.

Interacting with the Spirent applications

At startup, the connector obtains a reference to a remote object of HTI. VisiBroker's SmartAgent (osagent) retrieves the remote object. The connector sends test requests to Flow via HTI. In order to receive asynchronous responses, the connector registers itself as a listener to the Flow via HTI.

If an error occurs within the connector or during its online processing within the Spirent applications, the connector's application-specific component sends the FAIL return code to the connector framework, which sends it to the integration broker.

Processing business object requests

The connector only supports the Create verb. Any other verbs generate an error and are not processed by the connector. When the connector receives a business object containing a test request to Spirent, the connector converts the contents of the business object into tag and value pairs which it passes to Flow via a method provided by HTI. All test requests are sent asynchronously and the responses are later returned as an asynchronous event.

Event notification

To publish response events to the connector after the requested tests are executed, Flow sends the events to listeners that have been registered. Since the connector registers itself as a listener when it starts up, all asynchronous requests to Flow are returned to the connector as published events.

Flow sends responses to the connector in the forms of tag and value pairs. The connector converts the pairs into XML strings and stores them in the event store table. A response corresponds to an XML string.

Event polling

The connector polls the event store table at a regular, configurable interval. It searches for all events in the table, converts the XML data of the events to business objects, and sends the business objects to the integration broker. A connector-specific configuration property can be used to specify the number of events to pick from the event table at each polling. Events that have been processed are removed from the event store table.

Event archiving

The connector archives the events that it processes in the event polling operation. These events are added to the archive table. The results of processing are set to a field of each record added to the table.

Installing and configuring the connector

This section contains the installation and configuration information specific to the connector for Spirent. For general information on installing and configuring the product, refer to the guide below.

Prerequisites

Before you use the IBM WebSphere Business Integration Adapter for Spirent Applications, verify that your system has the required software. You must also perform operations such as importing definitions of the connector, business objects, and configuration properties. This section describes the required software and operations.

Required software for using the connector

The connector works on the following platform and database combinations:

The connector requires the following softwares:

The connector requires the following Spirent related files:

Note: If you use the connector with the WebSphere Business Integration Adapter 2.0 environment, you must install the WebSphere Business Integration Adapter Runtime library 1.2.3 FixPack, available on the IBM support download site at www-3.ibm.com/software/integration/cw/ics/support/.

Installing the connector

The connector is installed during the IBM WebSphere Business Integration Adapter product installation.

After your IBM WebSphere Business Integration Adapter system is installed, you can install additional connectors from the IBM WebSphere Business Integration Server CD at any time. To do this, insert the IBM WebSphere Business Integration Server CD, run the installation program and choose the connectors you want to install.

If you add the connector for Spirent after you install the connector to the IBM WebSphere Business Integration Server, then you must carry out the following steps in order to install its definition:

  1. Stop the IBM WebSphere Business Integration Server if it is currently running.
  2. Restart the IBM WebSphere Business Integration Server with the -design option so that it runs in design mode.
  3. Open the Command Prompt window.
  4. Navigate to the directory in which the connector definition file is located, c:\IBM\WebSphereICS\repository\Spirent, for example.
  5. Run the following command:
    repos_copy -iCN_Spirent.txt -s Server_name -u User_name -p Password
    replacing Server_name, User_name, and Password, with the appropriate values for your server and User ID.
  6. Stop and restart the IBM WebSphere Business Integration Server without using any options, so that it runs in production mode.

The following two subsections describe how to install the connector for Spirent on a UNIX or Windows system. The remainder of the chapter applies to both UNIX and Windows installations of the connector, unless otherwise indicated.

Installing on a UNIX system

To install the connector on a UNIX system, run the Installer for IBM WebSphere Business Integration Adapter and select IBM WebSphere Business Integration Adapter for Spirent Applications.

IBM WebSphere Business Integration Adapter installer installs standard files associated with the connector. The following table describes the UNIX file structure that the connector uses.

Installed UNIX file structure for the connector
Subdirectory of $CROSSWORLDS Description of contents
connectors/Spirent CWSpirent.jar: contains a program of this connector implemented by Java

start_Spirent.sh: the startup script for the connector. The script is called from the generic connector manager script.
connectors/Spirent/dependencies event_table_xxx.sql: contains sql statements required to create the event and archive tables in the database
connectors/messages SpirentConnector.txt and SpirentConnector_en_US.txt: connector message files
connectors/Spirent/Samples xxx.in: sample application-specific business object (ASBO)

SpirentAgentConfig.cfg: sample configuration file in case of the integration broker is InterChange Server.
repository/Spirent CN_Spirent.txt: connector definition file

Installing on a Windows system

To install the connector on a Windows system, run IBM WebSphere Business Integration Adapter installer and select the IBM WebSphere Business Integration Adapter for Spirent.

IBM WebSphere Business Integration Adapter installer installs standard files associated with the connector. The following table describes the Windows file structure that the connector uses.

Installed Windows file structure for the connector
Subdirectory of %CROSSWORLDS% Description of contents
connectors\Spirent CWSpirent.jar: contains a program of this connector implemented by Java

start_Spirent.bat: the startup script for the connector
connectors\Spirent\dependencies event_table_xxx.sql: contains sql statements required to create the event and archive tables in the database
connectors\messages SpirentConnector.txt and SpirentConnector_en_US.txt: connector message files
connectors\Spirent\Samples xxx.in: sample application-specific business object (ASBO)

SpirentAgentConfig.cfg: sample configuration file in case the integration broker is InterChange Server
repository\Spirent CN_Spirent.txt: connector definition file

Creating the event and archive tables in the database

The connector uses event and archive tables for event notification and to archive the result. See Databases for a description of the schemas of these two tables. You must create the tables in the database before the connector can process event delivery.

SQL scripts for creating the event and archive tables

The following SQL script files are provided in the connectors/Spirent/dependencies directory. These scripts create the tables using the default names.

To create the databases, perform one of the following sequences of steps, depending on the database you are using:

Microsoft SQL Server 2000
  1. Start Query Analyzer by clicking Start > Programs > Microsoft SQL Server > Query Analyzer.
  2. Connect to SQL Server as a database user.
  3. Open the event_table_mssqlserver.sql file.
  4. Execute the file by clicking Query > Execute (or press F5).
IBM DB2
  1. Copy the event_table_db2.sql file onto the DB2 instance user's home directory.
  2. Log in as a DB2 instance user.
  3. At the command prompt, type the following command:

    $ db2batch -d dbinstance -a dbuser/dbpassword -f event_table_db2.sql

    where

Oracle Database Server
  1. Copy the event_table_oracle.sql file into the home directory of the Oracle account.
  2. Start SQL*Plus.
  3. Enter user name.
  4. Enter password.
  5. Execute the SQL script by entering the following command:
    SQL>@event_table_oracle

Configuring Event and Archive Processing

To configure event and archive processing, you must use configuration properties to specify the following information:

See Connector-specific properties for more details.

Preparing the dependent files

Spirent API jar file

You will need the IDL file to create the Spirent API jar file. You can get the IDL file from the Spirent plc Website. Follow the procedures below to create and place the Spirent API jar file in the appropriate directory on a Windows system:

  1. Install the IBM Developer Kit for Windows, Java 2 Technology Edition Version 1.3.1. You can use the idlj.exe utility.
  2. Create a work directory and copy the IDL file into it.
  3. At the command prompt, type the following commands:

    Idlj -emitAll -fallTIE *.idl

    javac HtiServiceProviderInterface\*.java

    jar -cvf htiServiceProvider.jar .\HtiServiceProviderInterface\*.class

  4. Copy the htiServiceProvider.jar into the connectors/Spirent/dependencies directory.

JDBC driver

Copy the JDBC driver file(s) detailed in the following sections into the connectors/Spirent/dependencies directory (depending on which database you use):

Microsoft SQL Server 2000
msbase.jar, msutil.jar and mssqlserver.jar

Note: The above files are included in Microsoft SQL Server 2000 Driver for JDBC, available on the Microsoft Download Center www.microsoft.com/downloads, as of Nov. 2002.

IBM DB2

No action is required. The connector uses the DB2 driver installed with the IBM WebSphere Business Integration Adapter.

Oracle Database Server

classes12.zip, located in the directory where Oracle is installed

Configuring the connector

Before you can run the connector, you must set its standard and connector-specific configuration properties. To do this, use one of the following tools:

Standard connector properties

Standard configuration properties provide information that all connectors use. See Standard configuration properties for documentation of these properties.

Connector-specific properties

This section documents configuration properties specific to this connector at runtime. Connector-specific properties provide a way of changing static information or logic within the connector without having to recode and rebuild it.

The following table lists the connector-specific configuration properties for this connector. See the sections that follow for explanations of these properties.

Connector-specific property information for this connector
Property Possible values Default value Required
ArchiveTable
Database table name CWHKMNAR Yes
DataBasePassword Database password (none) Yes
DataBaseURL URL string (none) Yes
DataBaseUserName Database user name (none) Yes
EventStoreTable Database table name CWHKMNES Yes
HTIListenerName Listener name registerd to HTI HTI_Event_Listener Yes
HTIReadyTimeout Time in millisecond 15000 Yes
HTIRequestBO ASBO name Spirent_TestRequest Yes
HTIResponseBO ASBO name Spirent_TestResponse Yes
HTITagValueBO ASBO name Spirent_TagAndValue Yes
IORFileName Full path IOR file name HekimianNamingService.ior Yes
JDBCDriver JDBC driver name (none) Yes
LoopSleepTime Time in millisecond 3000 Yes
PollQuantity Integer; 1 or more 1 Yes

ArchiveTable

This property specifies the name of the database table that the connector uses to archive events that have been processed.

DataBasePassword

This property specifies the password for the database containing the event store and the archive table.

DataBaseURL

This property specifies the URL string for accessing the database that has the event store and the archive table. Use one of the following forms of string, depending on the database you are using:

Where host_name is the host name which your database system is installed, port_number is the port number used to connect the database system, and db_name is the name of the database that contains the event store and the archive table.

DataBaseUserName

This property specifies the user name for the database that has the event store and the archive table.

EventStoreTable

This property specifies the name of the database table that the connector uses to store events received from Flow.

HTIListenerName

This property specifies the name of the listener registered to Flow via HTI. Events from Flow are received by the listener.

HTIReadyTimeout

This property specifies time in milliseconds. When it starts up, the connector tries to bind to HTI until the specified time has passed.

HTIRequestBO

This property specifies the name of the top-level ASBO used for a test request to the connector.

HTIResponseBO

This property specifies the name of the top-level ASBO used for a test response from the connector.

HTITagValueBO

This property specifies the name of the ASBO representing a tag and value pair contained both in the test request and in the test response. The ASBO is contained by the top-level ASBOs for test request and test response.

IORFileName

This property specifies the name of the IOR file which the Spirent Server program generates. You must copy the HekimianNamingService.ior from an appropriate directory,for example /hekimian/cof/adm, on the Spirent Server machine to the directory of the machine running the Spirent Adapter. Then specify the full path name of the IOR file. For example, c:\ HekimianNamingService.ior Please contact Spirent if the location of the file is unknown.

JDBCDriver

This property specifies the name of the JDBC driver used for accessing the database that has the event store and the archive table. Use one of the following values, depending on your database:

LoopSleepTime

This property specifies interval time to check if binding to HTI is established.

PollQuantity

This property specifies the number of events to retrieve during each polling for events.

Environment specific configuration

This section describes the configuration information specific to the environment such as the integration broker and the platform you are using.

For Unix

If you install the connector on Unix, the installer should automatically create the connector_manager_Spirent file which is the start up script for the connector. In this case, complete the following steps:

  1. Edit the file using an appropriate text editor.
  2. Specify the value of AGENTCONFIG_FILE to the connector configuration file you created. -c is required before the file name, as shown in the following example:

       AGENTCONFIG_FILE=-cConnectorConfigurationFile

    Where ConnectorConfigurationFile is the connector configuration file you created. The file name should include the full path name.

Note: You can also create the connector start up script by completing the following steps:

  1. Run the Connector Configuration Tool, which generates a connector start up script.
  2. In the Connector Configuration Tool, set the value of Agent Config File to the connector configuration file you created. The file name should include the full path name.

See Using the Connector Configuration Tool in Adapter for WebSphere MQ Integrator Broker User Guide for details on using the Connector Configuration Tool.

For Windows

If you install the connector on Windows, the installer should automatically create a Windows shortcut to start the connector. In this case, complete the following steps:

  1. Right-click the short cut and select Properties.
  2. In the property window, specify the connector configuration file as the argument of the start_Spirent.bat using the -c option, as shown in the following example:
     -cConnectorConfigurationFile

    Where ConnectorConfigurationFile is the connector configuration file you created. The file name should include the full path name.

Note: Add the -c option to the command. Do not remove the existing arguments.

Creating or modifying business objects

The connector component of the IBM WebSphere Business Integration Adapter for Spirent Applications makes assumptions about the structure of its supported business objects, the relationships between parent and child business objects, and the format of the application-specific information. Therefore, when you create or modify a business object that will be processed by the connector, your modifications must conform to the rules the connector is designed to follow. If they do not, the connector cannot process new or modified business objects correctly.

This section describes how the connector processes business objects and describes the assumptions the connector makes. You can use this information as suggestions for implementing new business objects or as a guide to modifying existing ones.

Business object and attribute naming conventions

For clarity, use a prefix, such as Spirent_, when you name a business object to represent data for Spirent. Follow this convention for all child business objects as well as for the top-level business object. For example, the business object name for test request would be Spirent_TestRequest.

Note: In this document, the term hierarchical business object refers to a complete business object, including all the child business objects that it contains at any level. The term individual business object refers to a single business object, independent of any child business objects it contains. The term top-level business object refers to the individual business object at the top of the hierarchy that does not itself have a parent business object.

Business object structure

WebSphere business objects can be flat or hierarchical. All the attributes of a flat business object are simple, meaning that they represent a single value (such as String or Integer).

In addition to its simple attributes, a hierarchical business object can have attributes that represent a single-cardinality child business object or an array of child business objects. In turn, each of these business objects can contain single-cardinality child business objects or arrays of child business objects, and so on.

A single-cardinality relationship occurs when an attribute in a parent business object represents a single child business object. The type of the attribute is the same as that of the child business object.

A multiple-cardinality relationship occurs when an attribute in a parent business object represents an array of child business objects. The type of the attribute is the same as the type of the array of child business objects.

Top-level business object structure

The top-level business objects that this connector uses have the following structures:

The attribute names TagAndValue, Tag, and Value cannot be changed. Each name of the top level business objects for request and response should be specified in the connector-specific configuration properties, HTIRequestBO and HTIResponseBO, respectively. A name of the business object representing a tag and value pair should be specified in the connector-specific property, HTITagValueBO.

For more information on the AppSpecificInfo of the top_level_business_object, see Business object application-specific information.

Top-level business object structure examples

Creating a business object

Business objects used by the connector are generated by using Business Object Designer and imported to the integration broker.

Loading the business object to the integration broker.

For instructions on loading the business object, refer to the guide below.

Note: Because the XML element is case-sensitive, while the business object name is case-insensitive, the repos_copy utility might return with an error. In this case, check the error message and manually modify the name of business object that causes the error.

Business object verb processing

This section describes the following aspects of processing a business object's verbs:

Verb determination

A top-level business object and each of its individual child business objects can contain their own verbs. Therefore, an integration broker can pass a business object that has different verbs for parent and child business objects to the connector. When this occurs, the connector uses the verb of the top-level parent business object to determine how to process the entire business object.

Verb processing for business object requests

This section outlines the steps the connector takes when creating, retrieving, updating or deleting a business object that it receives from the integration broker. The connector processes hierarchical business objects recursively; that is, it performs the same steps for each child business object until it has processed all individual business objects.

Create operations

The connector performs the following steps when it receives a top-level business object with the Create verb specified

  1. Extracts the TagAndValue business objects from the top-level business object for test request.
  2. Convert each TagAndValue business object to a tag and value pair.
  3. Generate an array of the pairs converted from all TagAndValue business objects
  4. Calls the method of HTI to send a test request with the array generated as a paremeter.

Retrieve operations

The connector does not support this verb. It returns a status of FAIL.

Update operations

The connector does not support this verb. It returns a status of FAIL.

Delete operations

The connector does not support this verb. It returns a status of FAIL.

Business object attribute properties

Business object architecture defines various properties that apply to attributes. This section describes how the connector interprets several of these properties and describes how to set them.

Name property

Each business object attribute must have a unique name.

Type property

Each business object attribute must have a type, such as Integer, String, or the type of a child business object.

Cardinality property

Each business object attribute that represents a child business object or an array of child business objects has the value of 1 or n, respectively, for the cardinality property. All attributes that represent child business objects also have a ContainedObjectVersion property (which specifies the child's version number) and a Relationship property (which specifies the Containment value).

Key property

At least one simple attribute of each business object must be specified as the key. To specify that an attribute is the key for the business object, set the key property of the attribute to true.

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

Required property

This property specifies whether an attribute must contain a value.

If this property is specified for an attribute that represents a single-cardinality child business object, the connector requires the parent business object to contain a child business object for this attribute.

When the connector receives a business object with a create request, the connector might cause the create operation to fail if a required attribute does not have a valid value.

The connector does not use this property for attributes that represent an array of child business objects.

Max Length property

If the attribute is of type String, this property specifies the maximum length allowed for the attribute's value.

AppSpecificInfo

For information on this property, see Business object application-specific information.

Default value property

The connector does not support this property.

Special attribute value

Simple attributes in business objects can have a special value: CxIgnore. When it receives a business object from the integration broker, the connector ignores all attributes with a value of CxIgnore. It is as if those attributes were invisible to the connector.

Business object application-specific information

Application-specific information in business object definitions provides the connector with application-dependent instructions on how to process business objects. The connector parses the application-specific information from the attributes or verb of a business object or from the business object itself to generate queries for create, update, retrieve and delete operations.

The connector stores some of the business object's application-specific information in cache and uses this information to build queries for all the verbs.

If you extend or modify an application-specific business object, you must make sure that the application-specific information in the business object definition matches the syntax that the connector expects.

This section provides information on the application-specific information format for business objects supported by the connector.

The following table provides an overview of the functionality available in business object application-specific information.

Overview of application-specific information in supported business objects
Scope of application-specific information Functionality
Entire business object The connector does not support this
Simple attributes The connector does not support this
Business object verb The connector does not support this

Troubleshooting

This section describes problems that you may encounter when running the connector.

Event processing

If there are events in the event table, and they are not being processed while the connector is running, ensure that the following conditions are met:

Mapping

If the business objects are not being mapped or mapping is not being invoked, check to make sure the maps have been installed in the correct directory.

Error handling and logging

The connector logs an error message whenever it encounters a condition that causes its current processing of a business object and verb to fail. When such an error occurs, the connector also prints a textual representation of the failed business object as it was received. The connector writes the text to the connector log file or to the standard output stream, depending on its configuration. You can use the text as an aid in determining the source of the error.

Error types

The following table describes the types of tracing messages that the connector issues at each trace level. These messages are in addition to any tracing messages issued by the IBM WebSphere Business Integration Adapter architecture, such as the Java connector execution wrapper and the IBM WebSphere MQ message interface.

Spirent connector tracing messages
Tracing level Tracing messages
Level 0
  • Issues a message that identifies the connector version. No other tracing is done at this level. This is the default value.
Level 1
  • Logs error messages, status messages, and identifying (key) information for each business object processed.
  • Records entry and exit trace for pollForEvents() method.
Level 2
  • Identifies the business object handlers used for each object the connector processes.
  • Logs each time a business object is posted to the integration broker.
  • Records entry and exit trace for doVerbFor() method.
  • Indicates each time a test request or a test response business object is received.
Level 3
  • Relates to business object processing. Examples of this include finding a match between business objects, or finding a business object in an array of child business objects. either from gotApplEvent() or executeCollaboration().
Level 4
  • Identifies application-specific information. Examples of this information include the values returned by the methods that process the application-specific information fields in business objects.
  • Identifies when the connector enters or exits a function. These messages help trace the process flow of the connector.
Level 5
  • Indicates connector initialization. Examples of this message include the value of each connector configuration property that has been retrieved from InterChange Server.
  • Represents statements executed in the application. The connector log file contains all statements executed in the target application and the value of any variables that are substituted (where applicable).
  • Records business object dumps. The connector should output a text representation of a business object before it begins processing (showing the object the connector receives from the integration broker) and after it has processed the object (showing the object the connector returns to the integration broker).
  • Records parameters of entry and return values on exit for each method.

Error messages

All the messages that the connector generates are stored in a message file named SpirentConnector.txt. Each error has an error number followed by the error message. For example:

    1000
     Unexpected null object {1} found.
     [EXPL]
     A required object to run the connector agent was found
         as null. This indicates that an internal error occurred.
     1001
     Class cast exception ;{1}. Expected class was {2}.
     [EXPL]
     An unexpected class was found. This indicates that an
         internal error occurred.

Loss of connection to the application

If the connector fails to establish a connection during startup, it sends FAIL to the integration broker and terminates.
If it occurs after the connector has started, a log message indicating this error is written in log output.

Appendix A: Standard configuration properties for connectors

This appendix describes the standard configuration properties for WebSphere Business Integration adapter connectors. The information covers connectors running on the following brokers:

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

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

Note: In this document, backslashes (\) are used as the convention for directory paths. For UNIX installations, substitute slashes (/) for backslashes and follow the conventions for each operating system.

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

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

Note: Connector Configurator and System Manager run only on the Windows system. If you are running the connector on a UNIX system, you must have a Windows machine with these tools installed. To set connector properties for a connector that runs on UNIX, you must start up System Manager on the Windows machine, connect to the UNIX integration broker, and bring up Connector Configurator for the connector.

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 (only if WebSphere InterChange Server is the integration broker)
  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 window, or see the Update Method column in the Property Summary table below.

Summary of standard properties

The table below 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.

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

Summary of standard configuration properties
Property name Possible values Default value Update method Notes
AdminInQueue Valid JMS queue name CONNECTORNAME /ADMININQUEUE  
Delivery
Transport is
JMS
AdminOutQueue Valid JMS queue name CONNECTORNAME/ADMINOUTQUEUE  
Delivery
Transport is
JMS
AgentConnections 1-4 1
Component
restart

ICS: Delivery
Transport is
MQ or IDL
AgentTraceLevel 0-5 0 Dynamic  
ApplicationName application name The value that is specified for
the connector application name

Component
restart

Value required
BrokerType ICS, WMQI, WAS      
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 No value
Component
restart
 
ContainerManagedEvents No value or JMS JMS  
Guaranteed
event delivery
ControllerStoreAndForwardMode true or false True Dynamic ICS only
ControllerTraceLevel 0-5 0 Dynamic ICS only
DeliveryQueue   CONNECTORNAME/DELIVERYQUEUE
Component
restart

JMS transport
only
DeliveryTransport MQ, IDL, or JMS JMS
Component
restart

For WAS or
WMQI:
JMS only
DuplicateEventElimination True/False False
Component
restart

JMS transport
only: Container
Managed Events
must be
<NONE>
FaultQueue   CONNECTORNAME/FAULTQUEUE
Component
restart
 
jms.FactoryClassName CxCommon.Messaging.jms .IBMMQSeriesFactory or CxCommon.Messaging .jms.SonicMQFactory
or any Java class name
CxCommon.Messaging. jms.IBMMQSeriesFactory
Server
restart

JMS transport
only
jms.MessageBrokerName If FactoryClassName is
IBM, use
crossworlds.queue. manager.
If FactoryClassName
is Sonic, use
localhost:2506.
crossworlds.queue.manager
Server
restart

JMS transport
only
jms.NumConcurrentRequests Positive integer 10
Component
restart

JMS transport
only
jms.Password Any valid password  
Server
restart

JMS transport
only
jms.UserName Any valid name  
Server
restart

JMS transport
only
JvmMaxHeapSize Heap size in megabytes 128m
Component
restart
ICS only
JvmMaxNativeStackSize Size of stack in kilobytes 128k
Component
restart
ICS only
JvmMinHeapSize Heap size in megabytes 1m
Component
restart
ICS only
ListenerConcurrency 1- 100 1
Component
restart

ICS only:
Delivery
Transport must
be MQ
Locale en_US, ja_JP, ko_KR,
zh_C, zh_T, fr_F, de_D,
it_I, es_E, pt_BR

Note:

This is a
subset of the
supported
locales.

en_US
Component
restart
 
LogAtInterchangeEnd True or False False
Component
restart
ICS only
MaxEventCapacity 1-2147483647 2147483647 Dynamic
ICS:
Repository
Directory must
be <REMOTE>
MessageFileName path/filename Connectorname.txt or 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
ICS only:
Repository
Directory must
be <REMOTE>
OADMaxNumRetry A positive number 1000 Dynamic
ICS only:
Repository
Directory must
be <REMOTE>
OADRetryTimeInterval A positive number in
minutes
10 Dynamic
ICS only:
Repository
Directory must
be <REMOTE>
PollEndTime HH:MM 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 Component
restart

JMS transport
only:
DuplicateEvent
Elimination
must be True
PollStartTime HH:MM(HH is 0-23, MM is 0-59) HH:MM Component
restart
 
RepositoryDirectory Location of meta-data
repository
  Component
restart

For ICS: set to
<REMOTE>
For WMQI and
WAS: set to
<local directory>
RequestQueue Valid JMS queue name CONNECTORNAME/REQUESTQUEUE Component
restart
 
ResponseQueue Valid JMS queue name CONNECTORNAME/RESPONSEQUEUE Component
restart
 
RestartCount 0-100   Dynamic
Connector must
be in polling
mode
RestartRetryCount 0-99 3 Dynamic  
RestartRetryInterval A sensible positive value in
minutes
1 Dynamic  
RHF2MessageDomain mrm, xml mrm Component
restart

Only if
Delivery
Transport is
JMS and
WireFormat
is CwXML
SourceQueue Valid WebSphere MQ name CONNECTORNAME/SOURCEQUEUE Component
restart

Only if
Delivery
Transport is
JMS and
Container
Managed
Events is
specified
SynchronousRequestQueue   CONNECTORNAME/ SYNCHRONOUSREQUESTQUEUE
Component
restart
 
SynchronousRequestTimeout 0 - any number (millisecs) 0
Component
restart
 
SynchronousResponseQueue   CONNECTORNAME/ SYNCHRONOUSRESPONSEQUEUE
Component
restart
 
WireFormat CwXML, CwBO CwXML
Component
restart

CwXML for
WMQI and
WAS;
CwBO if
Repository
Directory is
<REMOTE>
(ICS)
WisfSynchronousRequest Timeout 0 - any number
(millisecs)
0
Component
restart
WAS only

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

WebSphere ICS only.

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 type that you are using. The options are ICS, WMQI or WAS.

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 ASCII for this property. If you previously configured the value of this property to ascii7 or ascii8, you must reconfigure the connector to use either ASCII or one of the other supported values.

Important: By default only a subset of supported character encodings display 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 Connector Configurator.

The default value is ascii.

ConcurrentEventTriggeredFlows

WebSphere ICS only.

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.

The default value is JMS. It can also be set to 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. 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.

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

ControllerStoreAndForwardMode

WebSphere ICS only.

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 ICS, 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

WebSphere ICS only.

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

DeliveryQueue

The queue that is used by the connector to send business objects to the integration broker.

The default value is DELIVERYQUEUE.

DeliveryTransport

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

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

WebSphere MQ and IDL

Use WebSphere MQ rather than IDL for event delivery transport, unless you must have only one product. WebSphere MQ offers the following advantages over 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. 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 in the following environment:

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. If your installation uses less than 768M of process heap size, IBM recommends that you set:

This script resides in the \bin directory below the product directory. With a text editor, 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 can occur, which can adversely affect the performance of your system.

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.

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). This property is applicable only if the RepositoryDirectory value is <REMOTE>.

The default value is 128m.

JvmMaxNativeStackSize

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

The default value is 128k.

JvmMinHeapSize

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

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

ListenerConcurrency

This property supports multi-threading in MQ Listener when ICS is the integration broker. It enables batch writing of multiple events to the database, thus improving system performance. The default value is 1.

This property applies only to connectors using MQ transport. The DeliveryTransport property must be set to MQ.

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

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

TT

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

codeset

is 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 Connector Configurator.

The default value is en_US. If the connector has not been globalized, the only valid value for this property is en_US. To determine whether a specific connector has been globalized, see the connector version list on these websites:

http://www.ibm.com/software/websphere/wbiadapters/infocenter, or http://www.ibm.com/websphere/integration/wicserver/infocenter

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 and is applicable only if the value of the RepositoryDirectory property is <REMOTE>.

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

Valid only when the integration broker is ICS and the Repository Directory is <REMOTE>.

Specifies whether the Object Activation Daemon (OAD) automatically attempts to restart the application-specific component after an abnormal shutdown. This property is required for automatic restart.

The default value is false.

OADMaxNumRetry

Valid only when the integration broker is ICS and the Repository Directory is <REMOTE>.

Specifies the maximum number of times that the OAD automatically attempts to restart the application-specific component after an abnormal shutdown.

The default value is 1000.

OADRetryTimeInterval

Valid only when the integration broker is ICS and the Repository Directory is <REMOTE>.

Specifies the number of minutes for the interval during which the OAD automatically attempts to restart the application-specific component after an abnormal shutdown. If the application-specific component does not start within the specified interval, the OAD repeats the attempt as many times as specified in OADMaxNumRetry.

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 the integration broker to send business objects to the connector.

The default value is 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.

When the integration broker is ICS, this value must be set to <REMOTE> because the connector obtains this information from the InterChange Server repository.

When the integration broker is WMQI or WAS, this value must be set to <local directory>.

ResponseQueue

Designates the JMS response queue, which delivers a response message from the connector framework to the integration broker. When the integration broker is IICS, the server sends the request and waits for a response message in the JMS response queue.

RestartCount

Causes the connector to shut down and restart automatically after it has processed a set number of events. You set the number of events in RestartCount. The connector must be in polling mode (set PollFrequency to "p") for this property to take effect.

Once the set number of events has passed through request processing, the connector is shut down and restarted the next time it polls.

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.

The default is 1.

RHF2MessageDomain

WebSphere MQ Integrator Broker only.

This property allows you to configure the value of the field domain name in the JMS header. When data is sent to WebSphere MQ Integrator Broker over JMS transport, the connector framework writes JMS header information, with a domain name and a fixed value of mrm. A configurable domain name enables users to track how WebSphere MQ Integrator Broker processes the message data.

A sample header would look like this:

<mcd><Msd>mrm</Msd<Set>3</Set><Type>
 Retek_POPhyDesc</Type><Fmt>CwXML</Fmt></mcd>

The default value is mrm, but it may also be set to xml. This property only appears when DeliveryTransport is set to JMS and WireFormat is set to CwXML.

SourceQueue

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

SynchronousRequestQueue

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.

SynchronousResponseQueue

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.

SynchronousRequestTimeout

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

Message format on the transport.

WisfSynchronousRequest Timeout

WAS integration broker only.

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.

Appendix B. Connector Configurator

This appendix describes how to use Connector Configurator to set configuration property values for your adapter.

You use Connector Configurator to:

Note: In this document, backslashes (\) are used as the convention for directory paths. For UNIX installations, substitute slashes (/) for backslashes and follow the conventions for each operating system.

Overview of Connector Configurator

Connector Configurator allows you to configure the connector component of your adapter for use with these integration brokers:

The mode in which you run Connector Configurator, and the configuration file type you use, may differ according to which integration broker you are running. For example, if WMQI is your broker, you run Connector Configurator directly, and not from within System Manager.

Each time you install a new adapter, you need to set up a configuration file for the connector. This file:

You use Connector Configurator to create this configuration file and to modify its settings.

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 or technology).

Because standard properties are used by all connectors, you do not need to define those properties from scratch; Connector Configurator incorporates them into your configuration file as soon as you create the file. However, you do need to set the value of each standard property in Connector Configurator.

The range of standard properties may not be the same for all brokers and all configurations. Some properties are available only if other properties are given a specific value. The Standard Properties window in Connector Configurator will show the properties available for your particular configuration.

For connector-specific properties, however, you need first to define the properties and then set their values. You do this by creating a connector-specific property template for your particular adapter. There may already be a template set up in your system, in which case, you simply use that. If not, follow the steps in Creating a new template to set up a new one.

Note: Connector Configurator runs only in a Windows environment. If you are running the connector in a UNIX environment, use Connector Configurator in Windows to modify the configuration file and then copy the file to your UNIX environment.

Starting Connector Configurator

You can start and run Connector Configurator in either of two modes:

Running Configurator in stand-alone mode

You can run Connector Configurator independently and work with connector configuration files, irrespective of your broker. However, if WMQI is your integration broker, you can only use Connector Configurator in stand-alone mode.

To do so:

If you are creating a configuration file for use with WAS as the broker, you may prefer to run Connector Configurator independently to generate the file, and then connect to System Manager to save it in a System Manager project (see Completing a configuration file.)

Running Configurator from System Manager

If WAS is your integration broker, you can run Connector Configurator from System Manager.

To run Connector Configurator:

  1. Open the System Manager.
  2. In the System Manager window, expand the Integration Component Libraries icon and highlight Connectors.
  3. From the System Manager menu bar, click Tools>Connector Configurator. The Connector Configurator window opens and displays a New Connector dialog box.
  4. When you click the pull-down menu next to System Connectivity: Integration Broker, you can select ICS Connectivity or WAS Connectivity, depending on your broker.

To edit an existing configuration file:

  1. In the System Manager window, select any of the configuration files listed in the Connector folder and right-click on it. Connector Configurator opens and displays the configuration file with the integration broker type and file name at the top.
  2. Click the Standard Properties tab to see which properties are included in this configuration file.

Creating a connector-specific property template

To create a configuration file for your connector, you need a connector-specific property template as well as the system-supplied standard properties.

You can create a brand-new template for the connector-specific properties of your connector, or you can use an existing file as the template.

Creating a new template

This section describes how you create properties in the template, define general characteristics and values for those properties, and specify any dependencies between the properties. Then you save the template and use it as the base for creating a new connector configuration file.

To create a template:

  1. Click File>New>Connector-Specific Property Template.
  2. The Connector-Specific Property Template dialog box appears, with the following fields:
  3. Select a template from the Template Name display, enter that template name in the Find Name field (or highlight your selection in Template Name), and click Next.

If you do not see any template that displays the connector-specific properties used by your connector, you will need to create one. Connector Configurator provides a template named None, containing no property definitions, as a default choice.

Specifying general characteristics

When you click Next to select a template, the Properties - Connector-Specific Property Template dialog box appears. The dialog box has tabs for General characteristics of the defined properties and for Value restrictions. The General display has the following fields:

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

Specifying values

The Value tab enables you to set the maximum length, the maximum multiple values, a default value, or a value range for the property. To do so:

  1. Click 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 changes. The changes will not be accepted unless you also open the Property Value dialog box for the property, described in the next step.
  4. Right-click the box in the left-hand corner of the adapter display panel. A Property Value dialog box appears. Depending on the property type, the dialog box allows you to enter either a value, or both a value and range. Enter the appropriate value or range, and click OK.
  5. The Value panel refreshes to display any changes you made in Max Length and Max Multiple Values. It displays a table with three columns:

The Value column shows the value that you entered in the Property Value dialog box, and any previous values that you created.

The Default Value column allows you to designate any of the values as the default.

The Value Range shows the range that you entered in the Property Value dialog box.

After a value has been created and appears in the grid, it can be edited from within 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 the Value field and click Edit Value.

Setting dependencies

When you have made your changes to the General and Value tabs, click Next. The Dependencies dialog box appears.

A dependent property is a property that is included in the template and used in the configuration file only if the value of another property meets a specific condition. For example, PollQuantity appears in the template only if JMS is the transport mechanism and DuplicateEventElimination is set to True.
To designate a property as dependent and to set the condition upon which 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, select 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 the dependent 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 entered as an XML document, under \data\app in the\bin directory where you have installed Connector Configurator.

Creating a new configuration file

When you create a new configuration file, your first step is to select an integration broker. The broker you select determines the properties that will appear in the configuration file.

To select a broker:

To create a new file for WAS, you can also do this:

Creating a configuration file from a connector-specific template

Once a connector-specific template has been created, you can use it to create a configuration file:

  1. Click File>New>Connector Configuration.
  2. The New Connector dialog box appears, with the following fields:
  3. A configuration screen appears for the connector that you are configuring. The title bar shows the integration broker and connector names. You can fill in all the field values to complete the definition now, or you can save the file and complete the fields later.
  4. To save the file, click File>Save>to File or File>Save>Save to the project. To save to a project, you must be using ICS or WAS as the broker, and System Manager must be running.

    If you save as a file, the Save File Connector dialog box appears. Choose *.cfg as the file type, verify in the File Name field that the name is spelled correctly and has the correct case, navigate to the directory where you want to locate the file, and click Save. The status display in the message panel of Connector Configurator indicates that the configuration file was successfully created.

    Important
    : The directory path and name that you establish here must match the connector configuration file path and name that you supply in the startup file for the connector.
  5. To complete the connector definition, enter values in the fields for each of the tabs of the Connector Configurator window, as described later in this chapter.

Using an existing file

You may have an existing file available in one or more of the following formats:

Although any of these file sources may contain most or all of the connector-specific properties for your connector, the connector configuration file will not be complete until 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 in Connector Configurator, revise the configuration, and then save the file as a configuration file (*.cfg file).

Follow these steps to open a *.txt, *.cfg, or *.in file from a directory:

  1. In Connector Configurator, click File>Open>From File.
  2. In the Open File Connector dialog box, select one of the following file types to see the available files:
  3. In the directory display, navigate to the appropriate connector definition file, select it, and click Open.

Follow these steps to open a connector configuration from a System Manager project:

  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. Click File>Open>From Project.

Completing a configuration file

When you open a configuration file or a connector from a project, the Connector Configurator window displays the configuration screen, with the current attributes and values.

The title of the configuration screen displays the integration broker and connector name as specified in the file. Make sure you have the correct broker. If not, change the broker value before you configure the connector. 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 ICS, WMQI, or WAS.
  2. The Standard Properties tab will display the properties associated with the selected broker. You can save the file now or complete the remaining configuration fields, as described in Specifying supported business object definitions.
  3. When you have finished your configuration, click File>Save>To Project or File>Save>To File.

If you are saving to file, select *.cfg as the extension, select the correct location for the file and click Save.

If multiple connector configurations are open, click Save All to File to save all of the configurations to file, or click Save All to Project to save all connector configurations to a System Manager project.

Before it saves the file, Connector Configurator checks that values have been set for all required standard properties. If a required standard property is missing a value, Connector Configurator displays a message that the validation failed. You must supply a value for the property in order to save the configuration file.

Setting the configuration file properties

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

Connector Configurator requires values for properties in these categories for connectors running on all brokers:

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 or non-English character sets. However, the names of both standard and connector-specific properties, and the names of supported business objects, must use the English character set only.

Standard properties differ from connector-specific properties as follows:

The fields for Standard Properties and Connector-Specific Properties are color-coded to show which are configurable:

Setting standard connector properties

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 select one from the drop-down menu if it appears.
  3. After entering all the values for the standard properties, you can do one of the following:

Setting application-specific configuration properties

For application-specific configuration properties, you can add or change property names, configure values, delete a property, and encrypt a property. The default property length is 255 characters.

  1. Right-click in the top left portion of the grid. A pop-up menu bar will appear. Click Add to add a property or Add Child to add a child property to a property.
  2. Enter a value for the property or child property.
  3. To encrypt a property, select 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 or agent restart is necessary to activate changed values.

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

Encryption for connector properties

Application-specific properties can be encrypted by selecting the Encrypt check box in the Edit Property window. To decrypt a value, click to clear the Encrypt check box, enter the correct value in the Verification dialog box, and click OK. If the entered value is correct, the value is decrypted and displays.

The adapter user guide for each connector contains a list and description of each property and its default value.

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

Update method

Connector properties are almost all static and the Update Method is Component restart. For changes to take effect, you must restart the connector after saving the revised connector configuration file.

Specifying supported business object definitions

Use the Supported Business Objects tab in Connector Configurator to specify the business objects that the connector will use. You must specify both generic business objects and application-specific business objects, and you must specify associations for the maps between the business objects.

For you to specify a supported business object, the business objects and their maps must exist in the system.

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

If WMQI is your broker

The MQ message set files (*.set files) contain message set IDs that Connector Configurator requires for designating the connector's supported business objects. See Implementing Adapters with WebSphere MQ Integrator Broker for information about creating the MQ message set files.

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

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

To specify supported business objects:

  1. Select the Supported Business Objects tab and click Load. The Open Message Set ID File(s) dialog box 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. Click Open. The Business Object Name field displays the business object names contained in the *.set file. The numeric message set ID for each business object is listed in its corresponding Message Set ID field.
    Do not change the message set IDs. These names and numeric IDs are saved when you save the configuration file.
  4. When you add business objects to the configuration, you must load their message set files. If you attempt to load a message set that contains a business object name that already exists in the configuration, or if you attempt to load a message set file that contains a duplicate business object name, Connector Configurator detects the duplicate and displays the Load Results dialog box.
    The dialog box 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 select the Message Set ID that you wish to use.

If WAS is your broker

When WebSphere Application Server is selected as your broker type, Connector Configurator does not require message set IDs. The Supported Business Objects tab shows a Business Object Name column only for supported business objects.

If you are working in stand-alone mode (not connected to System Manager), you must enter the business object name manually.

If you have System Manager running, you can select the empty box under the Business Object Name column in the Supported Business Objects tab. A combo box appears with a list of the business objects available from the Integration Component Library project to which the connector belongs. Select the business object you want from this list.

Setting trace/log file values

When you open a connector configuration file or a connector definition file, Connector Configurator uses the logging and tracing values of that file as default values. You can change those values in Connector Configurator.

To change the logging and tracing values:

  1. Click the Trace/Log Files tab.
  2. For either logging or tracing, you can choose to write messages to one or both of the following:

Data handlers

The data handlers section is available for configuration only if you have designated a value of JMS for DeliveryTransport and a value of JMS for ContainerManagedEvents. Not all adapters make use of data handlers.

See the descriptions under ContainerManagedEvents in Appendix A, Standard Properties, for values to use for these properties. For additional details, see the Connector Development Guide for C++ or the Connector Development Guide for Java.

Saving your configuration file

When you have finished configuring your connector, you save the connector configuration file. Connector Configurator will save it in the broker mode that you selected during configuration. The title bar of Connector Configurator always displays the broker mode (ICS, WMQI or WAS) that it is currently using.

The file is saved as an XML document. You can save the XML document in three ways:

For WMQI:

For WAS:

After you have created the configuration file and set its properties, you need to deploy it to the correct location for your connector.

For details about using projects in System Manager, and for further information about deployment, see the following implementation guides:

Changing a configuration file

You can change the integration broker setting for an existing configuration file. This enables you to use the file as a template for creating a new configuration file, which can be used with a different broker.

Note: You will need to change other configuration properties as well as the broker mode property if you switch integration brokers.

To change your broker selection within an existing configuration file (optional):

  1. Open the existing configuration file in Connector Configurator.
  2. Select the Standard Properties tab.
  3. In the BrokerType field of the Standard Properties tab, select the value that is appropriate for your broker.
    When you change the current value, the available tabs and field selections on the properties screen will immediately change, to show only those tabs and fields that pertain to the new broker you have selected.

Completing the configuration

After you have created a configuration file for a connector and modified it, make sure that the connector can locate the configuration file when the connector starts up.

To do so, open the startup file used for the connector, and verify that the location and file name used for the connector configuration file match exactly the name you have given the file and the directory or path where you have placed it.

Using Connector Configurator in a globalized environment

Connector Configurator is globalized and can handle character conversion between the configuration file and the integration broker. Connector Configurator uses native encoding. When it writes to the configuration file, it uses UTF-8 encoding.

Connector Configurator supports non-English characters in:

The drop list for the CharacterEncoding and Locale standard configuration properties displays only a subset of supported values. To add other values to the drop list, you must manually modify the \Data\Std\stdConnProps.xml file in the product 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>

 

Appendix C: Connector feature list

Business object request handling features

The following table lists the business object request handling features supported by the connector

Business object request handling features
Category Feature Support Notes
Business object and attribute naming Business object names Full  
Attribute names Full  
Create Create verb Partial The connector interprets the Create verb as a test request to Spirent and sends the request to Spirent asynchronously .
This necessarily means creating objects in Spirent applications.
Delete Delete verb No  
Logical Delete No  
Exist Exist verb No  
Retrieve Retrieve verb No  
Ignore missing child object No  
RetrieveBy
Content
RetrieveBy
Content verb
No  
Multiple results No  
Ignore missing child object No  
Update After-image support No  
Delta support No  
KeepRelations No  
Verb support Subverb support No  
Verb stability Full  

Event notification features

The following table lists the event notification features supported by the connector

Event notification features
Category Feature Support Notes
Connector properties Event distribution No
PollQuantity Full
Event table Event status values Full
Object key No
Object name No
Priority No
Miscellaneous features Archiving Full
CDK method gotApplEvent() Full
Delta event notification No
Future event processing No
In-Progress event recovery Partial InDoubtEvents property is not supported. The connector will try to post all in-progress events to the integration broker when it starts up.
Physical delete event No
RetrieveAll No
SmartFiltering No
Verb stability Full

General features

The following table lists the general features supported by the connector

General request handling features
Category Feature Support Notes
Business object Foreign key No  
Foreign key attribute property No  
Key No  
Max Length No  
Required No  
Meta-data driven design No  
Loss of connection to application Connection lost on request processing Full  
Connection lost on polling N/A  
Connection lost while idle No The connector cannot detect it
Connector properties Application
Password
N/A Spirent does not require the user to log in to access APIs
Application
UserName
N/A Spirent does not require the user to log in to access APIs
UserDefaults connector property N/A  
Message tracing General messaging Full  
Trace Level 0 Full  
Trace Level 1 Full  
Trace Level 2 Full  
Trace Level 3 Partial  
Trace Level 4 Partial  
Trace Level 5 Partial  
Message tracing Full  
Miscellaneous features Java package names Full com.ibm.adapters.Spirent
Logging messages Full  
CDK method logMsg N/A  
NT service compliance Full  
Transaction support Full  
Special IBM WebSphere Business Interchange Server Values CxBlank processing Full CxBlank for Tag attribute of tag_and_value business object is not allowed. If specified, the tag_and_value business object is ignored.
CxIgnore processing Full  

Copyright IBM Corp. 1997, 2004