The connector works in two modes, Request and Event. In Request mode, the process begins when the integration broker issues a request to Exchange Server by sending the connector a business object which represents the requested operation. The connector processes that object based on its active verb and then sends the appropriate request on to Exchange Server. Depending on the nature of the request, the connector may also process and return information from Exchange Server to the integration broker.
In Event mode, the process begins at Exchange Server. The connector polls the Event Store on the Server for its record of subscribed Exchange events. For every such event found, the connector builds an appropriate business object and populates it with data retrieved from User Folders by means of a WebDAV call. The connector then publishes the business object to the integration broker.
The following sections contain additional information about these processes.
Requests from the integration broker take the form of one of four operations: Retrieve, Create, Update, or Delete. Retrieve asks the connector to retrieve information from the Exchange database; Create, Update, or Delete ask the connector to instruct the database to perform the appropriate actions on itself, based on the information contained in the initial request.
When the integration broker requests that the connector retrieve information from Exchange, it furnishes values known as primary key values. Using these values the connector can fetch the appropriate information from the Exchange database. Because the information that is being requested is often complex, the information is usually stored hierarchically. The connector uses the primary key values to descend recursively through the database item hierarchy.
The business object that the connector builds to return the information to the broker is also hierarchical, and is known as a hierarchical business object. A hierarchal business object consists of a top-level business object and one or more child business objects. The connector attempts to construct a business object that exactly matches the structure of the item in the database. 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 Exchange database and the number of child business objects contained by the returned hierarchical business object match the number and order of children in the database.
When an integration broker asks the connector to create a new Exchange Server item in the database based on the business object the broker hands the connector, the connector performs the following steps:
When the integration broker asks the connector to update an Exchange Server item in the database, the connector performs the following steps:
When an integration broker asks the connector to delete a hierarchical business object from the database, the connector physically deletes the top-level item.
An event is the creation, modification, or deletion of any Exchange Server item. Exchange Information Store notifies Event Listener that an event has occurred. The event is placed into the Event Store and given an event ID. The connector invokes its pollForEvents () method and the information represented by the events is retrieved and processed using the ItemURI found in the event notification.
When the connector finds a Create event in the Event Store, it creates a new business object whose structure matches that of the type specified by the event and sets the ItemURI field with the values found in the event. The connector then retrieves the pertinent item from the database and uses it to populate the new business object. The verb on the business object is set to Create and the connector publishes it to the integration broker.
When the connector finds an Update event in the Event Store, it creates a new business object whose structure matches that of the type specified by the event and sets the ItemURI field with the values found in the event. The connector then retrieves the pertinent item from the database and uses it to populate the new business object. The verb on the business object is set to Update and the connector publishes it to the integration broker.
When the connector finds a Delete event in the Event Store, it creates a new business object whose structure matches that of the type specified by the event and sets the ItemURI field with the values found in the event. The verb on the business object is set to Delete and the connector publishes it to the integration broker.
The connector supports only physical delete operations that are triggered by Exchange Server.
Whenever an Exchange Server object is created, updated, or deleted, the connector's Event Listener places an event notification, or event, in the Event Store. When the connector invokes the pollForEvents() method, the notifications 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.
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. |
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.
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. |
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.
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 Appendix A, Standard configuration properties for connectors.
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 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 Event Listener is unable to process events (either because it is disabled or because of a system error), the Event Service maintains the events and delivers them to Event Listener once it has been restored.