Using Email Adapters with Ensemble
Using the Email Inbound Adapter
[Back] [Next]
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

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:

For settings not listed in this book, see Settings in All Productions in Managing Ensemble Productions.
Overall Behavior
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:
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:
  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.MailMessage 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.MailMessage 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 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.
  5. The ProcessInput() method then calls your custom OnProcessInput() method, passing the %Net.MailMessage 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 Ensemble Messages in Developing Ensemble Productions.
The following list describes the basic requirements of the 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
}
}
Note:
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.
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.MailMessage 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 Ensemble Messages in Developing Ensemble 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 Ensemble Productions
    Each of these methods returns a status (specifically, an instance of %Status).
  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.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.
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.MailMessagePart.
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.MailMessage and %Net.MailMessagePart.
Message Contents
Once you know what the general message structure is, use the following techniques to retrieve the contents:
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.
Both %Net.MailMessage and %Net.MailMessagePart provide the following properties, which give you other headers:
Also, you can use the GetAttribute() method. Given a header name and an attribute, this method returns the value of that attribute.
Other Message Information
The following properties and methods provide additional information about the message:
Adding and Configuring the Business Service
To add your business service to an Ensemble production, use the Management Portal to do the following:
  1. Add an instance of your custom business service class to the Ensemble production.
  2. Enable the business service.
  3. Configure the adapter to access a POP3 mail server and download messages. Specifically:
  4. Run the production.
Specifying How to Log into a POP3 Server
Specify values for the following settings to indicate the POP3 server to log onto, as well as the security information to access a mailbox:
For example, you could use values like the following:
Setting Value
POP3 Server pop.hotpop.com
POP3 Port 110
Credentials hotpop
In this example, hotpop is the ID of the Ensemble credentials that consist of the username isctest@hotpop.com and the corresponding password.
Specifying the Messages to Retrieve
Specify values for the following settings to control which messages to retrieve. Only messages that match all the given criteria are used. The matching is case-sensitive.
If you change these criteria, the adapter will examine and possibly process messages that did not match the criteria before.