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:
The following sections contain additional information about these processes.
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.
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.
When an integration broker asks the connector to create a hierarchical business object in the database, the connector performs the following steps:
When an integration broker asks the connector to update a hierarchical business object 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 deletes only the top-level business object.
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).
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.
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.
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.
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.
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 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.