Freemarker

1. Overview

The Freemarker component (freemarker) builds a text from a template written in the FreeMarker language, which supports conditions, loops, and data formatting — more powerful than Message Formatter for complex texts (for example, generating an HTML email body with a list of order items).

Use it when you need template logic (conditions, loops) to build a text. For simple variable substitutions, Message Formatter is more straightforward.

2. Prerequisites

No credentials or external access — local processing.

3. Authentication and Connection

Not applicable.

4. Configuration / Supported Operations

The component has a single operation: render a FreeMarker template. The template is compiled once when the flow starts (it isn't recompiled on every run).

Field	Required	Type	Description	Example
template	Yes, in practice	Text (FreeMarker template)	The template to process. Inside it, the input message's body is available as body (parsed as JSON, when possible) and the headers as headers. The UPPERCASE(text) and LOWERCASE(text) functions are also available.	"Hello ${body.customer.name}!"
encoding	No	Text	Template character encoding. Default value: "UTF-8".	"UTF-8"
locale	No	Text	Locale used when processing the template (number/date formatting). Default value: "en-US".	"en-US"
timeZone	No	Text	Time zone used when processing the template. Default value: "America/Sao_Paulo".	"America/Sao_Paulo"
version	No	Text	FreeMarker language version. Default value: "2.3.33".	"2.3.33"

5. Practical Examples

Simple example: build a personalized greeting using data from the message body.

Input:

{
  "customer": { "name": "Maria Silva" }
}

Component configuration:

{
  "componentName": "freemarker",
  "configurations": {
    "template": "Hello ${body.customer.name}, welcome!",
    "locale": "en-US"
  }
}

Response (the message body becomes the processed text):

"Hello Maria Silva, welcome!"

Advanced example: build an order summary with a list of items, using a template loop.

Input:

{
  "orderId": 981,
  "items": [
    { "name": "Product A", "quantity": 2 },
    { "name": "Product B", "quantity": 1 }
  ]
}

Component configuration:

{
  "componentName": "freemarker",
  "configurations": {
    "template": "Order ${body.orderId}:\n<#list body.items as item>- ${item.name} (x${item.quantity})\n</#list>",
    "locale": "en-US"
  }
}

Response:

"Order 981:\n- Product A (x2)\n- Product B (x1)\n"

6. Common Errors and Troubleshooting

Error / Symptom	Likely Cause	How to Fix
Template renders empty or with an error	FreeMarker syntax is incorrect, or the expression references a field that doesn't exist in body.	Review the template syntax and check the field names used.
Template processing error	Internal FreeMarker failure interpreting the template (invalid syntax) or interpolating the data.	Check the FreeMarker template syntax and the input body's format.
body available as plain text instead of an object	The input body isn't valid JSON; in that case it's made available as a raw string.	Make sure the input message is valid JSON, if the template expects to access body fields.