Carma Dynamic Content

Introduction

This document contains a description of how a campaign in Carma can contain dynamic content.

The reader should be familiar with Carma and have a working knowledge of general Carma concepts.

Definitions

Dynamic Content in Carma comes in two flavors; Design time content and Distribution time content.

Design time content i.e. when you actually create the communication

Design time content is a way to facilitate the creation of a campaign. If you, for instance, wants to include the latest top hits in your campaign you can use a special block into the campaign editor to retrieve the data from your system. The preferred format for this data is JSON, RSS or structured XML data.

Design time content is implemented in the template and needs to be coded by Compost. Contact support at support@compost.se if you need help implementing Design time content.

Distribution time content i.e. when the message is sent from Carma

Distribution time content is data that can be individualized for every contact. The data will be retrieved when the message is sent, so if you need data that is as updated as possible (e.g. current weather at the recipients location) this is the method you should use.

Carma will cache queries with the same parameters e.g. if all recipients has the same destination only one query will be sent to the 3rd party system. As this puts less strain on both Carma and you system you may want to structure your queries si they minimize the load.

Data retrieval

To use dynamic content you need to be able to publish your data on a public URL accessible by Carma. The URL cannot be password protected so if you want to keep the data secure you can limit access to so that only IP’s from Composts net can use them.

For Distribution time content we prefer data formatted with JSON. For backwards compatibility we can retrieve data in XML, but this method is deprecated and may be removed in a later version of carma.

Distribution Time Dynamic Content

Implementing Distribution Time DC with handlebars.

For a detailed explanation of carma script tags, please read this article.

A normal script tag will pull data from the contacts data or previous message history. You can for instance pull the contacts first name using the tag {{contact.firstName}}

Contact scoped dynamic content is implemented using script tags in the content block.

If you want to use a contacts data in order to retrieve data from a 3rd party system you do this by creating links to the external system with the {{#dynamicHttp}} tag. The request to the external system will be populated with the contacts data ant the data retrieved can then be used to render the block in the message.

Dynamic content uses Handlebars (http://handlebarsjs.com/) syntax, with a few custom handlebars helpers.

The syntax of the dynamic request helper is:

…

Default data

The first true/false statement in the end tells carma how important the external data is for the message. Sometimes you may not want to send the message if the request doesn’t return any data, and sometimes you can send the data with some default info instead. If the flag is set to false the message will not be sent if bad data is returned.

The second true/false statement has the same functionality, but only when the message is opened using the “Open in browser”-url.

Example Code

Below is an example based upon a dynamic integration with weather service worldweatheronline.com

The forecasts will be based on the value of the city property in this case.

So when you include below link with the recipient property parameters named {{contact.city}} and {{contact.lang}} and send it in an email to your recipient list, it will automatically bring in and render the weather forecast per recipient.

This example return the weather on the contacts destination in the contacts language.

{{#dynamicHttp “http://api.worldweatheronline.com/free/v1/weather.ashx?q={{contact.city}}&format=json&num_of_days=5&lang={{contact.lang}}&key=67efa0f444793fdd43ecd777cb4a8b79c72cd0e4” true true}}

This content is rendered using Handlebars syntax.

Current temperature is {{data.current_condition.[0].temp_C}} C <br />

This gets rendered if dynamicHttp request or rendering failed.

You can use the dot syntax to retrieve any of the data elements and insert it into the message.

In the example the return data has the following syntax.

{ “data”:

{ “current_condition”: [

{“cloudcover”: “0”,

“humidity”: “80”,

“observation_time”: “09:52 AM”,

“precipMM”: “0.0”,

“pressure”: “1024”,

“temp_C”: “2”,

“temp_F”: “36”,

“visibility”: “10”,

“weatherCode”: “113”,

“weatherDesc”: [ {“value”: “Sunny” } ],

“weatherIconUrl”: [ {“value”: “http://cdn.worldweatheronline.net/images/wsymbols01_png_64/wsymbol_0001_sunny.png” } ],

“winddir16Point”: “W”,

“winddirDegree”: “260”,

“windspeedKmph”: “6”,

“windspeedMiles”: “4” } ],

“request”: [ {“query”: “Stockholm, Sweden”, “type”: “City” } ],

“weather”: [ {“date”: “2015-03-05”, “precipMM”: “0.0”, “tempMaxC”: “3”, “tempMaxF”: “37”, “tempMinC”: “-1”, “tempMinF”: “31”, “weatherCode”: “113”,

“weatherDesc”: [ {“value”: “Sunny” } ],

“weatherIconUrl”: [ {“value”: “http://cdn.worldweatheronline.net/images/wsymbols01_png_64/wsymbol_0001_sunny.png” } ],

“winddir16Point”: “NW”,

“winddirDegree”: “309”,

“winddirection”: “NW”,

“windspeedKmph”: “15”,

“windspeedMiles”: “9” }

}}

Implementing Distribution Time DC with XML/XSL.

NOTE! This method is deprecated and is only available for backwards compatibility. We strongly suggest using the method described above as it is easier to implement and maintain.

The first thing to do is to provide Compost with an URL where data can be fetched, and an image of how the rendered data should look. Based on this Compost will produce a special block in your template that will be used to render the data into email-ready HTML. Below is an example of a well formed XML that can easily be translated into a block in Carma.

If you include multiple items in the XML, Carma can either render all of them or place them in individual blocks that can then either be deleted if they are redundant or they can be associated with a filter so that only a subset of you contacts will receive the block.

The XSL part of the code is stored with the placeholder. Please contact Carma support (support@compost.se) to learn more on how they can help you with this.

The boolean at the end is used to determine what should happen if the RSS feed cannot be read or parsed correctly.

If true, the message will be created but with a blank space where the content should have been placed. If false, no message will be generated.

Example Code

A combination of XML (the rss data) and a stylesheet ( XSL) with produce the final HTML that will be placed in the message. Below is an example of XML/XSL that produces the following output:

XML

<?xml version=”1.0″ encoding=”UTF-8″ ?>

<data>

<title>Example feed</title>

<description>A feed with nice formatting</description>

<item>

<title>A headline or title</title>

<![CDATA[Lorem ipsum & dolor sit amet]]>

</description>

<image>http://placehold.it/100×100</image>

</item>

</channel>

</data>

XSL

<?xml version=”1.0″ encoding=”UTF-8″?>

<?altova_samplexml carma_follow_email_v1.3.1.xml?>

<xsl:stylesheet version=”1.0″ xmlns:xsl=”http://www.w3.org/1999/XSL/Transform”>

<xsl:output method=”html” omit-xml-declaration=”yes” indent=”yes”/>

<xsl:template match=”/”>

<xsl:apply-templates select=”data/channel/item”/>

</xsl:template>

<xsl:template match=”item”>

<tr>

</a>

</td>

</td>

<xsl:value-of select=”title”/>

</font>

<br />

<xsl:value-of select=”description”/>

<br />

Published on: <xsl:value-of select=”substring(pubDate,0,17)” />

</font>

</td>

</tr>

</table>

</xsl:template>

</xsl:stylesheet>