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.

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.

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. For more information, see Working with Received Email.

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

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

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

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

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

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

For information on properties and methods of %Net.MailMessageOpens in a new tab, see Working with Received Email.

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:

   • Authenticate to a POP3 mail server

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

See Also

• Working with Received Email

• Settings for the Email Inbound Adapter