Writing FreeMarker Templates in WSO2 MI

Photo by Lukas from Pexels

In WSO2 Micro Integrator, there are various ways to transform or generate payloads. PayloadFactory mediator, DataMapper, Script mediator, and Smooks mediator are some of the mediators we can use to transform and generate payloads.

Dont forget to check out this article about the CSV module, which is an easy-to-use module to transform CSV payloads.

Transforming CSV in WSO2 MI— The Easy Way

In the latest MI release (MI 4.0.0), WSO2 introduced a new feature to the PayloadFactory mediator. It’s the Apache FreeMarker templating support.

FreeMarker is a general-purpose templating engine developed by Apache. It’s a Java-based template engine that is very popular among Java developers to convert Java objects to HTML, XML, CSV, and other text-based formats.

To work with FreeMarker templating in PayloadFactory you have to get the latest version of WSO2 Integration Studio. To demonstrate this new feature, I’m doing the following JSON to XML transformation.

Input-

{
"first_name": "John",
"last_name": "Deo",
"age": 35,
    "location": {
        "state": {
            "code": "NY",
            "name": "New York"
        },
        "city": "Manhattan"
    }
}

Output-

<user>
    <Name>John Deo</Name>
    <Age>35</Age>
    <Address>Manhattan, NY</Address>
</user>

I first opened the Integration Studio and created an integration project in that project I created a REST API and the sequence of the REST API is as follows,

If I go to the properties view of the PayloadFactory mediator,

We can see, there’s a new property called Template Type. Using this property we can select the way we are going to write the template. If this is set to Default, then the PayloadFactory would work with the traditional syntaxes (Expressions with $ symbol). But here, I’m selecting the Freemarker template type. Then the PayloadFactory would accept a FreeMarker template as the payload template.

The FreeMarker template I developed to transform my JSON to XML is as follows,

<user>
    <Name>${payload.first_name} ${payload.last_name}</Name>
    <Age>${payload.age}</Age>
    <Address>${payload.location.city}, ${payload.location.state.code}</Address>
</user>

💡 You can use online FreeMarker template tester provided by Apache to test the template while development. — https://try.freemarker.apache.org/

When I add this into the Integration Studio properties view, it shows like this,

As you can see, Integration Studio provides syntax highlighting for FreeMarker templates 😲

That’s it 😁. We did a transformation in the PayloadFactory mediator using FreeMarker templates. It’s simple as that. Now, we can run our project in embedded Micro Integrator in the Integration Studio and send a request to the REST API and it would give us the desired output.

You might be wondering how to access payload, properties, and arguments of the mediation flow in the FreeMarker template. To do that, PayloadFactory provides built-in variables for the FreeMarker templates.

• payload — this variable represents the current payload of the mediation sequence.
• ctx — this represents ctx properties
• axis2 — this represents asix2 properties
• trp — this is the variable to refer to transport headers
• arg — using this, we can access defined argument in the PayloadFactory

We can use these variables as starting points of our template. Following is another example FreeMarker template that is using these variables.

{
"ctx property" : "${ctx.user_name}",
"axis2 property": "${axis2.REST_URL_POSTFIX}",
"trp property": "${trp.Host}"
}

The output payload generated from this template is as follows,

{
"ctx property": "john",
"axis2 property": "/demo",
"trp property": "localhost:8290"
}

The complete synapse code for this implementation is,

<property name="user_name" scope="default" type="STRING" value="john"/>
<payloadFactory media-type="json" template-type="freemarker">
    <format><![CDATA[{
        "ctx property" : "${ctx.user_name}",
        "axis2 property": "${axis2.REST_URL_POSTFIX}",
        "trp property": "${trp.Host}"
        }]]>
    </format>
<args/>
</payloadFactory>

That’s all about how to write FreeMarker templates in PayloadFactory and perform complex transformations. Refer to the official documentation for more details and examples. Happy coding 💻 🎉