Configuring the connector

The Connector Configurator tool provides a graphical user interface for configuring the connector. When you are finished specifying values for the connector's configuration properties, the Connector Configurator generates a configuration file for the connector.

The connector configuration that you create through Connector Configurator is used as the source for the .wsdl file used in generating a Service Project for the interaction pattern in WebSphere Application Server, and it is also used as the local configuration file that is installed at the same location where the connector agent (also referred to as the adapter agent) is installed. When you have completed the steps for creating a configuration file, you will be able to both save the configuration as an Integration Component Libraries project in the System Manager perspective (so that it can be used in generating a *.wsdl file) and save the configuration as a file that can accompany the connector agent in the location where the agent is installed.

Important:
If the business integration adapter is running on UNIX, you must create the configuration file using Connector Configurator on Windows and then copy the file to your UNIX machine. When you create the configuration file, make sure that you observer UNIX path and file name conventions when setting properties.

Depending on the adapter product that you have purchased, you may already have a starting point for your connector configuration, either as a connector definition file in the directory ProductDir\connectors\repository\ConnName, or as a sample configuration file. You can open such files in Connector Configurator, and then revise them to create a complete configuration file for the connector. Note that while the connector definition file provides some starting values for the configuration file, a completed configuration file contains all the standard and application-specific properties for the connector, and specifies its supported business objects. Appendix B, Standard configuration properties for connectors, describes these properties in detail.

If no connector definition file or sample configuration file has been provided, you must create a new configuration file for that connector, using Connector Configurator.

The sections below discuss Connector Configurator settings that apply to every connector working with WebSphere Application Server.

Running Connector Configurator

Use Connector Configurator to create a new connector configuration, to revise an existing connector configuration that already has been saved to the System Manager integration component libraries, or to open an existing connector connector file that exists outside of System Manager.

Regardless of how you begin the process, in order to use the connector configuration with WebSphere Application Server as the integration broker, you must save the completed connector configuration to a project in the integration component libraries of System Manager.

To start and run Connector Configurator, do one of the following:

If you are creating a new connector configuration:

  1. Open the System Manager perspective.
  2. In the System Manager perspective, expand the Integration Component Libraries folder and select an existing Integration Component Library project folder. (If one does not already exist, you will need to create a new one. To create a new Integration Component Library project folder, select Integration Component Libraries, and right-click to open the New Integration Component Library dialog. Enter a project name for the new library project, and click Finish. The new library project appears as a folder within the top level Integration Component Libraries folder.) Expand the folder for the the Integration Component Library project that you are using, and select Connectors within it.
  3. From the System Manager menu bar, click Tools>Connector Configurator. The Connector Configurator window opens and displays a New Connector dialog box.
  4. Enter a name for the new connector configuration.
  5. Click the pull-down menu next to System Connectivity: Integration Broker, and select WAS.
  6. Select a template if one exists. If you do not have a template, choose None.
  7. Before you make any settings in the configuration file, click the Standard Properties tab and verify the following settings:

To edit an existing configuration that has been previously saved in System Manager:

  1. In the System Manager perspective, expand the Integration Component Libraries icon and highlight Connectors.
  2. Select a connector configuration listed in the Connector folder, right-click on it, and choose Edit Definition. Connector Configurator opens and displays the configuration for the connector, with the integration broker type and file name at the top.
  3. Before you make any settings in the configuration file, click the Standard Properties tab and verify the following settings:

To use an existing file to configure a connector, you must open the file in Connector Configurator, revise the configuration, and then save the configuration to the Integration Components Library in System Manager.

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, 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.
  4. Before you make any settings in the configuration file, click the Standard Properties tab and verify the following settings:

After you have opened Connector Configurator as described above, you can set the properties (includingthe properties that specify queues) and designate supported business objects, as described in this section. When you have completed the configuration, choose Save To Project.

Setting Standard and Connector-Specific properties

Configuration of a connector requires that you set values for both standard properties and connector-specific properties. For connector-specific properties, see the documentation for the specific adatper that you are using. For standard properties, seeAppendix B, "Standard configuration properties for connectors" later in this guide.

