Using the Email Outbound Adapter

Overall Behavior

Within a production, an outbound adapter is associated with a business operation that you create and configure. The business operation receives a message from within the production, looks up the message type, and executes the appropriate method. This method usually executes methods of the associated adapter.

The email outbound adapter (EnsLib.EMail.OutboundAdapterOpens in a new tab) provides settings that you use to specify the following:

• The SMTP server to connect to and how to authenticate to it.

• The default address to send email from (the From: header).

• Recipients to add to any messages sent by the adapter, in addition to any hardcoded recipients.

It provides methods to do the following three actions:

• Add a recipient to the To: list.

• Add a recipient to the Cc: list.

• Send a message.

Creating a Business Operation to Use the Adapter

To create a business operation to use the EnsLib.EMail.OutBoundAdapter, you create a new business operation class. 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 operation class:

• Your business operation class should extend Ens.BusinessOperationOpens in a new tab.

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

• In your class, the INVOCATION parameter should specify the invocation style you want to use, which must be one of the following.

  • Queue means the message is created within one background job and placed on a queue, at which time the original job is released. Later, when the message is processed, a different background job will be allocated for the task. This is the most common setting.

  • InProc means the message will be formulated, sent, and delivered in the same job in which it was created. The job will not be released to the sender’s pool until the message is delivered to the target. This is only suitable for special cases.

• Your class should define a message map that includes at least one entry. A message map is an XData block entry that has the following structure:

  XData MessageMap
  {
  <MapItems>
    <MapItem MessageType="messageclass">
      <Method>methodname</Method>
    </MapItem>
    ...
  </MapItems>
  }
  
  

  

• Your class should define all the methods named in the message map. These methods are known as message handlers. Each message handler should have the following signature:

  Method Sample(pReq As RequestClass, Output pResp As ResponseClass) As %Status
  

  

  Here Sample is the name of the method, RequestClass is the name of a request message class, and ResponseClass is the name of a response message class. In general, these methods will refer to properties and methods of the Adapter property of your business operation.

• For other options and general information, see Defining a Business Operation Class.

The following example shows the general structure that you need:

Class EEMA.NewOperation1 Extends Ens.BusinessOperation 
{
Parameter ADAPTER = "EnsLib.EMail.OutboundAdapter";

Parameter INVOCATION = "Queue";

Method SampleCall(pRequest As Ens.Request,
                  Output pResponse As Ens.Response) As %Status
{
  Quit $$$ERROR($$$NotImplemented)
}

XData MessageMap
{
<MapItems>
  <MapItem MessageType="Ens.Request">
    <Method>SampleCall</Method>
  </MapItem>
</MapItems>
}
}

Creating Message Handler Methods

When you create a business operation class for use with EnsLib.EMail.OutboundAdapterOpens in a new tab, typically your biggest task is writing message handlers for use with this adapter, that is, methods that receive production messages and then send email messages via an SMTP server.

Each message handler method should have the following signature:

Method Sample(pReq As RequestClass, Output pResp As ResponseClass) As %Status

Here Sample is the name of the method, RequestClass is the name of a request message class, and ResponseClass is the name of a response message class.

In general, the method should do the following:

1. Examine the inbound request message.

2. Create an email message to send; for information, see Creating Email Messages.

3. Optionally call the AddRecipients(), AddCcRecipients(), and AddBccRecipients()methods of the Adapter property of your business operation. These methods add email addresses to the To:, Cc:, and Bcc: headers when you send the email message. These methods are discussed after these steps.

4. Call the SendMail() method of the Adapter property of your business operation:

       Set tSc=..Adapter.SendMail(email,.pf)
   
   

   

   This method is discussed after these steps.

5. Examine the response.

6. Use information in the response to create a response message (an instance of Ens.ResponseOpens in a new tab or a subclass), which the method returns as output.

   For information on defining message classes, see Defining Messages.

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

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

Available Methods

The adapter provides the following methods:

SendMail

Method SendMail(pMailMessage As %Net.MailMessage,
                Output pFailedRecipients As %ListOfDataTypes) As %Status

Given an email message, this method sends the message by means of the configured SMTP server. It returns, as output, as list of failed recipients, if the SMTP server returns this information.

AddRecipients

Method AddRecipients(pMailMessage As %Net.MailMessage,
                     pRecipients As %String)

Given an email message, this method adds the listed email addresses to the To: header of the message.

AddCcRecipients

Method AddCcRecipients(pMailMessage As %Net.MailMessage,
                       pRecipients As %String)

Given an email message, this method adds the listed email addresses to the Cc: header of the message.

AddBccRecipients

Method AddBccRecipients(pMailMessage As %Net.MailMessage,
                       pRecipients As %String)

Given an email message, this method adds the listed email addresses to the Bcc: header of the message. When sending an email there must be at least one address in the To: or Cc: header.

ContinueAfterBadSendSet

Method ContinueAfterBadSendSet(%val As %Integer) as %Status

If %val is true, the adapter continues to send the message if one or more of the recipients have an invalid address. The default is true.

Example

A method might look like the following:

Method SendMultipartEmailMessage(pRequest As EEMA.MultipartEmailMsg,
Output pResponse As Ens.Response) As %Status
{
    Set part1=##class(%Net.MailMessage).%New()
    Do part1.TextData.Write(pRequest.Message1)
    Set part2=##class(%Net.MailMessage).%New()
    Do part2.TextData.Write(pRequest.Message2)
    Set part3=##class(%Net.MailMessage).%New()
    Do part3.TextData.Write(pRequest.Message3)

    Set email=##class(%Net.MailMessage).%New()
    Set email.Subject=pRequest.Subject
    Set email.IsMultiPart=1
    Do email.Parts.SetAt(part1,1)
    Do email.Parts.SetAt(part2,2)
    Do email.Parts.SetAt(part3,3)

    Set tSc=..Adapter.SendMail(email,.pf)
    Set pResponse=##class(EEMA.EmailFailedRecipients).%New()
    Set pResponse.FailedRecipients=pf

    if pf.Count()'=""
    {
        set count=pf.Count()
        for i=1:1:count
        {
            $$$TRACE("Failed recipient:"_pf.GetAt(i))
            }
        }

    Quit tSc
}

For information on creating email messages, see Creating Email Messages.

Adding and Configuring the Business Operation

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

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

2. Enable the business operation.

3. Specify an SMTP mail server and credentials needed to access it.

4. Optionally specify additional addresses for the email messages.

5. Run the production.

See Also

• Creating Email Messages

• Settings for the Email Outbound Adapter