The JText adapter uses standard connector properties for configuration as detailed in the next section and connector-specific properties as detailed in the following section.
This section includes the following topics:
Connector Configurator allows you to configure the connector component of your adapter for use with these integration brokers:
You use Connector Configurator to:
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 (see Running Configurator in stand-alone mode).
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.
You can start and run Connector Configurator in either of two modes:
You can run Connector Configurator independently and work with connector configuration files, irrespective of your broker.
To do so:
You may choose 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.)
You can run Connector Configurator from System Manager.
To run Connector Configurator:
To edit an existing configuration file:
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 connector definition 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. Then you save the template and use it as the base for creating a new connector configuration file.
To create a template in Connector Configurator:
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.
The Value tab enables you to set the maximum length, the maximum multiple values, a default value, or a value range for the property. It also allows editable values. To do so:
To create a new property value:
The Value panel 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.
When you have made your changes to the General and Value tabs, click Next. The Dependencies - Connector-Specific Property Template 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)
When you create a new configuration file, you must name it and select an integration broker.
You also need to select an integration broker. The broker you select determines the properties that will appear in the configuration file. To select a broker:
Once a connector-specific template has been created, you can use it to create a configuration file:
Enter the name of the connector. Names are case-sensitive. The name you enter must be unique, and must be consistent with the file name for a connector that is installed on the system.
Click ICS or WebSphere Message Brokers or WAS.
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 indicates that the configuration file was successfully
created.
Once a connector-specific template has been created, you can use it to create a configuration file:
Enter the name of the connector. Names are case-sensitive. The name you enter must be unique, and must be consistent with the file name for a connector that is installed on the system.
Click ICS or WebSphere Message Brokers or WAS.
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 indicates that the configuration file was successfully
created.
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:
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.
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:
For connectors running on ICS, values for these properties are also required:
For connectors running on ICS, values for these properties are also required:
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:
Standard configuration properties provide information that all connectors use. See Appendix A, Standard configuration properties for connectors for documentation of these properties.
Table 5 provides information specific to this connector about configuration
properties in Appendix A.
Table 5. Property Information Specific to This Connector
Property | Note |
---|---|
CharacterEncoding | Because this connector is Java-based, it does not use this property. |
Locale | Because this connector has been internationalized, you can change the value of this property. See release notes for the connector to determine currently supported locales. |
To change the value of a standard property:
Connector-specific configuration properties provide information needed by the connector at runtime. They also provide a way of changing static information or logic within the connector without having to recode and rebuild the connector.
Table 6 lists the connector-specific configuration properties for the
connector. See the sections that follow for explanations of the
properties.
Table 6. Connector-specific configuration properties
Name | Possible values | Default value | Required? |
---|---|---|---|
ArchivingEnabled
| true or false |
true |
Yes |
EventLog
| Name and location of file |
event.log |
No |
EventRecovery
| abort or retry |
retry |
Yes |
FTPPollFrequency
| number of poll cycles |
No | |
GenerateTemplate
| BOName |
No | |
OutputLog
| File that registers the next sequence number for each incoming business object during request processing |
Output.Log |
No |
PollQuantity
| Number of events processed
at each poll |
25 |
No |
SortFilesOnTimestamp
| true or false | False | No |
Turns on archiving. If this property is set to true, the event file is archived in the archive directory with the specified extension. If this property is set to false, the event file is not archived. In this case, the connector deletes the file after sending all events to the integration broker. For more information, see Specifying event archiving.
The default value is true.
Provides file storage location for events that are generated by the connector. This file is located in the JText subdirectory in the connectors directory where the product is installed.
The default value is event.log.
Specifies recovery behavior. If this property is set to retry, the connector uses the event.log file to recover failed events. If this property is set to abort, the connector terminates when it encounters a failed event. For more information, see Event log file.
The default value is retry.
Determines how frequently the connector polls an FTP server measured in the number of standard poll cycles. For example, if PollFrequency standard configuration property is set to 10000, and FTPPollFrequency is set to 6, the connector polls the local event directory every 10 seconds and polls the remote directory every 60 seconds. The connector performs FTP polling only if you specify a value for this property. If FTPPollFrequency evaluates to 0 or blank, the connector does not perform FTP polling. By default it does not.
There is no default value for this property.
Enables the connector to generate a template for each supported business object after connector startup. The syntax for this property is BOName;BOName where the name of a specific business object is substituted for BOName. For example, to generate two templates, one for a Customer business object and one for an Item business object, specify Customer;Item. For more information, see Generating sample business objects for testing.
There is no default value for this property.
Specifies the name of the file that stores the sequence number that the connector uses to create unique output files for each type of business object during request processing. The format of the file is:
BusinessObjectName = NextSequenceNumber
where BusinessObjectName is the name of the request business object, and NextSequenceNumber represents the sequence number of the most recently received business object, incremented by one. For example, if the connector is processing Customer and Item business objects, the output log file might contain the following:
Customer = 12 Item = 2
This file indicates that the connector has already processed 11 Customers and 1 Item. The next Customer and Item business objects will be written to the Customer_12.out and Item_2.out files, respectively. When it receives a request Order business object, the connector adds a new row to the output log file and writes the business object to the Order_1.out file.
If FileSeqEnabled meta object is set to true, the connector uses this sequence number to uniquely name the output files that it creates for each business object. The connector names each output file by appending an underscore (_) and the sequence number to the business object's name or to a file whose name is specified in the OutputFileName meta-object attribute. Because the output log is stored in user-readable format, you can use a standard text editor to read the file or to reset its value.
For more information on the OutputFileName attribute, see Specifying the name of the output file. For more information about the output log, see Specifying request processing. For information on returning the generated file's name, see Returning a file's name.
The default is Output.Log.
Specifies the number of events to process for each poll. The connector poll method retrieves the specified number of event records and processes them in a single poll. Processing multiple events per poll can improve performance when the application generates large numbers of events. However, because integration-broker requests are blocked while the poll method is processing events, do not set the number of events too high. If each poll call takes a long time, it delays integration-broker request operations. For more information, see Tuning the performance of the JText connector.
The default value is 25.
Allows the adapter to pick up event files based on the timestamp. This property is ideally set to true when there are only a few huge event files picked up by the adapter during polling. When there are a lot of small event files, this value should be set to false in order to avoid the excess time taken to sort the files at each poll.
The default value is False.
Also, the JText adapter can poll remote files based on the timestamp from FTP
site only if the FTP server supports the mdtm (modification date
and time) command.
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.
The Update Method displayed for each property indicates whether a component or agent restart is necessary to activate changed values.
Application-specific properties can be encrypted by selecting the Encrypt check box in the Connector-specific Properties 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.
Refer to the descriptions of update methods found in the Standard configuration properties for connectors appendix, under Setting and updating property values.
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.
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 agent.
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 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.
You must restart the server for changes in transaction level to take effect.
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 object available from the Integration Component Library project to which the connector belongs. Select the business object you want from the list.
The Message Set ID is an optional field for WebSphere Business Integration Message Broker 5.0, and need not be unique if supplied. However, for WebSphere MQ Integrator and Integrator Broker 2.1, you must supply a unique ID.
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.
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.
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 agent.
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 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.
You must restart the server for changes in transaction level to take effect.
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 object available from the Integration Component Library project to which the connector belongs. Select the business object you want from the list.
The Message Set ID is an optional field for WebSphere Business Integration Message Broker 5.0, and need not be unique if supplied. However, for WebSphere MQ Integrator and Integrator Broker 2.1, you must supply a unique ID.
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.
The Resource tab allows you to set a value that determines whether and to what extent the connector agent will handle multiple processes concurrently, using connector agent parallelism.
Not all connectors support this feature. If you are running a connector agent that was designed in Java to be multi-threaded, you are advised not to use this feature, since it is usually more efficient to use multiple threads than multiple processes.
The messaging properties are available only if you have set MQ as the value of the DeliveryTransport standard property and ICS as the broker type. These properties affect how your connector will use queues.
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:
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.
When you have finished configuring your connector, save the connector configuration file. Connector Configurator saves the file 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 details about using projects in System Manager, and for further information about deployment, see the following implementation guides:
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.
To change your broker selection within an existing configuration file (optional):
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.
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>
A connector must be explicitly started using its connector start-up script. The startup script should reside in the connector's runtime directory:
ProductDir\connectors\connName
where connName identifies the connector. The name of
the startup script depends on the operating-system platform, as Table 7 shows.
Table 7. Startup scripts for a connector
Operating system | Startup script |
---|---|
UNIX-based systems | connector_manager_connName |
Windows | start_connName.bat |
You can invoke the connector startup script in any of the following ways:
Select Programs>IBM WebSphere Business Integration Adapters>Adapters>Connectors. By default, the program name is "IBM WebSphere Business Integration Adapters". However, it can be customized. Alternatively, you can create a desktop shortcut to your connector.
start_connName connName brokerName [-cconfigFile ]
connector_manager_connName -start
where connName is the name of the connector and brokerName identifies your integration broker, as follows:
You can load, activate, deactivate, pause, shutdown or delete a connector using this tool.
You can load, activate, deactivate, pause, shutdown or delete a connector using this tool.
For more information on how to start a connector, including the command-line startup options, refer to one of the following documents:
The way to stop a connector depends on the way that the connector was started, as follows:
connector_manager_connName -stop
where connName is the name of the connector.
You can load, activate, deactivate, pause, shutdown or delete a connector using this tool.
You can load, activate, deactivate, pause, shutdown or delete a connector using this tool.