How the e-Mail adapter works

The following sections describe how the e-Mail adapter processes business object requests and handles events.

Business object processing

When an integration broker sends a business object to the e-Mail adapter, the adapter processes the business object and generates an e-mail.

An e-Mail business object must contain e-mail routing information (from address, to address, subject, and content), the mime type of the attachments, and the business objects to deliver. The business object can also specify the complete path of files to include in the e-mail as attachments. A single business object can result in an e-mail message containing multiple business objects and multiple files as attachments.

To process a business object request, the adapter:

  1. Extracts the routing information from the top-level business object and composes an e-mail message.
  2. Processes each contained business object or file as follows:
  3. When the e-mail is complete, the adapter delivers it using JavaMail.

Figure 2 illustrates business object processing with the e-Mail adapter. For information on creating business objects for the e-Mail adapter, see Developing business objects for the adapter.

Figure 2. e-Mail adapter business object processing

Diagram of e-Mail adapter business object processing

Event notification

In event notification, the adapter polls for e-mail messages in specified folders on the mail server. The adapter checks the folders, retrieves new messages, converts the messages to business objects using the data handler, and sends the business objects to the integration broker.

The adapter can poll in multiple locations. The following folders are required per poll location:

Although polling locations can be located on different IMAP stores, these three folders, if specified for a poll location, should be in the same mailbox.

The sections that follow describe the event mechanism is more detail.

Event triggering

A triggering event for the e-Mail adapter is a new e-mail that arrives in a poll folder. The adapter checks each poll folder for new e-mails at the interval defined by the PollFrequency configuration property.

Event detection

Each IMAP mail server has a message store called an IMAP store. The IMAP store has a mailbox for each of the users of the mail server. A mailbox can have multiple folders, and a folder can contain multiple e-mail messages or folders.

Each poll folder must have a corresponding archive folder and failed event folder. The poll folder, archive folder, and failed event folder are together referred to as a poll location. An administrator must create the folders and specify the poll locations in the meta-object for the adapter.

The e-Mail adapter polls for new messages in the poll folder of an IMAP store. When the adapter sees a new message in a poll folder, it retrieves the message. The adapter determines that a message is a new message by checking the status of the IMAP flag for the message.

Event status

IMAP supports flags that describe the state of e-mail messages in a mailbox. The event detection mechanism uses the flags to determine which e-mail messages to retrieve. The status of an event is specified both by the folder in which the message is located and by the message flag.

The event mechanism uses the IMAP flag SEEN to mark events that are "in progress". In polling, the adapter checks the messages in a poll folder and picks messages that are not marked with the SEEN flag. These events are "ready to be polled". When the adapter picks a message from the poll folder for processing, it sets the SEEN flag for the message. Events marked as SEEN are "in progress" events.

Note:
The adapter does not poll messages marked as SEEN.

When processing is complete, and all the attachments of a message are successfully converted to business objects and sent to the integration broker, the e-mail is marked as FLAGGED and then moved to the archive folder. Messages that have attachments that cannot be converted to business objects, or messages that have unsubscribed business objects or business objects that could not be delivered to integration broker are moved to the failed event folder. Table 1 summarizes the event states for the e-Mail adapter.

Table 1. Event states

Event state e-Mail message state
ready to be polled All messages in the poll folder with the SEEN flag not set.
in progress All messages in the poll folder with the SEEN flag set.
sent to integration broker All messages in the archive folder. Any message in the PollFolder that is marked with the FLAGGED flag set.
Note:
The adapter changes the flag of an IN_PROGRESS message to FLAGGED once it has been sent to the interchange broker and is set to be archived (moved to the archive folder).
unsubscribed business objects and errors All messages in the failed event folder.

Event retrieval

To retrieve events, the adapter polls each poll folder in turn and picks one e-mail from each mailbox. This polling strategy ensures that e-mails in all poll folders get processed.

