Using FreeMarker template engine in Sitecore Personalize

If you have tried creating an experiment or experience within Sitecore Personalize or completed a training course, the phrase "FreeMarker syntax" might have caught your attention. In this article I will explain what is FreeMarker and how it helps to unlock the full potential of personalisation and experimentation capabilities in Sitecore Personalize.

What is FreeMarker?

FreeMarker is a template engine, it allows to generate text output based on templates and dynamic data. It is similar to Mustache, Handlebars, Thymeleaf and other template engines. Templates are written in the FreeMarker Template Language (FTL) that supports conditional blocks, iterations, formatting, and many other capabilities.

How is FreeMarker used in Sitecore Personalize?

As a template engine, FreeMarker helps to produce output of the predefined format and make it dynamic based on the provided data input.

There are two main areas where FreeMarker is used in Sitecore Personalize:

• Web experiences and experiments
• Interactive experiences and experiments

For both of them Sitecore Personalize allows to construct API response using FreeMarker language that will be executed on the server side. Do not confuse this with Handlebars template language that is used for HTML, CSS and JavaScript sections. The key difference is that HTML, CSS and JavaScript templates will be executed on the client-side by Handlebars.js library:

What data is available in API response?

API response can reference and transform any server-side data that is available for the current guest: including guest profile data, his sessions, orders, segment memberships, and the decision model that is associated with this experience.

API response data can then subsequently be used in the HTML, CSS and JavaScript sections of a web experience. Imagine wanting to access the guest’s name or email address in your JavaScript code. To achieve this, you must configure the API response to include the dynamic data so that when the experience is executed, the data is requested from the server and then passed to the front-end code.

Interactive experiences work in a similar manner, but they don’t contain any HTML, CSS and JavaScript. Irrespective of the programming language you choose, your application can interact with the REST API to get dynamically produced API response and then use this data as required. I will show a simple example of such application in my next article.

Examples and tips

Example 1: Basic API Response

Please see a basic example of API response mark-up below. This API response returns guest’s email address and full name so that it can be accessed by the application:

{
    "guestEmail": "${guest.email}", 
    "guestName": "${guest.firstName} ${guest.lastName}" 
}

Example 2: Conditional Sections and Segments

Let’s add a conditional section with segments that are applicable to the current guest:

{
    "guestEmail": "${guest.email}", 
    "guestName": "${guest.firstName} ${guest.lastName}" 
<#if (guest.segmentMemberships)??> 
    , 
    "segmentMemberships": [ 
    <#list guest.segmentMemberships as segment> 
        ${toJSON(segment)}<#if (segment?has_next)>,</#if> 
    </#list> 
    ] 
</#if> 
}  

You may have noticed multiple <#if> statements in the example above, they are required to ensure that the final JSON result is valid. If there are any extra commas or non-closed brackets, Sitecore Personalize will return an error saying that the syntax is not correct.

Example 3: Decision Model Results

Another common use case for API response is returning results of the linked decision model:

{
    "guestEmail": "${guest.email}", 
    "guestName": "${guest.firstName} ${guest.lastName}" 
<#if (decisionModelResults.decisionModelResultNodes)??> 
    , 
    "contentItemId": 
    <#list decisionModelResults.decisionModelResultNodes as resultNode> 
        <#list resultNode.outputs as output> 
            <#if (output.ContentItemID)??> 
                "${output.ContentItemID}" 
            </#if> 
        </#list> 
    </#list> 
</#if> 
}  

Depending on how the decision model is configured, it can return one or multiple output nodes so you should consider this when designing the API response.

As you can see, FreeMarker templates in Sitecore Personalize are quite flexible and allow to tailor API response depending on your application needs and data available within Sitecore CDP. In my next blog post I will show an example of how an application can integrate with the REST API to get dynamic API responses from Sitecore Personalize. If you found this article helpful, feel free to share it with fellow developers and personalisation enthusiasts.