Creating Message Handler Methods

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 the next section.