Adapter for NightFire Applications

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

This adapter includes the following elements:

This manual provides information about using this adapter with both 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 NightFire 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 MQ Integrator Broker or WebSphere Application Server to communicate with NightFire version 4.0 through the exchange of business objects.

NightFire is a set of software programs for automating the traditionally manual telecommunications service preordering and ordering processes. The connector communicates with the following NightFire applications via NightFire Platform:

The communications between the connector and NightFire Platform are established using XML over CORBA. The connector sends the requests to an interface of NightFire called Request Router. After the requests are processed, NightFire sends back the responses and notifications.

Connector components

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

Diagram showing the relationship of the connector with NightFire application and Integration broker

Connector

The connector, which is written in Java, complies with the IBM business integration standards for adapters. The connector receives the request for NightFire from the integration broker and sends the request to NightFire via the Request Router. The connector is notified of the response by NightFire, generates the business object corresponding with the response, and then sends the business object to the integration broker. It 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(R), Oracle, and Microsoft SQLServer. Both of the tables have the schema shown in the following table:

Event and archive table schema
Column DB2 type  Oracle type MS SQLServer type Description
event_id varchar(16) varchar(16) varchar(16) Unique ID. Used as primary key.
event_priority integer integer integer For future enhancement. Currently always set to 1.
event_time timestamp date datetime Time when NightFire issues the event
event_processed timestamp date datetime Time when the connector processes the event
event_status integer integer integer Event status as defined by IBM WebSphere Business Integration Adapter framework
event_xml clob(10000) long text Messages in the form of XML strings that are sent from NightFire

Event mapping files

The connector uses the following files for mapping from the NightFire XML object to the business object, when the connector handles the response sent from NightFire as an event.

How the connector works

This section describes how the connector interacts with the NightFire application, and how it processes business object requests and event notifications.

Interacting with the NightFire application

At startup, the connector obtains a reference to a remote object of NightFire Request Router. VisiBroker's SmartAgent (osagent) retrieves the remote object. The connector sends requests to NightFire by invoking the Request Router APIs. In order to receive asynchronous responses, the connector registers as a listener to the Reliable Event Service.

If an error occurs within the connector or during its online processing within the NightFire application, 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 supports only 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 request to NightFire, the connector converts the contents of the business object into an XML string which it passes to NightFire via a method provided by the Request Router interface.

Processing Create requests

When the integration broker sends a business object request with the Create verb, the connector checks AppSpecificInfo in the top-level business object. AppSpecificInfo should have one of the following values:

According to the value specified in AppSpecificInfo, the connector invokes the corresponding Request Router API of NightFire:

When the connector invokes the processSync method, NightFire processes the request synchronously and returns the response. When the connector invokes the processAsync method, NightFire processes the request asynchronously and returns the response as an asynchronous event later.

Processing application events

The NightFire connector only receives responses to asynchronous requests from the event notification mechanism. Synchronous requests are returned in the request process explained above.

Event publication

To publish response events to the connector, the NightFire application 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 NightFire are returned to the connector as published events.

To register the connector as a listener, the register(PushConsumerCallBack pccb) method of Event Service is used. Responses are returned using the processEvent(String event) method of the listener implementation. The connector stores the events it receives in the event store table.

Event polling

The connector polls the event table at a regular, configurable interval. It searches for events by event_time order, 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.

Event archiving

The connector archives the events that it processes in the event polling operation. These events are added to the archive table.

Installing and configuring the connector

This section contains the installation and configuration information specific to the connector for NightFire. For general information on installing and configuring the product if the integration broker is WebSphere MQ Integrator Broker, refer to the following document:

Prerequisites

Before you use the IBM WebSphere Business Integration Adapter for NightFire 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 NightFire related files:

Note: If you use the connector with the WebSphere Business Integration Adapter 2.0 environment, you need to install the WebSphere Business Integration Adapter Runtime library 1.2.3 FixPack, available on the IBM support download site http://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 NightFire 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\NightFire, for example.
  5. Run the following commands:
    repos_copy -iMO_NightFire.txt -s Server_name -u User_name -p Password
    repos_copy -iCN_NightFire.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 NightFire 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 NightFire 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/NightFire
CWNightFire.jar: contains a program of this connector implemented by Java

start_NightFire.sh: the startup script for the connector. The script is called from the generic connector manager script.
connectors/NightFire/dependencies
event_table_xxx.sql: contains sql statements required to create the event and archive tables in the database

