Webhook - Send Custom Request - Trimou Templating Engine Guide

Webhook - Send Custom Request - Trimou Templating Engine Guide

by on ‎10-13-2016 08:30 PM - edited a week ago by Community Manager (2,136 Views)

This article describes how to design templates using the Trimou templating engine in Webhook, with the Send Custom Request action.

Table of Contents Placeholder

Pre-Requisites

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 AudienceStream.

For more, see: Trimou 2.3.0 Documentation

JSON Input

All examples will reference the following JSON data:

{
    "name"   : "The marketing Beast",
    "tamed"  : true,
    "list"   : ["a", "b", "c"],
    "parent" : {
        "child": "Steve"
    },
    "items"  : [  
    {
        "id": "Bat"
    },
    {
        "id": "Cat"
    },
    {
        "id": "Mat"
    }],
    "date"    : "Jul 14, 2016 10:12:52 AM",
    "price"   : "3.99"
}   

Syntax

Variable Substitution

Reference variables and substitute in their value with double curly braces.

Template Rendered Value
{{name}} is here. The marketing Beast is here.

Sections

A section content is rendered if there is an object found for the given key and it evaluates to true. Syntax is a pair of opening {{#var}} and closing {{/var}} tags.

Template Rendered Value
{{#tamed}}He is tamed.{{/tamed}} He is tamed.

Since tamed == true, the section content is rendered. If it was false, the section would not show.

Inverted Sections

The inverse of a regular section. Content is rendered if false, and not shown otherwise. Syntax is a pair of opening {{^var}} and closing {{/var}} tags.

Template Rendered Value
{{^missing}}Show only if not set or empty.{{/missing}} Show only if not set or empty.

Property "missing" is not defined in the JSON data structure, and hence evaluates to false. However, if "missing" was defined, but set to false or an empty array, the result would be the same.

Nested Variable Access

Access array elements with using their (zero-based) index. Traverse nested properties with a dot.

Template Rendered Value
2nd array element = {{list.1}} 2nd array template = b
Child = {{parent.child}} Child = Steve

Iteration

Looping over arrays is straightforward, and Trimou provides a number of helper functions. Nested attributes within iteration are referenced by name. Trimou is able to figure out the context and parent (iteration element) they belong to.

Trimou Built-in Iteration Helpers:

  • iter.index (starts at 1)
  • iter.isFirst
  • iter.isLast
  • iter.hasNext
Template Rendered Value
{{#items}}
  {{iter.index}}) {{id}} {{#iter.isFirst}}FIRST{{/iter.isFirst}}
{{/items}}
1) Bat FIRST
2) Cat
3) Mat

Helper Functions

Templates can provide additional and custom functionality through helper methods. They allow for transforming data and make it easier to generate the desired document format.

castIntegers

UDH 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 {count=1.0}
tally.castIntegers {count=1}
tally.castIntegers.toJson {"count":1}

encodeBase64

Encode content in base64.

Template Rendered Value
{{#encodeBase64}}
  {{name}} is here.
{{/encodeBase64}}
VGhlIG1hcmtldGluZyBCZWFzdCBpcyBoZXJlLg

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}} &lt;hello&gt;&amp;&quot;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}} &lt;hello&gt;&amp;&quot;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
{{date}} Thu Jul 14 12:00:46 PDT 2016
{{formatDate date pattern="yyyy-MM-dd HH:mm a"}} 2016-07-14 12:00 PM

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.

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:
2015-01-22T08: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 conctentation seperator; 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 parameter exists and has content.

Template Rendered Value
{{#if name}}Welcome back, {{name}}!{{/if}} Welcome back, John!
{{#if history}} {{history.toJson}} {{/if}} ["Alpha", "Beta", "Gamma", "Delta"]

isEq

Print the content if the values are equal.

Template Rendered Value
{{#isEq seven 7}}seven is 7{{/isEq}} seven is 7
{{#isEq seven 8}}seven is 8{{/isEq}}  
{{#isEq water_is_wet true}}water is wet{{/isEq}} water is wet
{{#isEq water_is_wet false}}water is not wet{{/isEq}}  
{{#isEq vader \"anakin\"}}Vader is Anakin{{/isEq}} Vader is Anakin
{{#isEq vader \"kenobi\"}}Vader is Kenobi{{/isEq}}  

isNotEq

Print the content if the values are equal.

Template Rendered Value
{{#isNotEq seven 7}}seven is not 7{{/isNotEq}}  
{{#isNotEq seven 8}}seven is not 8{{/isNotEq}} seven is not 8
{{#isNotEq truth_is_out_there true}}the truth is out there{{/isNotEq}}  
{{#isNotEq truth_is_out_there false}}there's nothing out here{{/isNotEq}} there's nothing out here
{{#isNotEq beast \"is_nice\"}}The beast is nice{{/isNotEq}}  
{{#isNotEq beast \"is_scary\"}}The beast isn't scary!{{/isNotEq}} The beast isn't scary!

join

Join will convert a list into a string with an optional joiner.

Template Rendered Value
{{join items}} alpha,beta,gamma
{{join items on=" and "}} alpha and beta and gamma
{{join items on=""}} alphabetagamma
{{join empty_list on="humongous diatribe"}}  

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

sum

Sum all of the values in a list or tally.

Template Rendered Value
{{ tally.sum }} 47.8
{{ prices.sum }} 35.0

toInteger

Convert a variable’s value to an integer.

Template Rendered Value
{{price}} 3.99
{{price.toInteger}} 3

toJson

Print the variable in a JSON format.

Template Rendered Value
{{tally}} {count=1.0}
{{tally.toJson}} {"count":1.0}
{{properties}} [alpha,beta,gamma]
{{properties.toJson}} ["alpha","beta","gamma"]

toList

Convert a JSON-formatted-array string into an array for additional operations.

For prices: ["1","2","2"]:

Template Rendered Value
{{prices.toList.sum}} 5

toTimestamp

Convert a date variable’s value to the Unix seconds timestamp format.

Template Rendered Value
{{date}} Thu Jul 14 11:49:10 PDT 2016
{{date.toTimestamp}} 1468522150

toTimestampMs

Convert a date variable's value to the Unix milliseconds timestamp format.

Template Rendered Value
{{date}} Thu Jul 14 11:49:10 PDT 2016
{{date.toTimestampMs}} 1468522150000

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}} 1523297268
{{unixTimestamp format="yyyy-MM-dd HH:mm a"}} 2018-04-09 18:08 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}} 1523297268488
{{unixTimestampMs format="yyyy-MM-dd HH:mm a"}} 2018-04-09 18:08 PM

unless

Print the content if the parameter does not exist or has no content.

Template Rendered Value
{{#unless name}}Please Login{{/unless}} Please Login
{{#unless history}}5% off your first order!{{/unless}} 5% off your first order!

uuid

Print a randomly generated UUID. Useful for creating nonces.

Template Rendered Value
{{uuid}} 42eee61d-9bf5-4da0-9c20-f048481e7e03

wsse

Produce a WSSE header.

Template Rendered Value
{{wsse "username" "password"}} UsernameToken Username="username", PasswordDigest="dANnGlmaO4JDPOXPYKNrWeS2Tss=", Nonce="YjQ4MzM5ODAtMjdkOS00ZjM2LTlhZGYtMDM3OTUzNDdjY2Iy", Created="2017-10-09T16:51Z"