Rendering Templates with Data Feeds

Iterable uses data feeds to populate campaign messages with data pulled from web services. Since Iterable can pass parameters to these services, each data feed query can fetch data relevant to a specific user. This makes it possible to use dynamically-queried data to send personalized, relevant messages.

In Iterable, a single template can reference one or many data feeds, which means that data from multiple sources can be used to customize a single message. Iterable data feeds support web services that return JSON, XML, RSS, or Atom data.

This document describes how to use data feeds in an Iterable campaign.

Set up a web service

A data feed defined in Iterable retrieves its data by querying a web service.

For example, the JSON data below might come from a web service that returns product recommendations based on a user's prior purchases. The data includes:

• Information about a user's past purchase
• Three recommended products, each of which includes a name, description, price, and image URL.

{
  "pastPurchase": "Hot Dog Halloween Outfit for Cats",
  "suggestedProduct": [
    {
      "name": "Deluxe Cat Tree",
      "description": "A jungle for your favorite feline buddy",
      "price": 160,
      "imageUrl": "http://img-cache.cdn.gaiaonline.com/0b4be3af7262e023cce39cffa697d4cd/http://i324.photobucket.com/albums/k331/michellepaints/CC_Cat_Tree.jpg"
    },
    {
      "name": "Catnip Mouse Toy",
      "description": "Cats go absolutely crazy for this realistic mouse toy!",
      "price": 4,
      "imageUrl": "http://www.crystalclearpet.com/shop/treats/images/catnip-large-mouse-11077a.jpg"
    },
    {
      "name": "Set of 3 Furry Sticks",
      "description": "Dangle this enticing toy in front of your kitty!",
      "price": 5,
      "imageUrl": "http://i01.i.aliimg.com/wsphoto/v1/1944996867/Freeshipping-font-b-Rabbit-b-font-font-b-Fur-b-font-Strip-Funny-Cat-Stick-Cat.jpg"
    }
  ]
}

A sample web service for this data exists here: http://static.iterable.com/sample-data-feeds/sample_data_feed.json (click the URL to see the JSON it returns).

Note: The web service queried by a data feed should use a response charset of UTF-8.

Customize the response for each user

To personalize the data returned by a data feed for each of a campaign's recipients, pass user-specific merge parameters to the data feed's URL. A data feed URL that uses merge parameters might look something like the following:

http://host/sample_data_feed.json?{{#urlEncode}}email={{email}}{{/urlEncode}}

Here, the recipient's email is passed in double curly braces (Handlebars), and it is URL-encoded by the {{#urlEncode}}helper. The web service hosted at this URL must expect the passed-in URL parameters and use them to look up personalized data.

Before making a data feed query, Iterable replaces any parameters found in its URL with values from a user's profile or with data included on the event that triggered the campaign (using the events track API call). This makes it possible to use fields other than email (such as userId).

Note: Certain merge parameters related to the campaign itself, like {{campaignId}} and {{campaignName}}, are generated at campaign send time. These fields may appear blank when previewing the template with data.

Data feed HTTP response codes

When querying a data feed URL, Iterable interprets the resulting HTTP response code as follows:

Wikipedia provides more detail about HTTP status codes.

Data feed response times

Iterable expects a data feed to return a complete response within ten seconds; otherwise, it will retry the query three minutes later. After five unsuccessful query attempts, Iterable will skip sending the message to the user in question.

Create a data feed to query the web service

To use data feeds in a campaign, first define the data feeds in Iterable:

• Navigate to Integrations > Data Feeds
• For each necessary data feed, click the + CREATE NEW FEED button and provide the required information:

• Name: The name of the data feed. Used to select it when using it in a campaign.
• Format: The type of data the data feed will query from a web service.
• Template Handlebars Alias: An alias that can be used by a template to reference data from this data feed.
• For example, if the data feed returns a field1.field2 property, setting an alias of my_alias allows a template to reference this data as [[my_alias.field1.field2]] . Otherwise, the data would be available as [[field1.field2]].
• Data field aliases clarify which data feed an expression references, especially in situations where a single template uses multiple data feeds.
• Authorization Token: An authorization token to include with the data feed request.
• Click + ADD NEW CUSTOM HTTP HEADER to add custom HTTP headers required by the URL (as necessary).

Reference data feeds in a template

To reference a data feed in a template:

• Create a template by navigating to Templates > Create New Template (or do this while creating a campaign).
• When entering text for the template's content, reference a data feed with either:
  • Double square brackets 
    • Double square brackets are the default way to access data feed data. 
    • For example, the following expression references the price of the first item in the suggestedProduct array of the data feed defined above: [[suggestedProduct.[1].price]].
  • Double curly braces
    • Double curly braces are the default way to reference user profile data.
    • However, if Advanced options> Enable template generation using data feeds… > Merge the data feed and user contexts is enabled for the template, double curly braces can reference both user profile data and data feed data.
    • For example, the following code references the price of the first item in the suggestedProduct array of the data feed defined above: {{suggestedProduct.[1].price}}.
    • If the expression contained in double curly braces can reference either a value from the user's profile or a data feed, Iterable will use the user profile data.
      • Because of this, it's possible to write a single Handlebars expression that pulls user profile data when it's available, but otherwise uses data feed data.

