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. Request processing for the i2 connector is multi-threaded, it can handle multiple requests.
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.
This adapter is compatible with IBM's Common Event Infrastructure, a standard for event management that permits interoperability with other IBM WebSphere event-producing applications. If Common Event Infrastructure support is enabled, events produced by the adapter can be received (or used) by another Common Event Infrastructure-compatible application.
For more information refer to the Common Event Infrastructure appendix in this guide.
This adapter is compatible with the Application Response Measurement application programming interface (API), an API that allows applications to be managed for availability, service level agreements, and capacity planning. An ARM-instrumented application can participate in IBM Tivoli Monitoring for Transaction Performance, allowing collection and review of data concerning transaction metrics.
For more information refer to the Application Response Measurement appendix in this guide.
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.
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 (if it did not unregister). This can be referred to as durable subscription. Durable subscription is maintaind if the adapter is not configured to unregister for operations at the connector level or at the polling meta-object level.
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.
i2 CIS SDK version 6.1 contains a feature called Interaction Acknowlegement that enables the redelivery of messages that were not confirmed to be delivered to the integration broker. It does this by allowing a client to state whether or not messages are auto-acknowleged and retaining messages on the i2 Message Bus until they have been successfully delivered. This feature can be enabled by setting the AutoAcknowlege property for polling meta-objects to false.
If the delivery of a message fails to be delivered to the broker and the Auto Acknowlege field is set to false, the following happens (depending on the status returned by the gotApplEvents method:
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.