Contact us Blog

Generating email messages containing sublists

Background

Before reading this document, please look through our documentation about the general concepts used by Apsona's document generation tool, which discusses the user interface and some of the underlying concepts. You might also find it helpful to read the documentation about generating lists in Word documents. The ideas used for creating email templates with lists are quite similar to the ones used for Word documents.

Overview

Often you would want to generate email messages that include sub-lists. For example, consider creating an invoice as an email message. Below is an example of a simple invoice email as it would appear to an email recipient in her Google mail account. Here we have a header area containing the name and email address of the customer, and a detail area containing alist of items in the invoice. To prepare such an email message as a template, we begin with creating an Email Template record in Salesforce, by navigating to Setup - Communication Templates - Email Templates and clicking the New button. When you click the "Edit HTML Version" button, you can provide the HTML markup for the template. The HTML markup specifies the layout of the invoice, and we include place-holders specifying the parts of the markup where the data from your Salesforce database will appear. In the above example, the sender's company name, logo, address and other boiler-plate text are all coded directly into the invoice. But the recipient Customer Name, Email, Invoice Date, and the data values in the list of items are produced from data in the Salesforce database and filled into the appropriate positions in the HTML markup.

Below is the HTML template that produced this invoice, as it appears when you view it within Salesforce when you navigate to Setup - Communication Templates - Email Templates and click the template in question. If you like, you can download this markup to use it as a starting point for your own templates.

Merge fields

In the above HTML template, we have several place-holders, or "merge fields," marked by double-curly delimiters. For example, {{CustomerName}} is a merge field which will be replaced by the actual customer name when the email is generated. Similarly, the above template contains merge fields {{InvoiceDate}} and {{Email}}.

Apsona's email template processor assumes that merge fields begin with two left-curly symbols, end with two right-curly symbols and contain only alphabets, numerics and underscores. They cannot contain spaces, tabs or other special characters. If you create a merge field that doesn't conform to these conventions, the email processor will not recognize it as a valid merge field, so it will not be available for mapping. Other than the character rules above, there is no specific requirement as to merge field names. You can make up any names you want, and when you create the merge action, you can correlate the names you provided with the names of the data fields available (more on this below).

There are a few exceptions, special cases that Apsona recognizes. In the above template, there are three examples of such exceptions: the merge fields {{TableStart:Items}}, {{TableEnd}}, and {{Items:Amount:Sum}}. The three merge fields {{CustomerName}}, {{Email}} and {{InvoiceDate}} are fields for which there is only one value per generated email (e.g., there is only one customer to whom the invoice is addressed). By contrast, the fields {{Name}}, {{ServiceDate}} {{Amount}} that appear in the list area of the markup will each be replaced by more than one value, because the entire row containing those three fields must be replicated as many times as there are invoice line items. To mark such a block of repeated rows, Apsona uses the special {{TableStart}} and {{TableEnd}} merge fields. The {{TableStart}} field must appear in the leftmost table cell of the row, and the {{TableEnd}} field in the rightmost row. Apsona treats all the merge field references which appear between those two "end-marker" fields as being part of the repeated block. Each such repeated block is called a record group, and in the above example, there is just one record group named Items. Note that you can have multiple record groups in a template, each with its own name.

The {{TableStart}} in the above template actually looks like {{TableStart:Items}}. The name Items following the colon is also something we make up when we prepare the template. It specifies a name for the list of records to show, and when we build the merge action, we will associate that list with the data source from which the list will be obtained.

And then there is the {{Items:Amount:Sum}} merge field, which is a place-holder that represents the sum of the Amount field of the Items list, which we use to show the total invoice amount.

Mapping the fields in the merge action

When you use the above template to create a merge action for generating emails, the third step of the merge action builder (for matching the data fields with the template merge fields) looks like the screen below. Here we have mapped the {{CustomerName}} merge field to the Account Name field of the Account object, and the {{InvoiceDate}} field to a built-in field that provides the current date. The Items record group has been mapped to the Opportunity object, so that its three fields Name, ServiceDate and Amount come from the Name, Close Date and Amount fields of the Opportunity object, respectively.

Finally, note the choice in the Linkage area at the bottom of the mapping. When producing the sub-list, Apsona must retrieve only those Opportunity records which match the Account for which the invoice is meant. This correlation between Opportunity and Account happens based on the Account ID lookup in the Opportunity object. So we have chosen the linkage "Account ID matches Opportunity.Account". There may be situations where a different choice of linkage is more appropriate; therefore, Apsona offers up all the possible linkage choices, and lets you choose the correct one.

Plain-text email messages

Occasionally, you would want to send email in plain text format instead of HTML, e.g., when the email is purely transactional. Apsona's email template processor includes support for lists in plain-text email messages. To prepare a plain-text template, you simply select "Text" as the type of email template when you create it in Salesforce, as in the screen shot below.