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 certainly 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:

Note: Even if the value of the template parameter contains expression variables ${vars.firstName} and ${vars.lastName} which look similar to the PEL, these belong to the syntax of the pipeline engine and not to PEL!

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:

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

Which will create this output after template was rendered:

If the model contains a list like this:

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

Which will create this output after template was rendered:

Iterating list values

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

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

Which will create this output after template was rendered:

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

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

Which will create this output after template was rendered:

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:

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

This will be rendered to a result like this:

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

What is Template Transformation ?

The transform.ftl command

Accessing values (interpolation)​

Iterating list values​

Conditional output (if, else, elseif)​

The `transform.ftl` command

Accessing values (interpolation)

Iterating list values

Conditional output (if, else, elseif)