How the connector works

The connector receives a business object from the integration broker, processes that object based on its active verb, and then sends a request for operation to the Exchange Server.

It also polls the event store for subscribed events. If a subscribed event is found, the connector builds a business object and populates it with data retrieved from an API call to the Exchange Server. The connector then publishes the business object to the integration broker.

The following steps illustrate the basic sequence of events when a connector starts, polls for events, and processes those events:

  1. During connector startup, the init() method is invoked and the connector is logged onto Exchange Server.
  2. The resetReceivedCount() method is called to set the eventsReceived property to zero (0).
  3. The pollForEvents() method is called to poll the Event Store for subscribed events.
  4. If the connector finds subscribed events, it calls the processEvents() method to handle all of the event processing. The processEvents() method does the following:
  5. Depending on the archive behavior specified in the ArchiveProcessed property, the archiveEvent(), deleteEvent(), or setEventStoreStatus() methods can be called to perform the necessary event archiving.

The following sections contain additional information about these processes.

Business object processing

When the connector receives a request from an integration broker to perform an application operation, 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 order in which the connector processes child business objects and the top-level business object depends on whether the child business objects are contained with or without ownership and whether they are contained with single or multiple cardinality.

Note:
The term hierarchical business object refers to a complete business object, including all of the child business objects it contains. The term individual business object refers to a single business object, independent of any child business objects that it contains or that contain it. The term top-level business object refers to the individual business object at the top of the hierarchy; it does not have a parent business object.

Business object retrieval

When an integration broker asks the connector to retrieve a hierarchical business object from the database, the connector attempts to return a business object that exactly matches the current database representation of that business object. In other words, all simple attributes of each individual business object returned to the integration broker match the value of the corresponding fields in the database. Also, the number of individual business objects in each array contained by the returned business object match the number of children in the database for that array.

To perform such a retrieval, the connector uses the primary key values in the top-level business object received from the integration broker. These key values are used to recursively descend through the corresponding data in the database.

Business object creation

When an integration broker asks the connector to create a hierarchical business object in the database, the connector performs the following steps:

  1. Recursively creates each single-cardinality child business object contained with ownership into the database.
  2. Processes each single-cardinality child business object contained without ownership.
  3. Creates the top-level business object in the database.
  4. Creates each single-cardinality child business object that stores the parent/child relationship in the child.
  5. Creates each multiple-cardinality child business object.

Business object modification

When an integration broker asks the connector to update a hierarchical business object in the database, the connector performs the following steps:

  1. Uses the primary key values of the source business object to retrieve the corresponding entity from the database.
  2. Recursively updates all single-cardinality children of the top-level business object.
  3. Updates all simple attributes of the retrieved business object except those whose corresponding attribute in the source business object contains the value CxIgnore.
  4. Processes all arrays of the retrieved business object.

Business object deletion

When an integration broker asks the connector to delete a hierarchical business object from the database, the connector deletes only the top-level business object.

Processing application events

The creation, modification, or deletion of any Exchange Server object is considered an event. The event is placed into the Event Store. When the connector invokes the pollForEvents () method, the event is retrieved and processed. The Retrieve operation is based on key attributes in the business object (typically the EntryID attribute, and sometimes the StoreID attribute).

Create

When the connector finds a Create event in the Event Store, it creates a business object of the type specified by the event and sets the FolderID, StoreID, and MessageID fields with the values found in the event. The connector then retrieves the business object from the database and publishes it to the integration broker with the Create verb.

Update

When the connector finds an Update event in the Event Store, it creates a business object of the type specified by the event and sets the FolderID, StoreID, and MessageID fields with the values found in the event. The connector then retrieves the business object from the database and publishes it to the integration broker with the Update verb.

Delete

When the connector finds a Delete event in the Event Store, it creates a business object of the type specified by the event and sets the FolderID, StoreID, and MessageID fields to the values found in the event (all other attributes are set to CxIgnore).

The connector supports only physical delete operations that are triggered by Exchange Server.

