Using the Email Inbound Adapter

Overall Behavior

First, it is useful to understand the details that you specify for the adapter. The EnsLib.EMail.InboundAdapterOpens in a new tab 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.InboundAdapterOpens in a new tab) periodically checks the mailbox, finds matches, sends the messages (as instances of %Net.MailMessageOpens in a new tab) 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:

1. 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.

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

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

   1. The adapter creates an instance of the %Net.MailMessageOpens in a new tab class and puts the email data into it.

   2. The adapter calls the internal ProcessInput() method of the associated business service class, passing the %Net.MailMessageOpens in a new tab instance as input.

   3. The adapter deletes the mail message from the server.

4. The internal ProcessInput() method of the business service class executes. This method performs basic production 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.

5. The ProcessInput() method then calls your custom OnProcessInput() method, passing the %Net.MailMessageOpens in a new tab instance as input. The requirements for this method are described later in “Implementing the OnProcessInput() Method.”

The response message follows the same path, in reverse.

Creating a Business Service to Use the Email Inbound Adapter

To use this adapter in your production, create a new business service class as described here. Later, add it to your production and configure it. You must also create appropriate message classes, if none yet exist. See “Defining Messages” in Developing Productions.

The following list describes the basic requirements of the business service class:

• Your business service class should extend Ens.BusinessServiceOpens in a new tab.

• In your class, the ADAPTER parameter should equal EnsLib.EMail.InboundAdapterOpens in a new tab.

• Your class should implement the OnProcessInput() method, as described in “Implementing the OnProcessInput() Method.”

• For other options and general information, see “Defining a Business Service Class” in Developing Productions.

The following example shows the general structure that you need:

Class EEMA.EmailService Extends Ens.BusinessService
{
Parameter ADAPTER = "EnsLib.EMail.InboundAdapter";

Method OnProcessInput(pInput As %Net.MailMessage,
                      pOutput As %RegisteredObject) As %Status
{
   set tsc=$$$OK
   //your code here
   Quit tsc
}
}

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.MailMessageOpens in a new tab. Also, pOutput is the generic output argument required in the method signature.

The OnProcessInput() method should do some or all of the following:

1. Examine the email message and decide how to use it.

   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.”

2. Once you are sure of the message structure, use the other properties of %Net.MailMessageOpens in a new tab to access the message body or any headers. See “Using Email Messages.”

3. Create an instance of the request message, which will be the message that your business service sends.

   For information on creating message classes, see “Defining Messages” in Developing Productions.

4. For the request message, set its properties as appropriate, using values in the email message.

5. Call a suitable method of the business service to send the request to some destination within the production. Specifically, call SendRequestSync(), SendRequestAsync(), or (less common) SendDeferredResponse(). For details, see “Sending Request Messages” in Developing Productions

   Each of these methods returns a status (specifically, an instance of %StatusOpens in a new tab).

6. 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.

7. Return an appropriate status. This step is required.

The following shows a simple example:

Method OnProcessInput(pInput As %Net.MailMessage,
pOutput As %RegisteredObject) As %Status
{
    //Check if mail message has multiple parts
    Set multi=pInput.IsMultiPart
    If multi
        {$$$TRACE("This message has multiple parts; not expected")
        Quit $$$ERROR($$$GeneralError,"Message has multiple parts")
        }

    //Check if mail message is binary
    Set bin=pInput.IsBinary
    If bin
        {$$$TRACE("This message is binary; not expected")
        Quit $$$ERROR($$$GeneralError,"Message is binary")
        }

    //Check if mail message is HTML
    Set html=pInput.IsHTML
    If html
        {$$$TRACE("This message is HTML not expected")
        Quit $$$ERROR($$$GeneralError,"Message is HTML")
        }

    //now safe to get text of message
    Set pReq=##class(EEMA.EmailContents).%New()
    Set pReq.MessageText=pInput.TextData

    Set tSc=..SendRequestSync("EEMA.EmailProcessor",pReq,.pResp)
    Set pOutput=pResp

    Quit tSc
}

Using Email Messages

As noted earlier, after you retrieve an email message (%Net.MailMessageOpens in a new tab), 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.

In this step, you can use the ContentType property, which is equivalent to the Content-Type property. Or you can use the IsBinary, IsHTML, and IsMultiPart properties, which indirectly provide the same information as ContentType.

If the message is a multipart message, each part is an instance of %Net.MailMessagePartOpens in a new tab.

A message has message headers; each part of the message can also have message headers. You can access the headers via various properties of %Net.MailMessageOpens in a new tab and %Net.MailMessagePartOpens in a new tab.

Adding and Configuring the Business Service

To add your business service to a production, use the Management Portal to do the following:

1. Add an instance of your custom business service class to the production.

2. Enable the business service.

3. Configure the adapter to access a POP3 mail server and download messages. Specifically:

   • Specify a POP3 mail server and login details needed to access a mailbox

   • Specify criteria to determine which messages to download

   • Use Call Interv\al to specify how often the adapter looks for email

4. Run the production.