Working with communication templates

Quick Tutorial Full Training

The following can be done with communication templates:

  • Compose an email template
  • Choose email recipients by selecting an IQA query
  • Add query data sources to the template allowing you to insert merge fields from additional data sources in the message
  • Send an email directly to the recipients

To define a new email template, go to Marketing > Communication templates > New > Communication. Use the following information to help you define a new template and understand the available options.

Header tab

Use the Header tab to define basic information for the communication. Review the following to understand specific details about the Header tab fields:

  • From - Designates who the email is from. The From email address cannot exceed 64 characters. If the email address is provided through a query-supplied value, ensure that the supplied email does not exceed 64 characters. The email address will be shortened when the email is sent if it exceeds the maximum character length.
  • To - If every recipient address entered in the To field cannot be resolved, then the communication will fail to send. If one address in the To field is valid then the communication will send to that particular address and ignore any addresses that could not be resolved.
  • CC and BCC -
    • If you want to include additional addresses to which the communication can be sent without sending additional copies and creating additional interaction log entries, enter those addresses in the Cc or Bcc field. Any addresses entered in the Cc or Bcc fields will be included on each copy of the communication but will not cause additional copies to be sent.
    • Example: You enter {#party.Email} and anotheremail@example.com in the To field, meaning one copy of the communication is sent to the recipient’s primary email address, and a second copy is sent to anotheremail@example.com. The recipient will have two entries in the communication log for the two copies of the communication. To send only one copy of the communication with one interaction log entry, enter {#party.Email} in the To field, and add any additional email addresses in the Cc or Bcc fields.

    • If you would like a staff person to receive the order confirmation template, you must enter their email address in the Bcc field of the order confirmation template.
  • Subject - The subject line presented to recipients. The Subject cannot contain the < > symbols. If using a Client key that is licensed to a demo or test system, the Subject contains iMIS Demonstration.
  • Type - Provides recipients with classes of emails to opt in and out of. See Managing communication preferences.

Defining friendly names

By default, email addresses display in the From, To, Cc and Bcc fields. If you would like to display a friendly name, simply enter the friendly name in the field before the email address. For example, “Your Organization Name <info@yourorganization.com>” will display to recipients as “Your Organization Name.”

Note: For advanced email, 50 characters is the maximum length that can be used for the friendly name. If the friendly name is provided through a query-supplied value, ensure that the supplied name does not exceed 50 characters. The friendly name will be shortened when the email is sent if it exceeds the maximum character length.

Recipients tab

Click the Recipients tab to select the contacts to whom you will send the email:

  1. Click Select to select the query you want to use as the primary data source. This query retrieves the contacts to whom you will send email. By default, the SelectedContact query, which retrieves the selected contact (the contact you are signed in as or working on behalf of) is the primary data source. See Creating recipient queries for communications for more information.
  2. Note: The query must have a column that identifies the contact’s ID. Also, if the query contains filters with required or optional prompts, it must have default values because they cannot be changed when the email is sent.

  3. Deselect the names of any contacts that you do not want to receive the email.
  4. Note: If the query contains filters with required or optional prompts, you cannot deselect recipients from the list.

  5. To continue composing your email template, click Return to Compose.
  6. Two parameters in your communication are auto-filled. The To field includes the parameter {#party.Email}, and the salutation field includes {#party.FirstName}. These values, along with any other party fields, will only be resolved if your recipient query has a valid column that identifies the contact's ID.
  7. Note: It is possible for more than one person or organization to have the same email address. In this case, each recipient will still receive the email regardless.

Data sources tab

Use the Data sources tab to add additional data sources to the email template. Fields from the data sources can be inserted in the email message. The party data source, which provides basic information about email recipients, is a default data source. Do the following:

  1. Click Add data source.
  2. Select a query.
  3. If needed, change the Alias for the data source. The Alias is how you refer to the data source when creating the email communication. Fields from the data source will be prefixed by the Alias in the Insert field drop-down. The default Alias is the query name.
  4. Important! When creating a new communication template or editing an out-of-the-box template, the Data sources tab will have a Default query with an Alias of party. Do not remove this data source! You may add additional data sources, but the Default data source should remain to ensure that the email is received.

  5. Click OK.
  6. To edit a saved data source, click its edit icon and make the necessary changes. If a filter in the additional data source matches a display column in the recipient query, the property is used to link the two queries. For example, if the additional data source uses ContactKey as a filter, and the recipient query uses ContactKey as a display column, their information can be linked. On the filter tab in the additional data source query, the Comparison type should be set to Equal, and In Search? should be set to Required.
  7. If the additional data source is providing data about individual recipients, include a filter for an ID property (ID or PartyID) in the data source definition, then include the same property on the Display tab of the source query with an alias of PartyId. This will ensure that the data source is linked to the Recipient query.
  8. When the additional data source does not use filters or uses non-matching filters, the same data will be returned for each recipient. These data sources are useful when you want to insert standalone information, such as the name of a program administrator, that is not related to the recipient list in the email message.

    If an additional data source returns multiple data rows, a foreach statement can be used in the body of the communication to display data from each of the rows.

  9. Click Return to Compose.

Body tab

The Body tab offers many different features to help you customize the communication template.

Insert field drop-down

Use the Insert field drop-down to add fields to be merged for each recipient. Available fields include columns from the recipient query and added data sources and also commonly used contact properties. Any fields that are not found from the defined data source will resolve as blank.

The following are common insert parameters:

  • {#party.FirstName} - Use this parameter to address all recipients by their first name
  • {#party.Email} - Use this parameter in the To field to send the communication to all contacts in your query
  • Note: You can reformat these fields with a formatting string. To specify a format, add format="FORMAT_HERE" inside the brackets, with FORMAT_HERE specified by .NET Framework Standard Format Strings. For example: {#iqa.DataAdded format="d"}.

    Note: By default, inserted properties are HTML-encoded. This means that any HTML characters in your properties are rendered as plain text. Use the noencode attribute to ensure HTML markup is rendered in the browser.

    There are both Date/Time and Number formats available:

  • format="C" - Currency: Convert 123.456 to $123.46 ("C", en-US)
  • format="d" - Short date: Convert 6/15/2009 1:45:30 PM to 6/15/2009 (en-US)

    Example: {#ProgramItems.BeginDate format="d"}

  • format="D" - Long date: Convert 6/15/2009 1:45:30 PM to Monday, June 15, 2009 (en-US)
  • For more information on formatting types, please reference the .NET framework.

Using placeholders

Use placeholders within the content and the title to denote areas that will resolve against the data sources.

Placeholders can be used to populate attributes within HTML tags, such as the src attribute of <img> and <a> tags. Placeholders are specified using { } notation. For example:

{datasource[.property... ] [attributes]}

The {#...} placeholder embeds data into the content or title at the placeholder location. The placeholder consists of the following components:

  • datasource - The name of the data source.
  • property - (optional) The name of the property. Can be chained together using dot notation. For example, prop1.prop2.prop3. Where the property is a collection, a specific item can be accessed using [i] notation. For example, .Address[1] would return the item at index position 1 from the Address collection.
  • attributes - (optional) A space delimited set of attributes, some of which require values. Multiple attributes can be specified:
    • uppercase - Convert the data to uppercase.
    • lowercase - Convert the data to lowercase.
    • format - Format non-string values, such as format="d".
    • noencode - By default, inserted properties are HTML-encoded. This means that any HTML characters in your properties are rendered as plain text. Use the noencode attribute to ensure HTML markup is rendered in the browser.
    • Example: <strong>{#Party.FirstName noencode}</strong>

inserting LINKS

Use the Insert link drop-down to add many different types of links:

Inserting custom data using the foreach placeholder

To include repeating data in the body of email from an associated data source, use the {foreach} placeholder. For more information, see Using the foreach placeholder.

Note: To see a live example of the {foreach} placeholder in action, watch the Communication Creator - Advanced features video at the bottom of this page.

Adding attachments

Select Add attachment to include a PDF or RDL (SSRS report) from the Document System as an attachment to your communication.

Note: When opened as an attachment, reports containing subreports are not displayed properly in a PDF viewer. It is recommended that you do not send reports containing subreports as attachments.

  1. Select Add attachment and navigate to the Document System folder where the file will be saved.
  2. Click New > Adobe PDF or Reporting Services Template.
  3. Click Select to browse for the file.
  4. Select the file, then click Open.
  5. Enter a file Description, then click Upload.
  6. Select the file, then click OK.

See Attaching a Report Writer report to a communication template and Creating a communication with an attached SSRS report.

Previewing, saving, and sending communication templates

Review the following information for specific details about previewing, saving, and sending communication templates.

Preview

You must enter From and To addresses to preview the email. Click Preview to view a preview of the email for each recipient. Click Prev or Next to review the email for each recipient.

Saving

To save this email as a reusable template, click Save or Save As. The Document browser is displayed, allowing you to define a Name for this template. After the template is saved, the name you define for the template is shown in the editable Template name field. The email template is saved in the $/Common/Communications folder in the Document system.

All information in the template is included in the saved drafts including the recipient/query list, attachments, and message content. It is recommended to use a naming convention to identify your query in any saved email drafts. For example enter "All Members Thank You Communication" instead of "Thank you communication" to avoid any confusion about the content of the draft.

Sending

(optional) To send the email to the recipients immediately, click Send. Review the Communication Confirmation, then click Yes, Send Now or No, Go Back to make additional changes. A confirmation notification is displayed. The confirmation indicates that the number of messages attempted matches the number of results selected. Errors are listed individually explaining why the email was not sent.

To review the status of your communication job, go to the Communication logs (Marketing > Communication logs). For more information, see Communication logs.