Event handling

Whenever an Exchange Server object is created, updated, or deleted, the connector's Event Listener places the event in the Event Store. When the connector invokes the pollForEvents() method, the events in the Event Store are detected and subsequently processed.

The PollQuantity connector property specifies the number of events the connector retrieves from the event store. For each event the connector retrieves, the following tasks are performed:

Table 1 lists the status values used for events.

Table 1. Event status

Event status Numerical value for status Description
READY_FOR_POLL 0 The event is ready to be picked up by the next poll call.
IN_PROGRESS 1 The connector has picked up the event and is processing it.
UNSUBSCRIBED 2 There is no subscription for this event.
SUCCESS 3 The connector successfully processed the event.
ERROR_PROCESSING_EVENT -1 The connector encountered an error while processing the event.
ERROR_POSTING_EVENT -2 The connector encountered an error while publishing the business object to the integration broker.
ERROR_OBJECT_NOT_FOUND -3 The business object for which the event was created cannot be found.

Event notification

In order to use event notification, you must create two Exchange Server user folders: one for storing events, and one for archiving events. For instructions on creating and configuring these folders, see Connector installation.

Event archiving

The ArchiveProcessed connector property determines whether an event is archived after its status is updated. Table 2 describes the settings for ArchiveProcessed.

Table 2. Using the ArchiveProcessed property

ArchiveProcessed value Event status Connector behavior
true Event successfully processed The connector archives the event with a status of SUCCESS. After the event has been archived, it is deleted from the Event Store.
Event is unsuccessfully processed The connector archives the event with a status of ERROR_POSTING_EVENT or ERROR_OBJECT_NOT_FOUND. After the event has been archived, it is deleted from the Event Store.
Event is not processed because there is no subscription for the business object The connector archives the event with a status of UNSUBSCRIBED. After the event has been archived, it is deleted from the Event Store.
false Event is successfully processed The event remains in the Event Store.
Event is unsuccessfully processed The event remains in the event store with a status of ERROR_POSTING_EVENT, ERROR_OBJECT_NOT_FOUND, or ERROR_PROCESSING_EVENT.
Event is not processed because there is no subscription for the business object The event remains in the event store with a status of UNSUBSCRIBED.

Event recovery

The connector can recover events after a system failure. During startup, the connector invokes the recoverInProgressEvents() method to search for any events that had a status of IN_PROGRESS when the previous connector session ended.

The InDoubtEvents connector property determines what type, if any, of event recovery is performed. Refer to Application-specific configuration properties for more information on setting this property.

Guaranteed Event Delivery

The connector supports Guaranteed Event Delivery (GED) through the use of the connector framework's duplicate event elimination (DEE) feature and the setDEEID() method. As a result, an event is sent to the integration broker only once, even if the connector terminates after delivering the event to the broker but before updating the event's status in the Event Store.

In order to take advantage of GED, you must set three connector configuration properties, as shown in Table 3.

Table 3. Setting connector properties to enable GED

Property name Description Value required for GED
DuplicateEventElimination Standard configuration property; when set to True, the event ID is stored in the monitor queue to prevent delivery of duplicate events. True
MonitorQueue Standard configuration property; specifies the JMS queue where the connector stores the processed event ID. Must be set to the appropriate queue (for example, MONITORQUEUE)
InDoubtEvents Connector-specific configuration property; specifies how to handle events that had a status of IN_PROGRESS when the connector terminated. Reprocess

For more information on setting connector configuration properties, see Standard configuration properties for connectors.

Transaction support

Transactional support is provided by the Exchange Server Extensible Storage Engine (ESE). The ESE is a transaction logging system that ensures data integrity after a system failure. Because the Event Store and Archive Store are placed in Exchange Server mailboxes, the ESE provides support for aborting or rolling back an event processing transaction.

If the Event Listener is unable to process events (either because it is disabled or because of a system error), the Information Store Service maintains the events and delivers them to the Event Listener once it has been restored.

Copyright IBM Corp. 1997, 2003