This topic describes how to use Connector Configurator Express to set configuration property values for your adapter.
If you are configuring any of the following adapters, you may also want to refer to the Quick Start Guide:
A more recent version of the Quick Start Guide may be available at the following link: http://www.ibm.com/websphere/wbiitemsync/express/infocenter
You use Connector Configurator Express to:
The topics covered in this topic are:
Connector Configurator Express allows you to configure the connector component of your adapter for use with InterChange Server Express.
You use Connector Configurator Express to:
You use Connector Configurator Express 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).
The range of standard properties may not be the same for all configurations. Some properties are available only if other properties are given a specific value. The Standard Properties window in Connector Configurator Express will show the properties available for your particular configuration.
You can start and run Connector Configurator Express in either of two modes:
You can run Connector Configurator Express independently to work with connector configuration files. To do so:
If you are creating a configuration file, you may prefer to run Connector Configurator Express independently to generate the file, and then connect to System Manager to save it in an InterChange Server Express project (see "Completing a configuration file".)
You can also run Connector Configurator Express from System Manager.
To run Connector Configurator Express:
To create a configuration file for your connector, you first 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.
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. You then save the template and use it as the base for creating a new connector configuration file.
To create a template:
Enter a unique name that identifies the connector, or type of connector, for which this template will be used. You will see this name again when you open the dialog box for creating a new configuration file from a template.
The names of all currently available templates are displayed in the Template Name display.
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 Express Express provides a template named None, containing no property definitions, as a default choice.
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:
Use the buttons provided (or right-click within the Edit properties display) to add a new property to the template, to edit or delete an existing property, or to add a child property to an existing property.
A child property is an attribute of another property, the parent property. The parent property can obtain simple values, or child properties, or both. These property relationships are hierarchical. When you create a configuration file from these properties, Connector Configurator Express will identify hierarchical property sets with a plus sign in a box at the left of any parent property.
Choose one of these property types: Boolean, String, Integer, or Time.
You can set Standard Flags (IsRequired, IsDeprecated, IsOverridden) or Custom Flags (for Boolean operators) to apply to this property.
After you have made selections for the general characteristics of the property, click the Value tab.
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:
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.
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:
== (equal to)
!= (not equal to)
> (greater than)
< (less than)
>= (greater than or equal to)
<=(less than or equal to)
You create a connector configuration file from a connector-specific template or by modifying an existing configuration file.
Once a connector-specific template has been created, you can use it to create a connector configuration file:
Enter the name of the connector followed by the word connector . Names are case-sensitive. The name you enter must be unique and consistent with the file name for a connector that is installed on the system. For example, enter iSoftconnector if the connector file name is iSoft.
Type the name of the template that has been designed for your connector. The available templates are shown in the Template Name display. When you select a name in the Template Name display, the Property Template Preview display shows the connector-specific properties that have been defined in that template.
Select the template you want to use and click OK.
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 Express indicates that the configuration
file was successfully created.
To use an existing file to configure a connector, you must open the file in Connector Configurator Express, revise the configuration, and then save the file as a configuration file (*.cfg 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 topic.
Follow these steps to open a *.txt, *.cfg, or *.in file from a directory:
Choose this option if a repository file was used to configure the connector. A repository file may include multiple connector definitions, all of which will appear when you open the file.
Follow these steps to open a connector configuration from a System Manager project:
To edit an existing configuration file:
When you open a configuration file or a connector from a project, the Connector Configurator Express window displays the configuration screen, with the current attributes and values.
Connector Configurator Express requires values for properties described in the following sections:
The fields for Standard Properties and Connector-Specific Properties are color-coded to show which are configurable:
To change the value of a standard property:
For connector-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.
The Update Method displayed for each property indicates whether a component or agent restart is necessary to activate changed values.
Connector-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.
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.
Use the Supported Business Objects tab in Connector Configurator Express to specify the business objects that the connector will use. You must specify both generic business object definitions and application-specific business object definitions, 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. Business object definitions, including those for data handler meta-objects, and map definitions should be saved into ICL projects.
To specify that a business object definition is supported by the connector, or to change the support settings for an existing business object definition, click the Supported Business Objects tab and use the following fields.
To designate that a business object definition is supported by the connector, with System Manager running:
To delete a business object from the supported list:
Deleting a business object from the supported list changes the connector definition and makes the deleted business object unavailable for use in this implementation of this connector. It does not affect the connector code, nor does it remove the business object definition itself from System Manager.
If a business object has Agent Support, the system will attempt to use that business object for delivering data to an application via the connector. Typically, application-specific business objects for a connector are supported by that connector's agent, but generic business objects are not.
To indicate that the business object is supported by the connector agent, check the Agent Support box. The Connector Configurator Express window does not validate your Agent Support selections.
The maximum transaction level for a connector is the highest transaction level that the connector supports.
For most connectors, Best Effort is the only possible choice, because most application APIs do not support the Stringent level.
You must restart the server for changes in transaction level to take effect.
Each connector supports a list of business object definitions and their associated maps that are currently active in InterChange Server Express. This list appears when you select the Associated Maps tab.
The list of business objects contains the application-specific business object which the connector supports and the corresponding generic object that the controller sends to the subscribing collaboration. The association of a map determines which map will be used to transform the application-specific business object to the generic business object or the generic business object to the application-specific business object.
If you are using maps that are defined for specific source and destination business objects, the maps will already be associated with their business objects when you open the display, and you will not need to change them.
If more than one map is available for use by a supported business object, you will need to explicitly bind the business object with the map that it should use.
The Associated Maps tab displays the following fields:
These are the application-specific and generic business objects supported by this connector, as designated in the Supported Business Objects tab. If you designate additional business objects under the Supported Business Objects tab, they will be reflected in this list after you save the changes by choosing Save to Project from the File menu of the Connector Configurator Express window.
The display shows all the maps that have been installed to the system for use with the supported business objects of the connector. The source business object for each map is shown to the left of the map name, in the Business Object Name display. To display the maps, you must first designate the supported business objects, and then save the connector configuration to project. To see the maps, you must first designate the supported business objects and save the connector configuration to project.
In some cases, you may need to explicitly bind an associated map.
Explicit binding is required only when more than one map exists for a particular supported business object. When InterChange Server Express boots, it tries to automatically bind a map to each supported business object for each connector. If more than one map takes as its input the same business object, the server attempts to locate and bind one map that is the superset of the others.
If there is no map that is the superset of the others, the server will not be able to bind the business object to a single map, and you will need to set the binding explicitly.
To explicitly bind a map:
The messaging properties are available only if you have set MQ as the value of the DeliveryTransport. These properties affect how your connector will use queues.
When you open a connector configuration file, Connector Configurator Express uses the logging and tracing values of that file as default values. You can change those values in Connector Configurator Express.
To change the logging and tracing values:
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. Adapters that make use of the guaranteed event delivery enable this tab.
See the descriptions under ContainerManagedEvents in the standard properties section of your adapter guide for values to use for these properties.
After you have created the configuration file and set its properties, you need to deploy it to the correct location for your connector. Save the configuration in an ICL project, and use System Manager to load the file into InterChange Server Express.
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. For more information on the startup file, see the appropriate section of your adapter guide.