The adapter processes each of the e-mails retrieved from a poll location in the following way:

  1. From the poll folder, the adapter picks an e-mail with the SEEN flag not set. The adapter then sets SEEN flag on this e-mail.
  2. The adapter fetches the e-mail from the poll folder. The e-mail can have any number of attachments, and the adapter processes each attachment. There must be only one business object per attachment.
  3. For each attachment, the adapter uses the mime type of the attachment to determine which data handler to use to convert the attachment to a business object. The adapter retrieves the contents of the attachment and passes it to the data handler. Attachments in an e-mail can be in different formats. If the attachment has no mime type, however, the adapter does not process the attachment.
  4. The data handler generates a business object and returns it to the adapter.
  5. If the business object is subscribed, the adapter delivers it to the integration broker; otherwise, the adapter considers this e-mail to be a failed event.

The adapter processes all message attachments in the same way. An e-mail message is considered to be a successful event if all the attachments were converted to business objects and delivered to the integration broker. In the cases of successful e-mails, the adapter marks the e-mail messages as FLAGGED, then, archives the successfully processed e-mails to the archive folder for this polling location. The adapter does not archive an e-mail until all of the attachments of the e-mail have been processed.

If one or more attachments cannot be converted to business objects or the business object provided by the data handler is unsubscribed, the event is a failed event. In this case, the adapter archives the e-mail in the failed event folder for this polling location.

The adapter delivers a number of events per folder that is less than or equal to the value configured for the PollQuantity adapter property. The adapter does not fetch and process new e-mail until it has finished processing the previous e-mail.

Failed events

An e-mail is considered to be a failed event in the following situations:

The adapter processes all the attachments of a message and deliver business objects obtained from a message to the integration broker, even if the message is a failed event. As an example, assume that an e-mail has five attachments. The adapter processes attachments one and two, fails to process attachment three, and then succeeds in processing attachments four and five. Although the adapter delivers business objects for four of the attachments, the entire e-mail message is treated as failed event and archived in the failed event folder because attachment three could not be processed. The adapter logs the details of each attachment that it fails to convert to a business object.

Event archiving

To archive events, the adapter requires an archive folder and a failed event folder. Events are archived into these folders as follows:

Recovery mechanism

An administrator can configure the recovery mechanism of the adapter for each polling location specified by the PollConfigMO configuration property. The PollConfigMO property identifies a meta object that has an InDoubtEvents attribute for each polling location. This attribute can have the values Reprocess, Ignore, LogError, or FailOnStartUp.

If the adapter crashes between poll calls, the poll folders may have messages that are in-progress. These messages have a SEEN flag set and are in-doubt events for the adapter. The next time the adapter starts, the initialization procedure scans all the poll folders for the in-doubt transactions as follows:

Before restarting the adapter, the administrator can view each of the poll folders using an e-mail client program, and determine how to handle in-doubt events. The administrator can either leave the in-doubt messages in the poll folder, reset the SEEN flag of in-doubt events, or delete the messages. When the adapter next starts, if there are in-doubt events, the adapter processes the in-doubt transactions in the initialization method as explained below.

Adapter initialization

When the e-Mail adapter starts, the following occurs:

  1. The adapter gets the subscription list for the business objects it supports.
  2. Using the information in the adapter's meta-object, the adapter creates a list of poll locations.
  3. The adapter tries to connect to each poll location. The adapter does not start if it fails to connect to any of the poll locations.
  4. The adapter makes sure that all the folders for each poll location exist. The adapter will not start if any folder does not exist.
  5. The adapter retrieves the value of the SMTP_MAILHOST property from the adapter properties. Using this value, the adapter connects to the mail host. If the attempt to connect to the mail host is not successful, the adapter does not start.
  6. The adapter looks for in-doubt transactions in each of the poll folders. If the adapter finds in-doubt transactions, it performs recovery based on the value of the InDoubtEvents setting for the poll location. If the InDoubtEvents flag is Reprocess, the adapter resets the SEEN flag for the message. If it is FailOnStartUp, the adapter terminates. If it is LogError, the adapter logs the error and continues. If the InDoubtEvents flag is Ignore, the adapter continues and ignores the in-doubt transactions.

Copyright IBM Corp. 2003