Overview

Skill Level: Intermediate

Prerequisites

Use Transact XML Message Scripting to create and send dynamic email messages to contacts.

Learn about message scripting for transactional messages and view the list of best practices.

Email message scripting allows for dynamic creation of email messages to contacts. The current version of this feature focuses on transactional emails and is applicable only to XML-based Transact, i.e. HTTP and Batch. Email message scripting is largely based on Handlebars, the popular open source templating framework. While not everything is supported, custom extensions are available. Many of the basic features of scripting can be experimented with at http://tryhandlebarsjs.com/.

Note: 

This document assumes that you are already familiar with the basics of Watson Campaign AutomationTransact XML. 

   

Recommendations

  • The script context structure must match the layout of the template.
  • Minimize logic in the template. If the script context structure properly matches the layout of the template, then most logic is eliminated.
  • Do not use standard profile personalization in the body of scripted messages. For example, %%FirstName%%. However, you can use standard profile personalization in the Mailing settings of a scripted template, including fields such as Subject line, From name, From address, and Reply-to address.

Step-by-step

  1. Getting started with Transact XML Message Scripting

    Before you can include message scripting in transactional emails, an organization administrator must enable this feature. Then, you can create a transactional email by using the email content builder.

    Enabling Transact XML Message Scripting

    Before the Transact email creator can add message scripting in an email, the organization administrator must enable Transact XML Message Scripting in Organization Settings.

    About this task

    Complete the steps to enable message scripting.

    Note: 

     Transact XML must be enabled in an organization before an organization administrator can enable Transact XML Message Scripting.

      

    Procedure

    1. In Watson Campaign Automation, go to Organization Settings.
    2. Click Mailing Settings and then click Edit.
    3. Select Enable Scripting.
    4. Click Save

    Creating the Transact email using message scripting

    Learn how to add a scripted template and script context to a transactional email.

    Before you begin

    About this task

    See Scripting Basics for details.

    Procedure

    1. Go to a Mailing template and create the Transact email. For more information, watch this video: How to create a mailing
    2. In the template, click Source and then paste the scripted template in the editor.
    3. In Preview, an JSON Scripting Context panel appears when scripting is detected in the editor. Enter the JSON scripting context.
    4. Click Test to ensure that the context is acceptable.
    5. If you want to edit the scripting context, click Change JSON Scripting Context and then click Refresh to update the preview.
    6. Save the email.
    7. Preview the script.

    Learn more:

  2. Understanding message scripting basics

    Learn about scripted templates and script context that are needed for message scripting.

    Transact email message scripting requires two components to render a complete email ready for sending.

    • Scripted template: An HTML document that contains both static HTML markup and the scripting code inside what are often described as mustaches {{ … }}.
    • Script context: Data that is provided to the script that renders the template’s dynamic results. We recommend that you use JSON personalization fields in the script context.

    JSON versus standard Transact XML personalization fields

    You can use standard Transact XML personalization fields to provide the script context for many kinds of email templates. However, JSON is the preferred format. This format can be used in more complex templates, such as layouts that involve nested data or looping and is a flexible way to model data to match the layout of even the most sophisticated templates.

    Table 1. Comparing personalization field formats for context data

    JSON  Transact XML 
    • Data is not saved to the Transact database custom columns*
    • Can provide a value as a number

    *You can provide JSON and XML personalization fields if you want the data saved in the Transact database custom columns.

    • Data is saved to the Transact database custom columns
    • Cannot provide a value as a number

    Script context fields

    The following fields are available in the script context:

    • MAILING_ID: The active Mailing ID for the group of automated messages.
    • FORWARD_INFO: Always set to an empty string.
    • JOB_ID_CODE: The encoded version of the Job ID. In Transact, this is the same as the Report ID.
    • RECIPIENT_TYPE: Always set to zero.
    • RECIPIENT_ID: The URL-encoded version of the encoded Recipient ID.
    • RECIPIENT_CODE:
    • mailing tracking level unique: The URL-encoded version of the encoded Recipient ID.
    • mailing tracking level unique: Set to zero.

     

    • OPT_OUT_VERP: the value based on the Mailing ID, Recipient ID, Job ID,
      and sending opt-out domain.

    Scripted template example

    View an example of a scripted template that is used in message scripting.

    Example

    Add a scripted template to the transactional email. The email recipient sees the scripted template in the message body.

    /*Code Goes Here*/<html><header><title></title></header>
    <body>
    Hello {{first}},<br/>
    {{#if country }}
    You are from {{country}}.<br/>
    {{else if favnum}}
    I don't know where you are from, but your favorite number is {{favnum}}.
    {{else}}
    Sorry, I don't know where you are from or what your favorite number is.
    {{/if}}
    </body></html>

    Script context examples

    Compare examples of script contexts that are used in message scripting and view the output.

    Transaction XML with JSON Script Context

    <XTMAILING>
    <CAMPAIGN_ID>4503824</CAMPAIGN_ID>
    <RECIPIENT>
    <EMAIL>watson@silverpop.com</EMAIL>
    <BODY_TYPE>HTML</BODY_TYPE>
    <SCRIPT_CONTEXT><![CDATA[
    {"first": "Watson",
    "country": "Canada",
    "favnum":"2"
    }
    ]]>
    </SCRIPT_CONTEXT>
    </RECIPIENT>
    </XTMAILING>

    Equivalent Transaction XML with Standard Personalization

    <XTMAILING>
    <CAMPAIGN_ID>4503824</CAMPAIGN_ID>
    <RECIPIENT>
    <EMAIL>watson@silverpop.com</EMAIL>
    <BODY_TYPE>HTML</BODY_TYPE>
    <PERSONALIZATION>
    <TAG_NAME>first</TAG_NAME>
    <VALUE>Watson</VALUE>
    </PERSONALIZATION>
    <PERSONALIZATION>
    <TAG_NAME>country</TAG_NAME>
    <VALUE>Canada</VALUE>
    </PERSONALIZATION>
    <PERSONALIZATION>
    <TAG_NAME>favnum</TAG_NAME>
    <VALUE>2</VALUE>
    </PERSONALIZATION>
    </RECIPIENT>
    </XTMAILING>

    Resulting HTML

    The contexts generate the same HTML results.

    <html><header><title></title></header>
    <body>
    Hello Watson ,<br/>
    You are from Canada.<br/>
    </body></html>
  3. Using Handlebar helpers in message scripting

    Use these basic Handlebar helpers in your message scripting template.

    List of basic helpers

    Message scripting uses several helpers to provide much of the function that is needed for flexible templates. The following list contains helpers that are currently supported.

    • The if helper is used to conditionally render a block of content.
    • The else helper is used to specify block of content that is returned if the expression returns a false value.
    • The unless helper is used as the inverse of the if helper.
    • The each helper is used to iterate over a list. Also known as looping.

    For detailed documentation for these helpers, go to Built-In Helpers.

    Using custom helpers in message scripting

    Message scripting provides a growing list of custom helpers. The following information identifies custom helpers that are supported.

    List of custom helpers and their examples

    #xif (Extended if)

    Use the Extended if helper to compare a context field value to a constant string, number, or Boolean value that uses a subset of JavaScript operators. Extended if also works with {{else}} blocks.

    Note: 

    If you do not want the system to evaluate numbers and Boolean values as strings, use JSON context. The operators that are currently supported are “==”, “!=”, “>=”, “<=”, “>”, and “<”.

      

    Example 1: xif / else xif / else

    {{#xif 'Age == 18' }}
    Vote for your first time!<br/>
    {{else xif 'Age > 18' }}
    Keep voting<br/>
    {{else}}
    Can't vote yet<br/>
    {{/xif}}

    Example 2: nested xif

    {{#xif 'gender=="male"' }}
    {{#xif 'age=>”18"' }}
    Have you registered for the selective service?<br/>
    {{/xif}}
    {{/xif}}

    capitalizeFirst

    Capitalizes the first word of a field value or string constant.

    Given {{capitalizeFirst myField}}
    with a context of {“myField”:”some value”}
    Result: Some value

     

    capitalizeEach

    Capitalizes each word of a field value or string constant.

    Given{{capitalizeEach myField}}
    with a context of {“myField”:”some value”}
    Result: Some value

     

    upperCase

    Capitalizes all letters of a field value or string constant.

    Given{{upperCase myField}}
    with a context of {“myField”:”some value”}
    Result: SOME VALUE

     

    lowerCase

    Enters all letters of a field value or string constant in lowercase letters.

    Given{{lowerCase myField}}
    with a context of {“myField”:”SomE ValuE”}
    Result: some value

     

    set

    Creates a new named value in the current context.

    Given{{set “title” (upperCase myField) }}
    My title is{{title}}with a context of{“myField:”SomE ValuE”}
    Result: My title is SOME VALUE

     

    debug

    The debug helper can be useful for testing and debugging a script by displaying the names and values in the current context of the script.

    Given{{debug}}
    with a context of{“firstName:”foo”,”lastName”:”bar”}
    Result: Current context :{firstName=foo, lastName=bar}

    Using loops in Handlebar helpers

    See examples of how you can iterate over a list, also known as looping, by using the each basic helper.

    Example of a loop

    This example shows how to use loop scripting to display a hardware store’s inventory and pricing.

    Given the following script

    <html><head><title></title></head>
    <body>Loop scripting example<br />
    {{#each items}}
    Name: {{itemName}}, Price: {{price}}<br />
    {{else}}
    No items available.<br/>
    {{/each}}
    </body></html> 

    With the following context

    {"items": [
    {"itemName":"hammer","price":"10.49"},
    {"itemName":"screwdriver","price": "11.19"}]}

    Result

    <html><head><title></title></head>
    <body>Loop scripting example<br />
    Name: hammer, Price: 10.49<br />
    Name: screwdriver, Price: 11.19<br />
    </body></html>

    Example of Nested Loops

    This example illustrates the power of message scripting. The key is to have the right script context as the model for your scripting code.

    In this example, a store has a number of departments. Each department can have a number of items. Some of these items from any department are on sale and those items are marked as sales items. When a department does not have any items on sale, display a default message.

    Given the following script

    <html><head><title></title></head>
    <body>Nested loop scripting example<br />
    {{#each departments }}
    Department: {{name}}<br />
    {{#each items}}
    {{#if special}}
    <span style="color:#FF0000;">Sale !!</span>&nbsp;
    {{/if}}
    Name: {{itemName}}, Price: {{price}}<br />
    {{else}}
    No items available for this department.<br/>
    {{/each}}
    {{/each}}
    </body></html>

    With the following context

    {"departments": [
    {"name": "Hardware",
    "items": [
    {"itemName":"hammer","price":"10.49","special":"sale"},
    {"itemName":"screwdriver","price": "11.19","special":""}]},
    {"name": "Candy",
    "items":[
    {"itemName":"ButterBits","price":"3.49","special":"sale"}]},
    {"name": "Housewares", "items":[]}
    ]}

    Result

    <html><head><title></title></head>
    <body>Nested loop scripting example<br />
    Department: Hardware<br />
    <span style="color:#FF0000;">Sale !!</span>&nbsp;
    Name: hammer, Price: 10.49<br />
    Name: screwdriver, Price: 11.19<br />
    Department: Candy<br />
    <span style="color:#FF0000;">Sale !!</span>&nbsp;
    Name: Butter Bits, Price: 3.49<br />
    Department: Housewares<br />
    No items available for this department.<br/>
    </body></html>

    Using comments in helpers

    See how to use comments in the script context.

    Text inside these mustaches {{!– –}} or {{! }} are comments that will not show in the rendered message. Any comments that contain }} or other scripting tokens should use the {{!– –}} syntax.

  4. Troubleshooting and support for Transact XML Message Scripting

    Read this section to learn how to resolve message scripting issues in your transactional emails.

    Issue with numeric or boolean helpers

    Symptoms

    You’re having problems trying to do numeric or boolean equality checks or comparisons.

    Resolving the problem

    • Use JSON scripting context, instead of XML personalization fields.
    • If you are using AGE, enter a numeric number in the JSON scripting context.
      Example with code
      {{#xif ‘Age >= 18’ }}Vote!{{/xif}}
      Example with context
      {“Age” : “3”}, the result would be “Vote!”
      Example with context
      With context {“Age”: 3}, the result would be empty string

    Do not see scripted personalization

    Review the list to resolve this issue.

    Symptoms

    Scripted personalization does not show in the transactional email.

    Resolving the problem

    Verify the following items to resolve this issue:

    • Is the field in your context (either JSON or XML personalization field)?
    • Does the field name case match between your scripted code and your context data?

    Error: Too many tokens found, expecting [number] in expression [expression]

    Recommended. The shortdesc element is optional and can be either on its own or inside an <abstract> element.

    Symptoms

    The error is generated from the code. For example:{{#xif ‘PERSON AGE >= 18’ }}Make sure you vote!{{else}}No voting yet{{/xif}}

    Resolving the problem

    • Do not include a space in PERSON AGE in the xif expression.
    • Trying to use quotes around PERSON AGE in the expression does not resolve the problem.For example, suppose you have the code: {{#xif ‘”PERSON-AGE” >= 18’ }}Make sure you vote!{{else}}No voting yet{{/xif}}

      A context of {“PERSON-AGE”: 21} results in an error: “PERSON-AGE” was not found in the current context. This error occurs because it is literally expecting “PERSON_AGE” with the quotes to be the field name in the scripting context.

      A context of {‘”PERSON-AGE”’: 21} (where PERSON_AGE is surrounded by double quotes within single quotes) renders the scripting xif code without error.

    User response: Optional. When you have particular actions that are performed by particular users, use one or more of the ts*Response elements.

Join The Discussion

Your email address will not be published. Required fields are marked *