The i2 connector is a CIS (Common Integration Services) client. It connects to the CIS client API in a non-managed environment, that is, it connects to the CIS adapter directly without an application server using the application's user name and password for authentication. For added flexibility, authentication is also possible during request service processing using the credential information included in the business object. For more information, see "Understanding business objects for the connector".
At present, the CIS client API does not support any connection pooling mechanism. There is no limitation on the number of connections. The i2 CIS adapter provides guaranteed messaging and delivery and persistent client connections, depending on the configuration settings of the i2 CIS agent. Data which includes double byte characters will remain consistent when used with the i2 connector. It supports the Group 1 Languages.
The i2 connector is bi-directional. It can process events originating from i2 applications, as well as requests sent by the broker to the application.
For event subscriptions, the i2 connector uses the information in the i2 metaobjects. It registers the operations on the types specified in these metaobjects with i2's CIS agent through the CIS adapter. The CIS agent listens to the registered operations and detects event messages only for registered operations. The i2 connector obtains these messages with the poll call.
For request processing, the i2 connector processes the requests coming from the integration broker by transforming incoming business objects into CIS records and using the appropriate CIS Client API calls to execute the operation on the i2 application modules.
The i2 connector follows the metadata design principles outlined in the IBM Connector Developer's Guidelines. This means new IBM business objects can be defined without additional coding or customization at the i2 connector code level. For more information, see Understanding business objects for the connector.
The following sections describe how the connector processes application events.
Events for the purpose of this document are the CIS messages published from the i2 application modules. The i2 application notifies the connector of all the events occurring in the modules for which corresponding operations have been registered with the CIS agent.
The onus of registering the operations of interest lies with the i2 connector.
Example: If the i2 connector is interested in the Bidding type operation addBid, any new Bidding additions to the i2 application module will be queued in the CIS server once the i2 connector registers for the addBid operation.
The i2 connector uses the information in the i2 metaobjects. It registers its intent to listen to some of the operations with the poll call. Effectively, this tells the CIS agent that the i2 connector wants to check for the output of the registered operations.
No status updates are made to the i2 applications. Typically, the event status, for example, SUCCESS, FAIL, UNSUBSCRIBED, is written to the application's event store. Since no event store is maintained for i2, the status update strategy is not relevant for the i2 connector. Error messages, if any, are logged to the i2 adapter log file. For more information, see "Troubleshooting and error handling".
For the i2 connector, polling is single threaded. The connector uses i2 metaobjects to register the operations of interest with the CIS agent for polling. These metaobject names have the i2MO prefix and store information about the operation and the corresponding IBM wrapper business object name for the specified operation and type. The attributes for the metaobject are specified as static default values. Default value is an attribute property, which can be set at the business object design time. For information on the wrapper business object structure and attribute properties, see Understanding business objects for the connector and Generating business objects using the i2 ODA.
The steps involved in retrieving a subscription message are as follows:
Once the i2 connector registers its interest for data using a persistent connection, the i2 connector can reliably retrieve data that was sent out when it was not running. The EventSubscriptionConnectionID property value or the polling metaobject connectionId attribute enables it to keep its association with the subscription through restarts of the connector.
For information on configuring the CIS agent with persistent storage, see your i2 CIS infrastructure guide. For information on configuring the EventSubscriptionConnectionID property, see "Installing and configuring the connector".
Example: If the PollQuantity is set to 5 and there are 5 registered operations, each poll call will result in checking the output 25 times. If the PollQuantity is not set, a default of 1 message is retrieved for each poll call for each operation.
Operations are i2's equivalent for verbs and are defined by the XML structure provided by i2 for each port. For more information, see Understanding business objects for the connector, and "Generating business objects using the i2 ODA".
When the i2 connector receives a service call request from an integration broker to perform an operation in an application, the request takes the form of a wrapper business object. The wrapper business object encompasses a metaobject, an operation or verb, and input and/or output types or formats for the operation. The metaobject (MO_Instance) and the input and output business objects are the child business objects of the wrapper business object. Enclosed in the MO_Instance object are the attribute values for the instanceId, connectionId, username, and password. The username and password are used for authentication during request processing. The verb for the wrapper business object must be a valid operation for the specified instance.
The information about the child business object, whether it is an input or output type, is obtained from the Application Specific Information (ASI) of the wrapper business object's attributes.
Example: ASI Type=input indicates that the child business object is of input type.
The input child business object is first converted to an XML message by the XML data handler. The business object is then transformed into a CIS record using the CIS utility. Then the operation is executed using the CIS Client API.
If the operation sends some output XML message, it is converted to an output child business object; and the output child business object in the wrapper business object is populated with the appropriate value.
If the i2 CIS agent is running with persistence enabled, the CIS agent can use stateful operations to maintain the session state. The connector can retrieve results of operations that failed to execute within the specified execution time and attempt to resolve the operations. It returns the results to the integration broker.
You can control the number of times that an interaction should be attempted to be resolved by setting the value for the InteractionResolutionAttempts property. A value of zero (0) for the InteractionResolutionAttempts prevents the connector from trying to resolve an interaction. Interaction Resolution attempts are only made on interactions with the CIS adapter state of INDOUBT.
For information on stateful operations, see "Using metaobjects for stateful operations". For information on configuring the InteractionResolutionAttempts and ExecutionTimeout properties, see "Installing and configuring the connector".
Any error conditions that occur while processing are logged as detailed error messages in the adapter log.
The connector populates a structure called the ReturnStatusDescriptor with the message and status of the latest error that occurred during the processing of a service call request. You can access the ReturnStatusDescriptor to find the reason for the cause of a failure during a service call request. The adapter framework propagates the structure, as appropriate.
When using persistent connections with the CIS adapter, status values have the range of CREATED, STARTED, UNDELIVERABLE, DELIVERED, SUCCESS, INDOUBT, FAILED to indicate the state of the interaction on a request processing failure.