Note that the following property settings are mandatory for connectors that use WebSphere Application Server as the integration broker:

Designating supported business object

In order to designate business objects as supported by the connector, the business objects must first have been saved to projects in an Integration Components Library folder, as described in "Adding business objects to ICLs". The following instructions assume that you have already done that.

To designate existing supported business objects for the connector:

  1. Open the connector configuration in Connector Configurator. Choose the Supported Business Objects tab.
  2. The Business Object Name drop-down box will appear. Initially, if you have not yet designated any supported business objects for this connector configuration, the first visible field is blank. Click the drop-down arrow.
  3. A scroll list displays, showing all the business objects that are available to be designated as supported in this connector configuration. To be available, a business object must have previously been saved to the subfolder Business Objects in the same Integration Components Library project that contains the Connectors subfolder for this connector configuration.
  4. To designate one of the listed business objects as a supported business object for this connector configruation, click on it in the drop-down field. The business object name is added to the first field in the drop-down, and a new blank field is added. Repeat the process in the new blank field, continuing until you have added all the intended business object designations.
  5. When finished, choose File>Save to project. This saves your connector configuration as an Integration Component Library project, and an icon for it is displayed in the System Manager Perspective.

Specifying the queues to be used by the connector

In Creating the WebSphere MQ queues, you defined a set of queues to be used by the connector to communicate with WebSphere Application Server. In the Connector Configurator, click the Standard Properties tab and assign these queues to the connector by setting values for the following standard properties:

Setting the connection mode with the queue manager

The default connection mode is bindings mode. Specify client mode as follows:

  1. In the Connector Configurator, click the Standard Properties tab.
  2. Assign to the standard property, jms.MessageBrokerName, the following value: QueueMgrName:[Channel]:[HostName]:[PortNumber], where the variables represent the following:
    QueueMgrName
    The name of the queue manager.
    Channel
    The channel used by the client.
    HostName
    The name of the machine where the queue manager is to reside.
    PortNumber
    The port number to be used by the queue manager for listening.

For example:

 
jms.MessageBrokerName = WMQIB.Queue.Manager:CHANNEL1:RemoteMachine:1456

Configuring logging and tracing options

Logging is used to communicate system messages, component state changes, failures, and tracing information. The following files are generated:

Table 8. Connector logging and tracing files.

Default file name and path Description

Temporary log file:

ProductDir\broker_name_connector_name_tmp.log.

During startup, the connector generates a temporary log file. This file contains all messages that are logged during startup, including connector properties and business object definitions that are passed to the connector framework. and the file is written to the directory in which the product is installed.

Connector log file:

UNIX: A connector logs messages to STDOUT by default, then those messages are rerouted to ProductDir/logs/connector_manager_ConnName .log.

WINDOWS: A connector logs messages to STDOUT by default, but can be configured to send to a local destination log file in the ProductDir directory.

The connector's log file is used to store messages issued by the connector. It also contains messages regarding WebSphere MQ communication errors.

Connector message file:

ProductDir\connectors\messages\ConnName_LocaleName.txt

This file contains the full text for each message issued by the connector. You can use this file to look up the text of message IDs you see in the log file. If the locale specified in the connector configuration file is not supported, the file ConnName.txt is used.

Trace file:

Defaults to STDOUT for both UNIX and Windows.

Contains trace messages as specified by the selected trace level.

The logging system is always active and provides an accurate monitor of the connector.

To troubleshoot a problem, you can turn on tracing. Trace messages help you monitor actions taken in components of the business integration system. Trace levels define the amount of detail written to the trace file. The higher the trace level, the more detail you receive. Tracing differs from logging in the following ways:

Tracing is off by default because it produces messages that are more detailed than you normally need.

For information about viewing logging and tracing messages using LogViewer, see Using Log Viewer to view connector messages.

Configuring connector logging