ElementToDTD.txt and DTDToBOName.txt: used to handle NightFire events
connectors/messages
NightFireConnector.txt and NightFireConnector_en_US.txt: connector message files
connectors/NightFire/Samples
xxx.in: sample application-specific business object (ASBO)

NightFireAgentConfig.cfg: sample configuration file in case of the integration broker is InterChange Server.
repository/NightFire
CN_NightFire.txt: connector definition file

MO_NightFire.txt: meta object 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 connector for NightFire.

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\NightFire
CWNightFire.jar: contains a program of this connector implemented by Java

start_NightFire.bat: the startup script for the connector
connectors\NightFire\dependencies
event_table_xxx.sql: contains sql statements required to create the event and archive tables in the database

ElementToDTD.txt and DTDToBOName.txt: used to handle NightFire events.
connectors\messages
NightFireConnector.txt and NightFireConnector_en_US.txt: connector message files
connectors\NightFire\Samples
xxx.in: sample application-specific business object (ASBO)

NightFireAgentConfig.cfg: sample configuration file in case of the integration broker is InterChange Server.
repository\NightFire
CN_NightFire.txt: connector definition file

MO_NightFire.txt: meta object definition file

Configuring the properties in the NightFire server

The port number of the NightFire’s Naming Service should be set into the the connector specific property “NFORBInitialPort”. The following procedure describes how to check the port number:

  1. Login to the NightFire server machine.
  2. Change the current directory to the installed directory of the NightFire server.
  3. View the contents of the “ns.ior” file with the VisiBroker’s tool “printIOR” program. Refer to the VisiBroker’s manual for instructions on how to use the program.
  4. You should see the port number of the Naming Service.

Creating the event and archive tables in the database

The connector uses event and archive tables for event notification and to archive the result. Databases section describes schemas of both of these 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\NightFire\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

NightFire API jar file

The IDL file “RequestHandler.idl” that is needed to create the NightFire API jar file has been installed into the NightFire server machine. You will need to create and place the Nightfire API jar file into the appropriate directory with the following procedure for Windows.

  1. Install the IBM Developer Kit for Windows, Java 2 Technology Edition Version 1.3.1. You can use the utility “idlj.exe".
  2. Create a work directory and copy the .idl file into it.
  3. Copy the .idl file “RequestHandler.idl” from the NightFire server machine in the directory /idl.
  4. At the command prompt, type the following commands:

    Idlj –emitAll –fallTIE *.idl

    javac com\nightfire\idl\RequestHandlerPackage\*.java com\nightfire\idl\*.java

  5. jar -cvf nforb.jar .\com\nightfire\idl\*.class .\com\nightfire\idl\RequestHandlerPackage\*.class

  6. Copy the nforb.jar into the connectors\NightFire\dependencies directory.
  7. Copy the nfcommon.jar file from NightFire installed machine into the connectors\NightFire\dependencies directory.

NightFire DTD files

Copy the NightFire DTD files that are used to generate business objects into the connectors\NightFire\dependencies directory. All the DTD files are available on NightFire's website at http://extranet.nightfire.com/.

JDBC driver

Copy the following JDBC driver file(s) into the connectors\NightFire\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 January 2003.

IBM DB2

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

Oracle Database Server

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

Event mapping files

The connector requires event mapping files to handle the NightFire response which is asynchronously sent from NightFire as an event. These files are used to create the business object corresponding to the response contained by the event in XML format.

The file names for these maps are specified in the configurable connector-specific properties. The files specified by default, ElementToDTD.txt and DTDToBOName.txt, contain sample data. These files are installed by the installer. You can modify these files to suit the business objects you use.

Modifing ElementToDTD.txt file

The connector uses ElementToDTD.txt to parse the NightFire XML response, and get the list of DTD file names that match with the NightFire XML response. ElementToDTD.txt is a property-format text file.

To modify this file, change the content of each line so that it appears as follows:

where:

Example:

The following excerpt is an example of a NightFire XML response. It is an LSR order response for Southwestern Bell.

<?xml version=" .... "?>
 <Response>
     <lsr_order_response>
         ...
         ...
     </lsr_order_response>
     <SupplierLSROrderResponse>
         ...
         ...
     </SupplierLSROrderResponse>
 </Response>

