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.
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.
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.
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.
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:
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 |
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.
This section describes how the connector interacts with the NightFire application, and how it processes business object requests and event notifications.
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.
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.
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.
The NightFire connector only receives responses to asynchronous requests from the event notification mechanism. Synchronous requests are returned in the request process explained above.
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.
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.
The connector archives the events that it processes in the event polling operation. These events are added to the archive table.
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:
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.
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/.
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:
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.
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.
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 |
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.
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 |
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:
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.
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:
where
SQL>@event_table_oracle
To configure event and archive processing, you must use configuration properties to specify the following information:
See Connector-specific properties for more details.
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.
Idlj –emitAll –fallTIE *.idl
javac com\nightfire\idl\RequestHandlerPackage\*.java com\nightfire\idl\*.java
jar -cvf nforb.jar .\com\nightfire\idl\*.class .\com\nightfire\idl\RequestHandlerPackage\*.class
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/.
Copy the following JDBC driver file(s) into the connectors\NightFire\dependencies directory (depending on which database you use):
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.
No action is required. The connector uses the DB2 driver installed with the IBM WebSphere Business Integration Adapter Framework.
classes12.zip, located in the directory where Oracle is installed
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.
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:
elementName=dtdFileName[,dtdFileName2, ...]
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
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
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 configuration properties provide information that all connectors use. See Standard configuration properties for documentation of these 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.
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 |
This property specifies the name of the database table that the connector uses to archive events that have been processed.
This property specifies the password for the database containing the event store and the archive table.
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.
This property specifies the user name for the database that has the event store and the archive table.
This property specifies the name of the event mapping file. See Event mapping files for details.
This property specifies the name of the event mapping file. See Event mapping files for details.
This property specifies the name of the database table used to store events received from NightFire.
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:
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.
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.
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.
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.
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.
This property specifies the number of events to retrieve during each polling for events.
This section describes the configuration information specific to the environment such as the integration broker and the platform you are using.
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:
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:
See Using the Connector Configuration Tool in Adapter for WebSphere MQ Integrator Broker User Guide for details on using the Connector Configuration Tool.
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:
-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.
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.
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.
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.
The top-level business objects that this connector uses have the following structures:
top_level_business_object | +-Header | | | +-XMLDeclaration (String) | +-DocType (String) | +-header_contents | +-Request | +-XMLDeclaration (String) +-DocType (String) +-request_contents
Notes:
top_level_business_object | +-XMLDeclaration (String) +-DocType (String) +-response_contents
Notes:
top_level_business_object | +-Header | | | +-XMLDeclaration (String) | +-DocType (String) | +-header_contents | +-Request | | | +-XMLDeclaration (String) | +-DocType (String) | +-request_contents | +-Response | +-XMLDeclaration (String) +-DocType (String) +-response_contents
Notes:
For more information on the AppSpecificInfo of the top_level_business_object, see Application-specific information at the business object level.
NightFire_LSR_SWBT_Request | +-Header (NightFire_header) | | | +-XMLDeclaration (String) | +-DocType (String) | +-ROOT (NightFire_ROOT_header) | +-Request (NightFire_LSR_SWBT_Request_Request) | +-XMLDeclaration (String) +-DocType (String) +-ROOT (NightFire_LSR_SWBT_Reuqest_Request_ROOT) | +-lsr_order (NightFire_LSR_SWBT_ROOT_lsr_order) +-SupplierLSROrderRequest (NightFire_LSR_SWBT_ROOT_SupplierLSROrderRequest)
Notes:
NightFire_LSR_SWBT_Response | +-XMLDeclaration (String) +-DocType (String) +-ROOT (NightFire_LSR_SWBT_Response_ROOT) | +-lsr_order_response (NightFire_LSR_SWBT_ROOT_lsr_order_response) +-SupplierLSROrderResponse (NightFire_LSR_SWBT_ROOT_SupplierLSROrderResponse)
Notes:
NightFire_SAGAV_SWBT | +-Header (NightFire_header) | | | +-XMLDeclaration (String) | +-DocType (String) | +-ROOT (NightFire_ROOT_header) | +-Request (NightFire_SAGAV_SWBT_lsr_preorder) | | | +-XMLDeclaration (String) | +-DocType (String) | +-ROOT (NightFire_SAGAV_SWBT_ROOT_lsr_preorder) | +-Response (NightFire_SAGAV_SWBT_lsr_preorder_response) | +-XMLDeclaration (String) +-DocType (String) +-ROOT (NightFire_SAGAV_SWBT_ROOT_lsr_preorder_response)
Notes:
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.
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.
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.
The XMLODA utility is included in the ODA\XML directory.
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).
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.
For instructions on loading the business object, refer to the Adapter for WebSphere MQ Integrator Broker User Guide
This section describes the following aspects of processing a business object's verbs:
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.
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.
The connector performs the following steps when it receives a business object with the Create verb specified
The connector does not support this verb. It returns a status of FAIL.
The connector does not support this verb. It returns a status of FAIL.
The connector does not support this verb. It returns a status of FAIL.
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.
Each business object attribute must have a unique name.
Each business object attribute must have a type, such as Integer, String, or the type of a child business object.
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).
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.
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.
If the attribute is of type String, this property specifies the maximum length allowed for the attribute's value.
For information on this property, see Business object application-specific information.
The connector does not support this property.
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.
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.
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.
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.
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
|
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
This section describes problems that you may encounter when running the connector.
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:
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.
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.
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.
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. |
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.
If the connector fails to establish a connection, it sends FAIL to the integration broker and terminates.
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.
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.
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.
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):
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.
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.
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 |
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 |
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 |
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 |
This section lists and defines each of the standard connector configuration properties.
The queue that is used by the integration broker to send administrative messages to the connector.
The default value is CONNECTORNAME/ADMININQUEUE.
The queue that is used by the connector to send administrative messages to the integration broker.
The default value is CONNECTORNAME/ADMINOUTQUEUE.
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.
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.
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.
Identifies the integration broker type that you are using. The options are ICS, WMQI or WAS.
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.
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.
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.
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.
WebSphere ICS only.
Level of trace messages for the connector controller. The default is 0.
The queue that is used by the connector to send business objects to the integration broker.
The default value is DELIVERYQUEUE.
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:
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=0x30000000This 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.
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.
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.
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.
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.
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.
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.
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.
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.
Specifies the password for the JMS provider. A value for this property is optional.
There is no default.
Specifies the user name for the JMS provider. A value for this property is optional.
There is no default.
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.
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
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.
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.
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.
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
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.
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.
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.
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.
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.
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.
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.
The queue that is used by the integration broker to send business objects to the connector.
The default value is REQUESTQUEUE.
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>.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Message format on the transport.
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.
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.
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.
You can start and run Connector Configurator in either of two modes:
You can run Connector Configurator independently and work with connector configuration files, irrespective of your broker. 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.)
If WAS is your integration broker, you can run Connector Configurator from System Manager.
To run Connector Configurator:
To edit an existing configuration file:
To create a configuration file for your connector, you need a connector-specific property template as well as the system-supplied standard properties.
You can create a brand-new template for the connector-specific properties of your connector, or you can use an existing 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:
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.
When you click Next to select a template, the Properties - Connector-Specific Property Template dialog box appears. The dialog box has tabs for General characteristics of the defined properties and for Value restrictions. The General display has the following fields:
After you have made selections for the general characteristics of the property, click the Value tab.
The Value tab enables you to set the maximum length, the maximum multiple values, a default value, or a value range for the property. To do so:
The Value column shows the value that you entered in the Property Value dialog box, and any previous values that you created.
The Default Value column allows you to designate any of the values as the default.
The Value Range shows the range that you entered in the Property Value dialog box.
After a value has been created and appears in the grid, it can be edited from within the table display. To make a change in an existing value in the table, select an entire row by clicking on the row number. Then right-click in the Value field and click Edit Value.
When you have made your changes to the General and Value tabs, click Next. The Dependencies dialog box appears.
A dependent property is a property that is included in the template and used
in the configuration file only if the value of another property meets a
specific condition. For example, PollQuantity appears in the template only if
JMS is the transport mechanism and DuplicateEventElimination is set to True.
To designate a property as dependent and to set the condition upon which it
depends, do this:
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:
Once a connector-specific template has been created, you can use it to create a configuration 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:
Follow these steps to open a connector configuration from a System Manager project:
Start System Manager. A configuration can be opened from or saved to System Manager only if System Manager has been started.
Start Connector Configurator.
Click File>Open>From Project.
When you open a configuration file or a connector from a project, the Connector Configurator window displays the configuration screen, with the current attributes and values.
The title of the configuration screen displays the integration broker and connector name as specified in the file. Make sure you have the correct broker. If not, change the broker value before you configure the connector. To do so:
If you are saving to file, select *.cfg as the extension, select the correct location for the file and click Save.
If multiple connector configurations are open, click Save All to File to save all of the configurations to file, or click Save All to Project to save all connector configurations to a System Manager project.
Before it saves the file, Connector Configurator checks that values have been set for all required standard properties. If a required standard property is missing a value, Connector Configurator displays a message that the validation failed. You must supply a value for the property in order to save the configuration file.
When you create and name a new connector configuration file, or when you open an existing connector configuration file, Connector Configurator displays a configuration screen with tabs for the categories of required configuration values.
Connector Configurator requires values for properties in these categories for connectors running on all brokers:
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:
To change the value of a standard property:
For application-specific configuration properties, you can add or change property names, configure values, delete a property, and encrypt a property. The default property length is 255 characters.
The Update Method displayed for each property indicates whether a component or agent restart is necessary to activate changed values.
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.
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.
Connector properties are almost all static and the Update Method is Component restart. For changes to take effect, you must restart the connector after saving the revised connector configuration file.
Use the Supported Business Objects tab in Connector Configurator 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.
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:
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.
When you open a connector configuration file or a connector definition file, Connector Configurator uses the logging and tracing values of that file as default values. You can change those values in Connector Configurator.
To change the logging and tracing values:
The data handlers section is available for configuration only if you have designated a value of JMS for DeliveryTransport and a value of JMS for ContainerManagedEvents. Not all adapters make use of data handlers.
See the descriptions under ContainerManagedEvents in Appendix A, Standard Properties, for values to use for these properties. For additional details, see the Connector Development Guide for C++ or the Connector Development Guide for Java.
When you have finished configuring your connector, 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:
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):
After you have created a configuration file for a connector and modified it, make sure that the connector can locate the configuration file when the connector starts up.
To do so, open the startup file used for the connector, and verify that the location and file name used for the connector configuration file match exactly the name you have given the file and the directory or path where you have placed it.
Connector Configurator is globalized and can handle character conversion between the configuration file and the integration broker. Connector Configurator uses native encoding. When it writes to the configuration file, it uses UTF-8 encoding.
Connector Configurator supports non-English characters in:
The drop list for the CharacterEncoding and Locale standard configuration properties displays only a subset of supported values. To add other values to the drop list, you must manually modify the \Data\Std\stdConnProps.xml file in the product directory.
For example, to add the locale en_GB to the list of values for the Locale property, open the stdConnProps.xml file and add the line in boldface type below:
<Property name="Locale" isRequired="true" updateMethod="component restart"> <ValidType>String</ValidType> <ValidValues> <Value>ja_JP</Value> <Value>ko_KR</Value> <Value>zh_CN</Value> <Value>zh_TW</Value> <Value>fr_FR</Value> <Value>de_DE</Value> <Value>it_IT</Value> <Value>es_ES</Value> <Value>pt_BR</Value> <Value>en_US</Value> <Value>en_GB</Value> <DefaultValue>en_US</DefaultValue> </ValidValues> </Property>
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.
The following table lists the business object request handling features supported by the connector
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 |
The following table lists the event notification features supported by the connector
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 |
The following table lists the general features supported by the connector
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 |