To configure connector logging options, click the Trace/Log Files tab and specify the following:

  1. To have log messages routed to STDOUT, click the To console (STDOUT) check box.
  2. To have log messages routed to a file, click the To file check box and specify the full-path name of the log file you want to use. You can have log messages routed to the console and to a file by specifying both the "To console" and "To file" options.
  3. If you designated the use of a log file, also specify the following options:
    1. To limit the size of the log file, set Log file size to a numeric value and unit of measure.
    2. To permit the log file to grow with no limit, click the Unlimited check box.
    3. If you have set a maximum size for the log file and you want to use file archiving, set Number of archives to the number of archive files you want to maintain.

For more information about managing log files, see Managing log and trace files.

Configuring connector tracing

To configure connector tracing options:

  1. Click the Trace/Log Files tab.
  2. To have trace messages routed to STDOUT, check To console (STDOUT).
  3. To have trace messages routed to a file, check To file and specify the full-path name of the trace file you want to use. You can have trace messages routed to the console and to a file by specifying both the To console and To file options.
  4. If you designated the use of a trace file, also specify the following options:
    1. To limit the size of the trace file, set Trace file size to a numeric value and unit of measure.
    2. To permit the trace file to grow with no limit, check Unlimited.
    3. If you have set a maximum size for the trace file and you want to use file archiving, set Number of archivesto the number of archive files you want to maintain.
  5. To set the tracing level:
    1. Click the Standard Properties tab.
    2. Set the AgentTraceLevel property to one of the values listed in Table 9.

Refer to the adapter user guide for the connector you are configuring for more details about the information generated by the different trace levels for that connector. You can set connector tracing to one of the following levels:

Table 9. Connector trace levels.

Trace level Description
1 Traces initialization and the sending and receipt of business objects.
2 Prints messages for level 1. In addition, provides more details than Level 1 for the same types of events.
3 Prints messages for levels 1 and 2. In addition, traces the exchange of messages between the connector agent and the messaging driver.
4 Prints messages for levels 1 through 3. In addition, traces the passing of business objects between internal levels of the connector.
5 Prints messages for levels 1 through 4. In addition, traces the passing of administrative messages between internal levels of the connector.

A new or changed tracing level takes effect when you restart the connector.

For more information about archiving trace files, see Managing log and trace files.

Configuring the connector startup files, shortcuts, and environment variables

The procedure for starting a connector and the set-up tasks required both depend on the platform where the connector is running.

For Windows

When you install WebSphere Business Integration adapters on Windows, a shortcut is created for each installed connector on the WebSphere Business Integration Adapters program menu (Start > Programs > IBM WebSphere Business Integration Adapters > Adapters > Connectors). You must use the startup options listed in Appendix C, Connector startup options to customize the following:

For UNIX

In the UNIX environment, you start a connector by running connector_manager_connName script, which is a wrapper for the generic connector manager script (ProductDir/bin/connector_manager). This wrapper includes the following information:

If you have created a custom adapter or if you have installed an adapter using electronic software delivery (ESD), you need to do the following before you start up the connector for the first time:

  1. Run the Connector Script Generator tool to update the connector_manager_connName script with the name of the connector's configuration file. See Appendix D, Using the Connector Script Generator tool, for more information about running this tool.

    Alternatively, you can navigate to the ProductDir/bin directory and edit the connector_manager_connName file to specify the name of the connector's configuration file. In the file, locate the AGENTCONFIG_FILE variable and set it to the full-path name of the configuration file as follows:

    AGENTCONFIG_FILE=ConfigFile
     
    
  2. If desired, update your PATH environment variable to include the ProductDir/bin directory.
  3. Ensure that the CWSharedEnv.sh file is sourced from the shell startup script (such as .cshrc) for your account.
Customizing the startup script

The generic connector manager script calls the appropriate start_connector.sh script, which is the actual script that manages the particular connector. Each WebSphere Business Integration adapter includes a start_connector.sh script. You can modify the start_connector.sh script to include any of the supported startup options listed in Appendix C, Connector startup options.

Note:
For information about creating a startup files for connectors, see Connector Development Guide for C++ or Connector Development Guide for Java.

Copyright IBM Corp. 1997, 2003