If you want to use generic5_lsr_response.dtd to parse the <lsr_order_response> ... </lsr_order_response> portion of this response,  and SWBT_lsr_response.dtd to parse the <SupplierLSROrderResponse> ... </SupplierLSROrderResponse> portion , insert the following lines in ElementToDTD.txt:

lsr_order_response=generic5_lsr_response.dtd
 SupplierLSROrderResponse=SWBT_lsr_response.dtd
Modifing DTDToBOName.txt file

After parsing the NightFire XML response using ElementToDTD.txt, the connector uses DTDToBOName.txt to determine the name of the business object corresponding to the list of DTD files. DTDToBOName.txt is a property-format text file.

To add or modify a line in this file, use the following syntax:

   dtdFileName[,dtdFileName2, ...]=businessObjectName

where dtdFileName is the name of the DTD file used to create the business object, and businessObjectName is the name of the business object created by the DTD file(s). The connector creates a new business object using the name, and populates the business object with the NightFire XML response. If the business object is created by two or more DTD files, use dtdFileName2 and its followers (separated by commas).

The DTD files are available on NightFire's website: http://extranet.nightfire.com/.

Example:

This example is for the LSR order response for Southwestern Bell.

To map the NightFire XML response to the NightFire_LSR_SWBT_Response business object, when generic5_lsr_response.dtd and SWBT_lsr_response.dtd are matched with the XML response, add the following line to DTDToBOName.txt.

generic5_lsr_response.dtd,SWBT_lsr_response.dtd=NightFire_LSR_SWBT_Response

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
CWNFArch
Yes
DataBasePassword Database password
admin
Yes
DataBaseURL URL string
jdbc:microsoft:
 sqlserver://
 your_host:1433
Yes
DataBaseUserName Database user name
crossworlds
Yes
DataHandlerMeta
ObjectName
Meta object name
MO_DataHandler_
 Nightfire
Yes
DTDToBOName File name
DTDToBOName.txt
Yes
ElementToDTD File name
ElementToDTD.txt
Yes
EventStoreTable Database table name
CWNFEvnt
Yes
JDBCDriver JDBC driver name
com.microsoft.
 jdbc.sqlserver.
 SQLServerDriver
Yes
MaxStored
ResponseID
Integer (1 or greater)
150
No
NFEventChannel Registered name in the Naming Service
NightFire.SPI.
 EventChannel
Yes
NFORBInitialHost IP address or host name of the Naming Service server
(none)
Yes
NFORBInitialPort Naming Service port number
(none)
Yes
NFSVCnameroot Naming Service instance name
Nightfire
Yes
PollQuantity Integer; 1 or more
1
No

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 strings, depending on your database:

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.

DTDToBOName

This property specifies the name of the event mapping file. See Event mapping files for details.

ElementToDTD

This property specifies the name of the event mapping file. See Event mapping files for details.

EventStoreTable

This property specifies the name of the database table used to store events received from NightFire.

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:

MaxStoredResponseID

This property specifies the maximum number of response_tag and response_bo pairs that are stored in the memory (non-persistent storage). The connector gets this information from the application-specific information at the business object level and stores it in the memory. See Application-specific information at the business object level for more details.

NFEventChannel

This property specifies the event channel name used by NightFire's Reliable Event Service. The connector can get events from NightFire through the channel. The channel that is normally used is NightFire.SPI.EventChannel.

NFORBInitialHost

This property specifies the IP address or host name of the host running VisiBroker's Naming Service. You should specify this property if the machine where NightFire is installed is located out of the subnet to which the connector installed machine belongs.

NFORBInitialPort

This property specifies the port number of VisiBroker's Naming Service. You should specify this property to the same value which is specified to the property key of the NightFire Console’s Property Editor.

NFSVCnameroot

This property specifies an instance of the Naming Service. The connector gets the root context from the specified Naming Service, then communicates to the NightFire application. The value normally specified for this property is Nightfire.

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_NightFire 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_NightFire.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 existing arguments. Do not remove the existing arguments.

Creating or modifying business objects

The connector component of the IBM WebSphere Business Integration Adapter for NightFire Applications is driven by meta-data. Meta-data, in the IBM WebSphere business integration environment, is application-specific data that is stored in WebSphere business objects and that assists the connector in its interaction with the application. A meta-data-driven connector handles each business object that it supports based on meta-data encoded in the business object definition rather than on instructions that are hard coded in the connector.

Business object meta-data includes the structure of a business object, the settings of its attribute properties, and the content of its application-specific information. Because the connector is driven by meta-data, it can handle new or modified business objects without requiring modifications to the connector code.

