The following sections describe how the connector processes business object requests and describe how the connector handles event notification.
The connector is meta-data driven. It is designed to handle the retrieval and submission of any business object regardless of the type of business object or the variables it carries. For the connector to be meta-data driven, business objects for Portal Infranet must contain the following information:
For more information on business object meta-data for Portal, see Understanding business objects.
When the connector receives a business object request from the WebSphere business integration system, the connector business object handler processes the business object. The business object handler is the bridge between the application-specific object and the Portal Infranet API. It is responsible for submitting a Portal Infranet operation to the API and for creating an application-specific business object that is sent to the WebSphere business integration system as the result of an Infranet event. The business object handler uses the data in the business object and any meta-data to make a call to the Infranet Java API to submit a storable object to Portal. When this operation is complete, a status is returned to the integration broker.
The flowchart in Figure 2 shows at a high level how the business object handler processes business object requests. The business object handler extracts the verb and key attributes from the business object. It uses the verb to determine the function call that is made to handle the business object. In this example, if the verb were an update verb, the UpdateObject function would be called.
Figure 2. High-level
view of business object processing
The business object handler Retrieve method retrieves an object from Portal Infranet and populates a WebSphere Business Integration Adapter business object with the application information. The connector Retrieve method does the following:
Figure 3 shows how the Retrieve method works. The method determines which action should be performed on an attribute, depending on its type. If it is a basic attribute type (such as a string), the business object handler dynamically populates the field. If the method encounters a child business object, it descends through the object until it reaches the basic attributes of that child business object. Then it cycles through all the basic attributes of the child object before continuing with the basic attributes of the parent object.
Figure 3. Flowchart
for retrieve verb processing
To process a Create or Update verb, the business object handler constructs an Infranet API object (an flist) and passes it to the Infranet API. The business object handler performs the following steps:
Infranet has an event mechanism that permits it to keep track of the actions that occur in the application. When a user performs an action in Infranet, the application generates an associated event.
The WebSphere Business Integration Adapter event module examines the event and determines whether it is one that the connector is interested in. If so, the event module generates an entry in the WebSphere Business Integration Adapter event table for the event.
Event detection in Infranet is implemented by means of a custom Infranet facilities module that is called by the event notification mechanism. This facilities module is provided by the integration broker, and it works with two configuration files to identify Infranet events and write events to the WebSphere Business Integration Adapter event table.
When a change occurs to an Infranet object, a persistent event is raised. Infranet can be configured to call a specific opcode when a given event occurs; therefore, the integration broker provides a configuration flat file that configures Infranet to call the WebSphere Business Integration Adapter event facilities module for events associated with business objects for Portal. This configuration file is called "pin_notify_cw" and is loaded into Infranet using the load_pin_notify utility delivered with Infranet.
When the event module receives an event, it extracts information from the event object and creates a new entry in the WebSphere Business Integration Adapter event table. An event in Infranet is actually an instance of an Infranet storable class, and each creation, modification, or deletion event is related to a specific Infranet storable class. For example, if a user modifies a particular contact related to a customer, Infranet generates an instance of the storable class /event/customer/nameinfo.
The event module uses its own event module configuration file to determine what event occurred, identify what part of the storable class (and related business object) was modified, and determine what type of action occurred. Using the configuration file event_code.txt, the event module examines the Infranet event and populates the WebSphere Business Integration Adapter event table with a record reflecting the event.
The event notification mechanism for the connector uses three tables created inside the Oracle database instance used by Infranet.
The schema of the first table specifies the information that is recorded for each event sent by Infranet that the connector is interested in. This table layout is also used for the archive table.
Event detection and associated processing is done within an Infranet transaction. Infranet calls custom processes within a transaction and waits for the results of the processing. If the custom process returns an error, the transaction is aborted. This guarantees that the connector does not lose any events.
Known Issues - The event notification module verifies the USERID of any Portal Event sent to it defined in the pin_notify_cw file. If there is no PIN_FLD_USERID associated with the event sent to the module, it will error and cause problems saving the object online. These types of events need to be adjusted using FLists or the storable classes to include such an ID. Check for these errors in the log file defined in the crossworlds.cnf configuration file.
The event module checks for a USERID to prevent events sent into the application by the connector from being added to the event queue. This is referred to as Ping-Ponging.
The "/event/customer/billinfo" is an event type where such a problem exists.
The connector checks for events by polling the XWORLDS_Events table that was set up in the Infranet database instance. The connector polls by using an SQL SELECT statement to extract entries from the XWORLDS_Events table. The number of events selected is specified by the PollQuantity property of the connector.
Polling is done by the pollForEvents() method in the connector. The connector polls the event table at the PollFrequency set in the WebSphere Business Integration Adapter connector properties. If a new row is detected in the table, the event data is retrieved, and the connector processes the event as follows:
Once the business object is sent to the WebSphere business integration system, the event table entry is archived to the XWORLDS_Archive_Events table and deleted from the event table.
The time interval at which the poll method is called can be adjusted by changing the PollFrequency connector property. This property is set using the integration broker.
When connecting to the Portal Infranet connection manager using the API, the connector does the following:
The connect statement uses the values of connector application-specific properties that are defined in the repository.
The context instances in the pool are closed when the connector is terminated.
The connector has been internationalized so that it can support double-byte character sets, and deliver message text in the specified language. When the connector transfers data from a location that uses one character code set to a location that uses a different code set, it performs character conversion to preserve the meaning of the data. The Java runtime environment within the Java Virtual Machine (JVM) represents data in the Unicode character code set. Unicode contains encodings for characters in most known character code sets (both single-byte and multibyte). Most components in the IBM CrossWorlds system are written in Java. Therefore, when data is transferred between most IBM CrossWorlds components, there is no need for character conversion. To log error and informational messages in the appropriate language and for the appropriate country or territory, configure the Locale standard configuration property for your environment. For more information on these properties, see Appendix A, Standard configuration properties for connectors.