How the connector works

The following sections describe how the connector processes business object requests and describe how the connector handles event notification.

Meta-data-driven connector behavior

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.

Business object processing

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


Retrieve verb 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:

  1. Checks that the Portal Infranet connection is valid. If it is not, the connection must be reinstantiated. If the connection is lost during the processing, the connector returns a BON_FAIL status indicating a connection problem with Infranet.
  2. Retrieves the application-specific information for the object. The application-specific information specified for a verb provides the operation code, or opcode, that must be invoked to retrieve a Portal Infranet object.
  3. Prepares the flist for the opcode based on tje application-specific information for the business object and its attributes.
    Note:
    An flist is a variable length list of field and value pairs. Flists provide input and output parameters to Infranet opcodes and functions.
  4. Invokes the specified opcode with the flist as input, and an empty output flist.
  5. If the previous steps are successful, the return flist structure contains a fully populated flist object corresponding to the storable object that is defined by a /WebSphere Business Integration Adapter business object. Since the flist has a one-to-one correspondence to the WebSphere Business Integration Adapter business object, the flist is traversed to retrieve all the attributes of the WebSphere Business Integration Adapter business object based on the attribute level application-specific information that identifies the flist field name and type.
  6. Populates the business object and sends it to integration broker.

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


Create and update 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:

  1. Retrieves the application-specific business object from the WebSphere Business Integration Adapter business object.
  2. Populates the Portal Infranet API object. When the flist is instantiated, the connector iterates through the object, attribute by attribute, and locates the values with which to populate the flist. This process must search through an object to find an attribute that may be several layers into the object.
  3. Checks that the Portal Infranet connection is still valid. If the connection is lost during processing, the connector returns a BON_FAIL status, indicating a connection problem with Infranet, and the connection must be reinstantiated.
  4. Uses the application-specific information for the business object verb to dynamically call the appropriate opcode for the Create or Update operation. Once the parameters are gathered and placed in an array, and the functional string has been assembled, the context function with the appropriate opcode is invoked.
  5. To process child business objects that have their own opcodes, the business object handler populates a separate flist for each child and then calls the appropriate opcode.
  6. Returns a status when the operation is complete.

Event notification

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

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.

Note:

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.

Event retrieval

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:

  1. The poll function creates an empty business object, sets the verb to Retrieve, and sets the keys using the event record. The business object is sent to the connector's business object handler.
  2. The business object handler uses the event data to make a call to the Infranet Java API to retrieve the Portal Infranet storable object.
  3. The business object handler converts the storable object to a WebSphere Business Integration Adapter application-specific business object, sets the verb to the action in the event record, and then sends the business object to the integration broker.

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.

Connecting to the infranet application

When connecting to the Portal Infranet connection manager using the API, the connector does the following:

  1. Creates a new instance of a Portal Infranet context.
  2. When an opcode is to be executed, the connector uses a context from the pool and adds it to the busy pool.
  3. When the task is completed, the context is returned to the free pool.

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.

Processing locale-dependent data

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.

Copyright IBM Corp. 1997, 2003