The connector 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, for example "NightFire_" or "NF_", when you name a business object to represent data for NightFire. Follow this convention for all child business objects as well as for the top-level business object. For example, the LSR request business object name for Southwestern Bell would be NightFire_LSR_SWBT_Request.

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:

For more information on the AppSpecificInfo of the top_level_business_object, see Application-specific information at the business object level.

Top-level business object structure examples

Creating a business object

This section describes how to create business objects from the NightFire DTD files.

You can use the XMLBORGEN or XMLODA utility to create business objects from NightFire DTD files, depending on the product and its version. The XMLBORGEN utility is available in the InterChange Server 4.1.1 or former, and the WebSphere Business Integration Adapters 2.0. The XMLODA utility is available in the WebSphere Business Integration Adapters 2.1 or later.

Getting the name of the root element in DTD file

You need to get the name of the root element. Refer to the following sections in the NightFire product documentation for information on how to get the name of the root element:

The sections above include the tables that describe the elements for each NightFire DTD. You can find the name of root element in the "Root Element" or "Element" column in the table.

Using XMLBORGEN utility to create business object definitions

The XMLBORGEN utility is included in the DevelopmentKits\edk\Utilities\xmlborgen directory.

To run XMLBORGEN, type the following command in a command prompt:

   xmlborgen -iinput_file -ooutput_file -pprefix -vverblist -nobject_name

Where input_file specifies the name of the DTD file and its path, output_file specifies the name and location where the generated business object definition will be stored, prefix specifies the prefix for the name of generated business objects (such as NightFire or NF), verblist specifies the list of verbs to be included in generated business objects (the recommended value is Create, because the NightFire connector only supports the Create verb), and object_name specifies the name of the root element in the input_file.

Notes: The DTD files are available on NightFire's website: http://extranet.nightfire.com/. Some DTDs have two or more root elements. In this case, you must run XMLBORGEN for each root element.

For general information about using the XMLBORGEN utility, refer to the Data Handler Guide.

Using XMLODA utility to create business object definitions

The XMLODA utility is included in the ODA\XML directory.

  1. Start the XMLODA by clicking Start > Programs > WebSphere Business Integration Adapters > Adapters > Object Discovery Agent > XML Object Discovery Agent
  2. Start the Business Object Designer and access to the XMLODA.
    1. Start the Business Object Wizard by clicking File > New Using ODA in the Business Object Designer menu bar.
    2. In the Select Agent dialog box, click Find Agents then select XMLODA
    3. In the Configure Agent dialog box, specify the following values.
      • FileName = input_file
      • Root = object_name
      • BOPrefix = prefix

      Where input_file specifies the name of the DTD file and its path, object_name specifies the name of the root element in the input_file, and prefix specifies the prefix for the name of generated business objects (such as NightFire or NF).

    4. In the Select Source dialog box, verify the BO structure then click Next
    5. In the Confirm source nodes for business objects dialog box, click Next
    6. In the BO Properties dialog box, specify Create for Verbs property
    7. In the Save business objects dialog box, select Open the new BOs in separate windows.
    8.  In the Business Object Designer window, select one or more of the attributes of the business object as the key attribute.
      • If an attribute is likely to have unique values, select that attribute as the key.
      • Otherwise, select the first attribute as the key.
    9. Save the BO definitions.

Notes: The DTD files are available on NightFire's website: http://extranet.nightfire.com/. Some DTDs have two or more root elements. In this case, you must run XMLODA for each root element.

For general information on accessing an ODA using the Business Object Designer, refer to the Data Handler Guide.

Loading the business object to the integration broker.

For instructions on loading the business object, refer to the Adapter for WebSphere MQ Integrator Broker User Guide

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 business object with the Create verb specified

  1. Gets the request handler name from the request_handler parameter in the AppSpecificInfo of the top-level business object.
  2. Determines which method is used to send a request to NightFire, based on the request_method parameter in the AppSpecificInfo of the top-level business object.
  3. Extracts the Header business object, the Request business object, and the Response business object (only in case of requestSync) from the top-level business object.
  4. Converts each business object to the NightFire XML object.
  5. Calls the method of the request handler using the NightFire XML objects as arguments.

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 If the business object is the top-level object, the application-specific information contains the instruction for the connector. You should specify this information manually. See Application-specific information at the business object level for details.

