This chapter describes the default behavior of the Ensemble email inbound adapter (EnsLib.EMail.InboundAdapter) and describes how to use this adapter in your productions. It discusses the following topics:

First, it is useful to understand the details that you specify for the adapter. The EnsLib.EMail.InboundAdapter class provides runtime settings that you use to specify items like the following:

The POP3 server to use and login details for the mailbox from which to read messages

Matching criteria that indicate the messages of interest

A polling interval, which controls how frequently the adapter checks for new input

In general, the inbound email adapter (EnsLib.EMail.InboundAdapter) periodically checks the mailbox, finds matches, sends the messages (as instances of %Net.MailMessage) to the associated business service, and deletes the messages from the email server. The business service, which you create and configure, uses these messages and communicates with the rest of the production. The following figure shows the overall flow:

More specifically:

The adapter regularly executes its OnTask() method, which connects to the POP3 server and logs on, using a specific username and password. The polling interval is determined by the CallInterval setting.

The adapter looks at all the messages in this mailbox and compares them against the match criteria.

When the adapter finds a message that meets the criteria, it does the following:

The adapter creates an instance of the %Net.MailMessage class and puts the email data into it.

The internal ProcessInput() method of the business service class executes. This method performs basic Ensemble tasks such as maintaining internal information as needed by all business services. You do not customize or override this method, which your business service class inherits.

Studio provides a wizard that you can use to create a business service stub similar to the preceding. To access this wizard, click File > New and then click the Production tab. Then click Business Service and click OK. Note that the wizard provides a generic input argument. If you use the wizard, InterSystems recommends that you edit the method signature to use the specific input argument needed with this adapter; the input argument type should be %Net.MailMessage.

Implementing the OnProcessInput() Method

Within your custom business service class, your OnProcessInput() method should have the following signature:

Method OnProcessInput(pInput As %Net.MailMessage,
pOutput As %RegisteredObject) As %Status

Here pInput is the email message object that the adapter will send to this business service; this is an instance of %Net.MailMessage. Also, pOutput is the generic output argument required in the method signature.

Email messages can have a variety of different structures, which would need different handling. You may want to start by making sure that the message has the structure you expect. That is, you would check whether it is a multipart message and whether the parts are binary. For more information, see Using Email Messages.

Each of these methods returns a status (specifically, an instance of %Status).

Make sure that you set the output argument (pOutput). Typically you set this equal to the response message that you have received. This step is required.

Return an appropriate status. This step is required.

The following shows a simple example:

MethodOnProcessInput(pInputAs%Net.MailMessage,pOutputAs%RegisteredObject)As%Status{//Check if mail message has multiple partsSetmulti=pInput.IsMultiPartIfmulti{$$$TRACE("This message has multiple parts; not expected")Quit$$$ERROR($$$GeneralError,"Message has multiple parts")}//Check if mail message is binarySetbin=pInput.IsBinaryIfbin{$$$TRACE("This message is binary; not expected")Quit$$$ERROR($$$GeneralError,"Message is binary")}//Check if mail message is HTMLSethtml=pInput.IsHTMLIfhtml{$$$TRACE("This message is HTML not expected")Quit$$$ERROR($$$GeneralError,"Message is HTML")}//now safe to get text of messageSetpReq=##class(EEMA.EmailContents).%New()SetpReq.MessageText=pInput.TextDataSettSc=..SendRequestSync("EEMA.EmailProcessor",pReq,.pResp)SetpOutput=pRespQuittSc}

Using Email Messages

As noted earlier, after you retrieve an email message (%Net.MailMessage), you generally start by determining what kind of message it is and how to read it; that is, whether it is a multipart message and whether the parts are binary.

Once you know what the general message structure is, use the following techniques to retrieve the contents:

For a multipart message, use the Parts property, which is an array of the parts. Use the Count() method to get the number of parts. Use the GetAt() method to retrieve a given part; the key for each part is an integer, starting with 1 for the first part.

Note that the email client that sends a message determines any wrapping in the message. The mail server has no control over this; nor does Caché.

Message Headers

The message itself and each part of the message has a set of headers.

The %Net.MailMessage class provides properties that give you the most commonly used headers.

To  The list of email addresses to which this message was sent. This property is a standard Caché list; to work with it, you use the standard list methods: Insert(), GetAt(), RemoveAt(), Count(), and Clear().

Cc  The list of carbon copy addresses to which this message was sent.

Bcc  The list of blind carbon copy addresses to which this message was sent. If the receiver of the message was on the blind carbon copy list, this property contains the address of the receiver; otherwise, it is null.