This article describes how to design templates using the Trimou templating engine in Webhook, with the Send Custom Request action.
Table of Contents Placeholder
Prerequisites
Introduction to Webhook - Send Custom Request Action
Introduction to Webhook - Send Custom Request - Template Variables Guide
Overview
Trimou is an open-source templating engine that allows the rendering of documents based on JSON input and a template definition. This guide explains common syntax, as well as extensions which are custom to Tealium AudienceStream.
For more, see: Trimou 2.3.0 Documentation
Webhooks
When setting up a webhook in AudienceStream, a vistor profile has visitor and visit attributes that need to be mapped to the required output. A visitor profile example that shows all data types available for mapping:
{ "badges": [ "Test Badge" ], "dates": { "Test Date [dat]": 1600128000000 }, "flags": { --booleans "Test Boolean [bln]": true }, "metrics": { --numbers "Lifetime visit count": 12 }, "metric_sets": { --tallies "Test Tally [tly]": { "A": 1, "B": 2, "C": 3 } }, "properties": { --strings "Test String [str]": "Hello" }, "property_sets": { --sets of strings "Test Set of Strings [ss]": [ "A", "B", "C" ] }, "property_lists": { --arrays of strings "Test Array Strings [arrs]": [ "A", "A", "B" ] }, "metric_lists": { --arrays of numbers "Test Array Numbers [arrn]": [ 1.0, 1.0, 2.0 ] }, "flag_lists": { --arrays of booleans "Test Array Booleans [arrb]": [ true, true, false ] } }
Map all attributes from the input visitor profile that you want to use in the Trimou template. The values of the mapped attributes become available to the Trimou rendering engine.
The following shows the data types available for mapping when setting up your template variables:
Syntax
The syntax examples in the sections below reference the visitor profile.
Variable Substitution
The name of a variable is a placeholder for its data value. Variable substitution references this value with double curly braces, such as {{var}} .
In the following example, the String variable {{str}} is substituted with it's value Hello .
Template
Rendered Value
{{str}}
Hello
{{str}} world
Hello world
The following example gets the first value in the array of numbers {{arrn}} , referenced by specifying the index 0 .
Template
Rendered Value
The value is {{arrn.0}}
The value is 1.0
The value is {{arrn.1}}
The value is 1.0
The value is {{arrn.2}}
The value is 2.0
Sections
A section of content, surrounded by opening {{#var}} and closing {{/var}} tags, is rendered if there is an object found for the given key. This includes a Boolean of value true , a non-empty Iterable , and a non-empty array.
In the following example, since the Boolean variable bln is true , the content is rendered. The content does not render if the variable was false .
Template
Rendered Value
{{#bln}} Section of content {{/bln}}
Section of content
In the following example, since the array of Strings arrs is not empty, the content is rendered 3 times, once for each array element. The content does not render if the variable was false .
Template
Rendered Value
{{#arrs}} Section of content {{/arrs}}
Section of content
Section of content
Section of content
Inverted Sections
A section of content, surrounded by opening {{#var}} and closing {{/var}} tags, is rendered if there is no object found in the context. This includes a Boolean of value false , an Iterable with no elements, or an empty array.
In the following example, since bln is true , the content is not rendered. The content renders if the variable was false .
Template
Rendered Value
{{^bln}} Section of content {{/bln}}
In the following example, since the variable missing is not defined in the visitor profile, the content is rendered.
Template
Rendered Value
{{^missing}} Section of content {{/missing}}
Section of content
Iteration
Trimou provides several helper functions to iterate an array. Nested attributes within an iteration are referenced by name. Trimou determines the context and parent (iteration element) they belong to.
In the above example, we mapped a Set of Strings to the variable "object.ss", an Array of strings to the variable "object.arrs", an Array of Numbers to the variable "object.arrn" and finally an Array of Booleans to the variable "object.arrb". This means we can use Trimou to iterate over these attributes treating them as aligned arrays collectively, by iterating over the variable "object". The example below shows this.
The following are the Trimou built-in iteration helpers:
iter.index (the first element is at index 1)
iter.isFirst
iter.isLast
iter.hasNext
{{#object}} and {{/object}} mean that we are iterating over the 4 variables that we have prefixed "object."
{{iter.index}} is the current iteration index, starting at 1.
{{#iter.isFirst}}"first":"true",{{/iter.isFirst}} renders the text inside if it is the first iteration
{{#iter.isLast}}"last":"true",{{/iter.isLast}} renders the text inside if it is the last iteration
{{ss}} inside the {{#object}} mean that we are referring to the item in the Set of Strings at this position, since we mapped the Set of Strings to "object.ss".
The same goes for {{arrs}} , {{arrn}} and {{arrb}} respectively to refer to the Array of Strings, the Array of Numbers and the Array of Booleans
{{#iter.hasNext}}, {{/iter.hasNext}} renders a comma if the iteration has more elements (iterHasNext is true )
Template
Rendered Value
"MyData":[ {{#object}} { "idx":{{iter.index}}, {{#iter.isFirst}}"first":"true",{{/iter.isFirst}} {{#iter.isLast}}"last":"true",{{/iter.isLast}} "ss": "{{ss}}", "arrs": "{{arrs}}", "arrn": "{{arrn}}", "arrb": "{{arrb}}", }{{#iter.hasNext}}, {{/iter.hasNext}} {{/object}} ]
"MyData": [{ "idx": 1, "first": "true", "ss": "A", "arrs": "A", "arrn": "1.0", "arrb": "true", }, { "idx": 2, "ss": "B", "arrs": "A", "arrn": "1.0", "arrb": "true", }, { "idx": 3, "last": "true", "ss": "C", "arrs": "B", "arrn": "2.0", "arrb": "false", }]
For Iterating over a Tally (we mapped the Tally to "tly" in the example above), you can use a special iterator, called the entrySet. Inside this, you can refer to the key and the value, as in the example below
Template
Rendered Value
"MyTally":{ {{#each tly.entrySet}} "{{key}}": "{{value.toInteger}}"{{#iter.hasNext}},{{/iter.hasNext}} {{/each}} }
"MyTally": { "A": "1", "B": "2", "C": "3" }
Helper Functions
Templates provide additional and custom functionality through Tealium provided helper functions. They allow for transforming data and make it easier to generate the desired document format.
castIntegers
Customer Data Hub uses decimals to store various numbers. This helper forces the output in collections to be integer values. Can be used with toJson .
Template
Rendered Value
tally
{A=1.0, B=2.0, C=3.0}
tally.castIntegers
{A=1, B=2, C=3}
tally.castIntegers.toJson
{"A":1,"B":2,"C":3}
encodeBase64
Encode content in base64.
Template
Rendered Value
{{#encodeBase64}} {{str}} world {{/encodeBase64}}
wqDCoEhlbGxvIHdvcmxkCg==
encodeUrl
URL-encode content.
Template
Rendered Value
{{#encodeUrl}}https://www.google.com/search?q=tealium{{/encodeUrl}}
https%3A%2F%2Fwww.google.com%2Fsearch%3Fq%3Dtealium
escapeHtml
Escape values for use in HTML documents.
Template
Rendered Value
{{#escapeHtml}}<hello>&\"world{{/escapeHtml}}
<hello>&"world
escapeJson
Escape values for use in JSON objects/arrays.
Template
Rendered Value
{{#escapeJson}}{"foo":"bar"}{{/escapeJson}}
{\"foo\":\"bar\"}
escapeXml
Escape values for use in XML documents.
Template
Rendered Value
{{#escapeXml}}<hello>&\"world{{/escapeXml}}
<hello>&"world
formatDate
Formats date variable according to specified pattern. Pattern syntax corresponds to Java’s Simple Date formatting. For full table listing, see the Java Simple Date Format documentation.
Template
Rendered Value
{{dat}}
2020-09-15T00:00:00.000Z
{{formatDate dat pattern="yyyy-MM-dd HH:mm a"}}
2020-09-15 00:00 AM
hash
HMAC Generator, computes a Hash-based message authentication code (HMAC) using a secret key. A HMAC is a small set of data that helps authenticate the nature of message; it protects the integrity and the authenticity of the message.
The secret key is a unique piece of information that is used to compute the HMAC and is known both by the sender and the receiver of the message. This key will vary in length depending on the algorithm that you use.
The following example assumes that testKey , timestamp , ip and lang exist as valid input variables in the Trimou template.
Template
Explanation
Rendered Value
{{hash algorithm="HmacSHA256" encodingCharset="UTF-8" binaryEncoding="hex" joinOn="" useSecretKey="true" testKey timestamp ip lang}}
Template Variables: testKey , timestamp , ip , timestamp and since useSecretKey="true" the first variable provided i.e. testKey will be used as the Secret Key for HMAC calculation
For example, if the concatenation of the timestamp, ip and lang are: 2020-08-20T08:45:33.412127.0.0.1en-US and the testKey is w8sZzy8EaPaxFKfaoTqUi6 The result is: a0afb572e3fc174c2dea112e1a9922fb9903caa65e6aa9e50e47758b8a611542
Options
Required
Possible Values
Description
algorithm
Yes
example: HmacSHA256
available options are: - when secretKey="true" refer to Java Mac Algorithms - when secretKey="false" refer to Java MessageDigest Algorithms
encodingCharset
No
UTF-8 (Default), US-ASCII
binaryEncoding
No
base64 (Default), hex
binaryEncodingOptions
No
lowercase (Default), uppercase
only applies when binaryEncoding="hex"
joinOn
No
input concatenation separator; provide empty value "" if you need to concatenate on empty
useSecretKey
No
false (Default), true
secretKey
No
variables
YES
Place all variables after the last option specified. For example: - if secretKey="true" , the first variable after all options are specified will be used as secretKey and all the others as the variables to be joined by joinOn option. - if secretKey="false" , they will all be used as variables to be joined by joinOn option.
if
Print the content if the variable exists and has content. The following example assumes that lang exist as valid input variables in the Trimou template.
Template
Rendered Value
{{#if str}} {{str}} world! {{/if}}
Hello world!
{{#if arrn}} {{arrn.toJson}} {{/if}}
[1.0,1.0,2.0]
{{#if ss}} {{ss.toJson}} {{/if}}
["A","B","C"]
isEq
Print the content if the values are equal.
Template
Rendered Value
{{#isEq bln true}}Boolean is true{{/isEq}}
Boolean is true
{{#isEq bln false}}Boolean is false{{/isEq}}
{{#isEq str "Hello"}}String is Hello{{/isEq}}
String is Hello
{{#isEq str "Test"}}String is Test{{/isEq}}
isNotEq
Print the content if the values are equal.
Template
Rendered Value
{{#isNotEq bln true}}Boolean is false{{/isNotEq}}
{{#isNotEq bln false}}Boolean is true{{/isNotEq}}
Boolean is true
{{#isNotEq str "Hello"}}Hello world!{{/isNotEq}}
{{#isNotEq str "Some string"}}Hello there!{{/isNotEq}}
Hello there!
join
Join will convert a list into a string with an optional joiner. Assuming empty_list is an empty list, no value is rendered.
Template
Rendered Value
{{join ss}}
A,B,C
{{join ss on=" and "}}
A and B and C
{{join ss on=""}}
A B C
{{join empty_list on=" and "}}
jsonMinify
If provided content that contains valid JSON, minifies it (removes all whitespace). If the content is not valid JSON, the original value is shown with no changes.
Template
Rendered Value
{{#jsonMinify}} { "name" : "Bob", "status" : "He is hungry!", } {{/jsonMinify}}
{"name":"Bob","status":"He is hungry!"}
md5
MD5 hash the content.
Template
Rendered Value
{{#md5}}Hello World!{{/md5}}
ed076287532e86365e841e92bfc50d8c
sha1
SHA1 hash the content.
Template
Rendered Value
{{#sha1}}Hello world!{{/sha1}}
d3486ae9136e7856bc42212385ea797094475802
sha256
SHA256 hash the content.
Template
Rendered Value
{#sha256}}Hello World!{{/sha256}}
7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd200126d9069
substring
Print the substring that begins at the specified start index and ends at the specified end index - 1.
Template
Rendered Value
{{sequence}}
"123456789"
{{substring sequence start="0" end="5"}}
"12345"
substringAfter
Print the substring after the specified separator string.
Template
Rendered Value
{{screensize}}
"340x480x640"
{{substringAfter screenSize separator="x"}}
"480x640"
substringAfterLast
Print the substring after the last occurrence of the specified separator string.
Template
Rendered Value
{{screensize}}
"340x480x640"
{{substringAfterLast screenSize separator="x"}}
"640"
substringBefore
Print the substring before the specified separator string.
Template
Rendered Value
{{screensize}}
"340x480x640"
{{substringBefore screenSize separator="x"}}
"340"
substringBeforeLast
Print the substring before the last occurrence of the specified separator string.
Template
Rendered Value
{{screensize}}
"340x480x640"
{{substringBeforeLast screenSize separator="x"}}
"340x480"
substringBetween
Print the substring between the specified open and close strings.
Template
Rendered Value
{{animals}}
"cat dog tiger duck"
{{substringBetween animals open="cat" close="duck"}}
" dog tiger "
sum
Sum all of the values in a list or tally.
Template
Rendered Value
{{tly.sum}}
6.0
{{arrn.sum}}
4.0
toInteger
Convert a variable’s value to an integer.
Template
Rendered Value
{{num}}
1.0
{{num.toInteger}}
1
toJson
Print the variable in a JSON format.
Template
Rendered Value
{{tly}}
{A=1.0, B=2.0, C=3.0}
{{tly.toJson}}
{"A":1.0,"B":2.0,"C":3.0}
toList
Convert a JSON-formatted-array string into an array for additional operations.
For arrn: ["1","2","2"] :
Template
Rendered Value
{{arrn.toList.sum}}
4.0
toTimestamp
Convert a date variable’s value to the Unix seconds timestamp format.
Template
Rendered Value
{{dat}}
2020-09-15T00:00:00.000Z
{{dat.toTimestamp}}
1600128000
toTimestampMs
Convert a date variable's value to the Unix milliseconds timestamp format.
Template
Rendered Value
{{dat}}
2020-09-15T00:00:00.000Z
{{dat.toTimestampMs}}
1600128000000
unixTimestamp
Print the connector fire time in seconds since Unix epoch. This is useful for authorization headers. Optionally, format the date variable according to a specified pattern. Pattern syntax corresponds to Java’s Simple Date formatting. For full table listing, see the Java Simple Date Format documentation.
Template
Rendered Value
{{unixTimestamp}}
1599859440
{{unixTimestamp format="yyyy-MM-dd HH:mm a"}}
2020-09-11 21:24 PM
unixTimestampMs
Print the connector fire time in milliseconds since epoch. This is useful for authorization headers. Optionally, format the date variable according to a specified pattern. Pattern syntax corresponds to Java’s Simple Date formatting. For full table listing, see the Java Simple Date Format documentation.
Template
Rendered Value
{{unixTimestampMs}}
1599859605838
{{unixTimestampMs format="yyyy-MM-dd HH:mm a"}}
2020-09-11 21:26 PM
unless
Print the content if the parameter does not exist or has no content.
Template
Rendered Value
{{#unless str}}str doesn't exist or no content{{/unless}}
{{#unless str2}}str2 doesn't exist or no content{{/unless}}
str2 doesn't exist or no content
uuid
Print a randomly generated UUID. Useful for creating nonces.
Template
Rendered Value
{{uuid}}
4d61f298-2a8d-461d-a3bf-b153892a7b49
... View more