If the business object is a child business object, it contains mapping information. See Note below.
Simple attributes Contains mapping information. See Note below.
Attributes that contain a child or an array of child business objects Contains mapping information. See Note below.
Business object verb The connector does not support this.

Note: Mapping information describes the relationship between the business object and the NightFire XML object (such as a request or response). This information is automatically specified when you generate the business object from the NightFire DTD file using XMLBORGEN utility.

The following sections discuss this functionality in more detail.

Application-specific information at the business object level

This section describes the application-specific information at the top-level business object. The format of this information is a sequence of "name=value" strings, separated by semicolons. The following table shows the possible name and value pairs.

 Application-specific information at the top-level business object
Name Value Required for async request Required for async response Required for sync request response
request_handler The request handler name which is registered in the Naming Service. The connector sends a request to NightFire using this request handler. Normally, Nightfire.Router is used. Yes No Yes
request_method Either of the following values. The supported method depends on a service provider
  • processAsync
  • processSync
Yes (processAsync should be specified) No Yes (processSync should be specified)
response_tag The XML element name that is used to correlate the request and its corresponding response. For example, the element INQNUM is used for the NightFire LSR Preorder. Optional No No
response_bo The possible business object name for the asynchronous response corresponding to the asynchronous request. Two or more names can be set (using a comma as a separator). Optional No No

The connector uses the information in response_tag and response_bo to determine the business object name for an asynchronous response from NightFire.

The value of response_tag is the name of the XML element that serves as a correlation id between the request and response business objects. When the connector receives an asynchronous request, it gets the values of response_bo and response_tag, as well as the correlation id value specified in the response_tag element, and stores these three values in the memory. When the connector receives an asynchronous response from NightFire, it finds the response_tag element in the response and compares its value to the response_tag element with the same name that is stored in memory. If the correlation id values match, the connector creates the business object using the corresponding response_bo.

The connector stores response_tag/correlation id/response_bo sets up to the number specified in the MaxStoredResponseID property. The connector only uses this information when the connector fails to determine the business object using information in the ElementToDTD and DTDToBOName file. This information will be lost when the connector is down.

The following is an example of the application-specific information at the top-level business object for the asynchronous request

 request_handler=Nightfire.Router;request_method=requestAsync;response_tag=INQNUM;
   response_bo=NightFire_Response1,NightFire_Response2

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.

NightFire 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 Records log messages.
Records each time the pollForEvents method is executed.
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.
Indicate each time an event from the application is received.
Level 3 Not supported.
Level 4 Record the application-specific information.
Records the connector specific processing.
Level 5 Records business object dumps.
Records raw XML strings.

Error messages

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

 31000
  Null verb encountered for business object {1}
  [EXPL]
  A null verb for the business object was encountered.
  31001
  Unsupported verb encountered for business object {1} with verb {2}
  [EXPL]
  The verb that was set in the business object is not supported by the connector. 

Loss of connection to the application

If the connector fails to establish a connection, it sends FAIL to the integration broker and terminates.

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

This appendix details the features supported by the connector. For descriptions of these features, see "Appendix A: Connector Feature Checklist" in the Connector Development Guide for Java.

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 request to NightFire and sends the request to NightFire either synchronously or asynchronously according to the AppSpecificInfo in a top-level business object.
Delete Delete verb No
Logical Delete No  
Exist Exist verb No  
Retrieve Retrieve verb No  
Ignore missing child object No  
RetrieveByContent RetrieveByContent 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 Partial Always set to 1
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 re-submit the events to the integration broker whenever it starts.
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 Full This connector is designed to process any business object defined in DTD files. Correspondences to the new business object and the new DTD file should be added in the DTDToBOName file and the ElementToDTD file.
Loss of connection to application Connection lost on request processing Partial The connector returns a status of FAIL
Connection lost on polling N/A  
Connection lost while idle No The connector cannot detect it
Connector properties ApplicationPassword N/A NightFire does not require the user to log in to access APIs
ApplicationUserName N/A NightFire 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 N/A  
Trace Level 4 Partial  
Trace Level 5 Partial  
Message tracing Full  
Miscellaneous features Java package names Full com.ibm.adapters.
NightFire
Logging messages Full  
CDK method logMsg N/A  
NT service compliance Full  
Transaction support Full  
Special IBM WebSphereICS values CxBlank processing Full  
  CxIgnore processing Full  

Copyright IBM Corp. 1997, 2004