What is Template Transformation ?

A Template Transformation converts a given data structure in another format using a template.

This template will be parsed by a template engine which applies a given model to it by interpolating variables inside the template with data from the model.

Since a template transformation is a very clean and flexible approach it can often be the right choice to convert from one format to another.

It is often used to convert from JSON to any other text-based format like XML, CSV or plain text.

The transform.ftl command

The transformer command transform.ftl uses the template engine FreeMarker in order to apply a transformation on a given model using a given template.

See the commands reference for details about the available parameters of this command.​

In order to do a conversion from one data structure into another using the transform.ftl command, you need two core parts:

• A model = The data structure you would like to convert (usually a JSON document).

• A template = Defines the conversion "rules".

Below you can find a simple example how this could look like in a pipeline with model and template defined as inline values:

pipeline:

  - transform.ftl:
      model: {
          "firstName": "Max", 
          "lastName": "Smith"
        }
      template: |
        Hello ${firstName} ${lastName}!

When you run this pipeline, you will get as output:

Hello Max Smith!

The data for the model and the template can for sure also come from a PEL or any other location supported by PIPEFORCE uris.

Here is an example which loads the model from the property store and the template from drive:

pipeline:

  - transform.ftl:
      model: $uri:property:global/app/myapp/data/person@value
      template: $uri:drive:/templates/person.ftl

It is also possible to directly access the vars, headers and body scope inside the template. In this case no model must be passed:

vars:
  firstName: Max,
  lastName: Smith
pipeline:

  - transform.ftl:
      template: |
        Hello ${vars.firstName} ${vars.lastName}!

As you can see, custom URIs are used here in order to point to locations for the model and the template.​

In this section some of the core concepts of the FreeMarker template language will be shown.

For more details visit their Official FreeMarker Documentation.

Accessing values (interpolation)​

In order to access a value from a model and write it at a certain position in the template, you can use ${variablePath} whereas variablePath points to the path of the value inside the model. Let's assume you have a JSON model like this:

{
  "person": {
    "firstName": "Maria",
    "lastName": "Sanders"
  }
}

If you would like to print the first name of the person, you could use the path person.firstName:

Hello ${person.firstName}!

Which will create this output after template was rendered:

Hello Maria!

If the model contains a list like this:

{
  "people": [
    {
      "firstName": "Maria",
      "lastName": "Sanders"
    },
    {
      "firstName": "Markus",
      "lastName": "Mayers"
    }
  ]
}

then you can access values in this list by its index like this:

Hello ${people[1].firstName}!

Which will create this output after template was rendered:

Hello Markus!

Iterating list values​

Sometimes it is necessary to iterate over a list from a model like this:

{
  "people": [
    {
      "firstName": "Maria",
      "lastName": "Sanders"
    },
    {
      "firstName": "Markus",
      "lastName": "Mayers"
    }
  ]
}

In FreeMarker you can do so by using the syntax <#list people as person>:

List of people:
<#list people as person>
- ${person.firstName} ${person.lastName}
</#list>

Which will create this output after template was rendered:

List of people:
- Maria Sanders
- Markus Mayers

You can also iterate over elements (called "hashes"). Let's assume you have a JSON model like this:

{
  "products":{
    "apple": 5,
    "banana": 10,
    "kiwi": 15
  } 
}

In order to iterate over the elements inside products you can use this FreeMarker template:

List of products:
<#list products as name, price>
- ${name}, ${price} EUR
</#list>

Which will create this output after template was rendered:

List of products:
- apple, 5 EUR
- banana, 10 EUR
- kiwi, 15 EUR

For more details about iterating model data structures, see FreeMarker Documentation.

Conditional output (if, else, elseif)​

In case you would like to generate an output only in case a certain criteria matches, you can use the if, else, elseif structure.

Let's assume a JSON model like this:

{
  "products":{
    "apple": 5,
    "banana": 10,
    "kiwi": 15
  } 
}

And now you would like to print BEST OFFER! on those with price < 10, then you could write a template like this:

List of products:
<#list products as name, price>
- ${name}, ${price} EUR <#if price < 10>[BEST OFFER!]</#if>
</#list>

This will be rendered to a result like this:

List of products:
- apple, 5 EUR [BEST OFFER!]
- banana, 10 EUR
- kiwi, 15 EUR

It's also possible to use <#else> and <#elseif> constructs. For more details, see FreeMarker Documentation.