Using aliases to reference data feed data

Templates can use aliases to reference data feed data, so long as:

• The data feeds in question have aliases defined in Integrations > Data Feeds.
• In the template, Advanced options > Enable template generation using data feeds… > Use data feed alias is enabled.

For example, a template might reference a data feed having alias my_alias by using syntax such as: [[my_alias.suggestedProduct.[1].price]].

Example template

Here is an example of a template that uses data from both a data feed and a user profile:

Integrate data feeds into a campaign

Iterable can query data feeds at campaign send time (once per recipient, to maximize personalization) or at campaign design time (only one time, minimizing load on the server that hosts the web service). These two options are described in more detail below.

Querying data feeds at campaign send time (once per recipient)

The most common way to fetch a data feed is at campaign send time, once per recipient. With this approach, data from the feed is both up-to-date and customized for the recipient (assuming user-specific merge parameters are included in the data feed's URL).

To have a campaign query data feeds at send time for each recipient:

• When creating a campaign, on the Select Template step, select the template whose contents reference the data feeds in question.
• Scroll to the bottom of the screen and click CONTINUE TO DESIGN.
• Navigate to the Advanced options tab.
• Select data feeds:
• Check Enable template generation using data feeds....
• Click the text input below the checkbox to view a list of the data feeds available to the project.
• Select all necessary data feeds (select one or many, as necessary).
• Set other data feed options on the Advanced options tab:
• Aliases 
  • If the template's contents use aliases (as defined for each data feed in Integrations > Data Feeds) to reference data feeds, select the Use data feed alias checkbox.
  • For example, a data feed might have an alias such as my_alias. With Use data feed alias enabled, the template can access the data feed's data as follows: [[my_alias.field1.field2]]. Otherwise, this data would be available as [[field1.field2]].
  • Aliases can make templates more readable and provide a way to disambiguate between two similar data feeds.
• Merging data feed and user contexts
  • If the selected template uses curly braces to reference data feeds, enable Merge the data feed and user contexts.
• Caching
  • To cache the template's data feeds (to reduce load on the servers that host them), select the Cache data feed response checkbox.
  • For each recipient, Iterable will determine the data feed URL to query by substituting parameters from the user's profile into the data feed's pre-defined URL (as necessary). If that URL has been cached within the past hour, the cached response will be used; otherwise, Iterable will query the URL.
  • Note: Iterable will re-cache the data feeds for a template every hour while sending the campaign.
• Save the template by scrolling to the bottom of the page and clicking SAVE TEMPLATE.
• Preview how the template will render with data feed data:
  • Click the PREVIEW button and select Preview with data.
  • On the Preview with data screen, in the Load user data text input, enter an email address associated with a user profile. Click LOAD USER DATA.
  • Under Load data feed data, select the data feed to use while previewing the template. Click LOAD FEED, and the data feed will load.
    • Notes:
      • It is only possible to preview one data feed at a time. If your template relies on multiple data feeds, preview each one sequentially.
      • If your template uses an alias to reference a data feed, for the Preview with data screen to work properly you must manually edit the feed's loaded data and wrap it in a top-level element with the same name as its alias. For example, for a data feed having alias my_alias, wrap the data as follows:
        { "my_alias": { "field1": { "field2": "testing" } } }
      • 
• Examine the preview to make sure it looks as expected.
• NOTE: If the data feed changes prior to the campaign being sent, the actual campaign will differ from the preview.

Querying data feeds at campaign creation time

Alternatively, Iterable can query a data feed one time during campaign setup, immediately integrating that data into the campaign's copy of the template. This minimizes load on the server that hosts the data feed, since the HTTP request is made only one time. However, with this approach it is not possible to personalize the data feed request for a specific user.

To query a data feed during campaign creation:

• When creating a campaign, on the Select Template step, click on the template whose contents reference the data feed in question.
• Scroll to the bottom of the screen and click Use Template With Data Feed....
• In the Select data feed to merge into template modal window that appears, select the data feed from which data should be queried. Click USE THIS DATA FEED.
• Note: When querying a data feed at campaign creation time (as opposed to send time), it is only possible to use reference one data feed in a template.
• To preview the template:
• Click the Preview button, and choose Preview with data.
• Verify that the template renders as expected.

Finish setting up the campaign

On the bottom of the Edit Template screen (part of campaign setup), click SAVE & CONTINUE TO REVIEW to finish setting up the campaign.