AgileApps Support Wiki Pre Release

HowTo:Send Messages to Multiple Recipients

From AgileApps Support Wiki

For:   Designers
Level: Beginner
Time:  15 minutes

See more:
    ◾ HowTo Guides

There are many ways to send a single message to multiple recipients. This writeup summarizes the possibilities so you can choose the mechanism that is most appropriate for your application.

User-Controlled

When sending an email from a Case or from any other record in the system, a user can add as many recipients as they like.
Advantage: Infinite flexibility
Disadvantage: Requires manual effort that becomes excessive when duplicated my different users and/or repeated by the same user.
Learn more: Respond to a Case or Add a Note

Template-Controlled Addresses

When creating an Email Template, a comma-separated list of recipients can be specified.
Rules and Processes can then be used to send a message using that template. (Or for records other than Case records, the template to use can be selected by the user.)
There are multiple ways to do it:
  • Individual recipient addresses can be hard-coded into the To, Cc, or Bcc fields.
  • Template Variables can reference Lookup fields in the record to include email addresses from related Contacts and Users.
Advantage: Addresses can be taken from related Contacts and User records
Disadvantage: Each value is a single address, which is fine unless you need to send to a list or recipients.

List of Addresses in a Record

An Email Address field can be added to the object. For a given record, that field can contain a single email address or a comma-separated list of addresses. That email field can then used as a template variable in one of the template lists.
Advantage: Every record can have it's own unique set of addresses.
Disadvantage: Address values have to be added to every record.

Multiple Send Message Actions in Rule or Process

A Rule or Process can perform multiple actions, and each action can use a template to send a message using an Email Address field either in the record, or in a related record.
Advantage: The same template can be used with different sets of recipients.
Disadvantage: Each recipient gets their own copy of the message. They can't see who else got it, or engage in an email conversation with the other recipients.

List of Addresses in a Related Record

Sometimes, an object already contains a Lookup to an object that could be augmented with an email list. For example, if each incoming Case were assigned to an specific Department using a record that gave the name and telephone number of the department manager, then an Email Address field could be added to the Department object, and that value could be used as a variable in the Email Template.
Advantage: Every record is automatically associated with the appropriate list.
Disadvantage: Requires a related object that will always be targeted by a Lookup, when records are processed.

Using an External "Alias"

One or more of the addresses contained in an email field could also be an email alias--a list of email addresses maintained on a separate server.
Advantage: Ability to re-use a list that is already being maintained elsewhere.
Disadvantage: In general, this technique works only for an On-Premise Installation.
Because an email alias is generally maintained on an LDAP Server, and that server is typically deployed behind a firewall, for protection.

Using an "Internal Alias"

At this point, we've learned that an email address field can contain a comma-separated list of addresses. And we know that Contacts and User records (for example), contain an email address field.
Putting those two ideas together creates a third possibility: Create a "User" record who's email "address" is in actuality a list of addresses. Then:
  • That "user" could be specified as a recipient in a template.
  • It could be selected from a Rule or Process (assuming that there is a Lookup field that points to it).
  • The field value could be accessed programmatically, using a technique that will be described momentarily.

Store Addresses in a Configuration Object

As an example, you could create an object called 'Notifications that has two fields:
  • Category - a name you use to designate the kind of notification you are doing.
  • Recipients - An Email Address field that contains a single email address or a comma-separated list of addresses. (Or even email aliases, for an On-premise Installation.)
You can then use Rules and Processes to send an Email, specifying a template that uses the recipient-list specified by a given record.
Advantage: Highly flexible. Recipients can be changed by editing a record, rather than modifying a template. A list can be used in multiple templates.
Disadvantage: Requires setting up a configuration object.

Retrieve Addresses Programmatically

Using any of the previously-mentioned internal storage mechanisms for a list of email addresses, you can programmatically access that list and use the Java sendEmail or sendEmailUsingTemplate API to send a message to it.
This approach goes beyond the beginner stage, of course. But it's worth knowing that it exists--either to get someone more experienced involved, or to consider it for an initial project to begin honing your development skills.
Here's the kind of Java Class you'll need to write:
package com.platform.{YOURDOMAIN}.util;

import com.platform.api.*;

public class UtilityFunctions
{
   // Send a message to a "user" who happens to contain a list of email addresses
   public void sendMessage(Parameters p) throws Exception
   {
      // Get the ID of the current object and record
      String objectID = p.get("object_id");
      String recordID = p.get("id");  

      // Get the address list
      String userID = "USER_RECORD_ID_GOES_HERE";
      Result result = Functions.getRecord("USER", "email", userID);
      if(result.getCode() < 0) {  
         String msg = "Error accessing user alias.\n"; 
         Logger.info(msg + result.getMessage(), "UtilityFunctions");
         Functions.throwError(msg);
      }
      Parameters resultParams = result.getParameters();
      String userList = resultParams.get("email");

      // Send the message
      String subject = "PUT SUBJECT HERE";
      String message = "PUT MESSAGE HERE";
      result = Functions.sendEmail(objectID, recordID, userList, "", 
                                   subject, message, "", "");
      if(result.getCode() < 0) {  
         String msg = "Error sending message.\n"; 
         Logger.info(msg + result.getMessage(), "UtilityFunctions");
         Functions.throwError(msg);
      }
      Functions.showMessage("email has been sent");
   }
}
Advantage: Ultimate flexibility.
Disadvantage: Requires a small amount of code and the "wiring" to invoke it.
Learn more: Java Code Samples#Send an Email Message

Wrap Up

At this point, you've seen a number of ways to send a message to a list of users, along with the advantages and disadvantages of each approach. You should now be able to pick the approach that will work best for your application.