Customize streaming payloads with FreeMarker

Amplitude streaming transformations use FreeMarker (FTL) templates to reshape an event payload before Amplitude sends it to a destination. This reference covers the template syntax. For when and how to apply a custom FTL template, refer to Streaming transformations.

Event streaming destinations that expose a custom payload editor use Apache FreeMarker (FTL) to turn the Amplitude event into the JSON body your destination expects. The editor in the connector builder provides autocomplete, hover documentation, and inline validation for the fields and helpers below. For the FreeMarker language itself, refer to the guide to creating templates.

The input object

input is the event (or user) Amplitude forwards. Access its fields with dot notation, wrapped in ${ } to output the value:

ftl
"${input.user_id}"
"${input.event_type}"
"${input.event_time}"

Commonly available fields include event_type, user_id, device_id, time, event_time, session_id, platform, event_properties, user_properties, group_properties, and groups, plus any transformations you select (derived_properties, lookup_properties). For the complete shapes, refer to the event format and user (Identify) format.

Fields aren't guaranteed

input fields depend on how each user instruments events, and a selected event property might not be present on every event you stream. Reference fields defensively (refer to Handle missing fields), and keep required-field usage to common fields like user_id, event_type, and event_time. The payload editor flags a referenced property that isn't present on all of the events you selected.

Dot and bracket notation

Use dot notation when a property name is a valid identifier, and bracket notation when the name contains spaces or other special characters:

ftl
${input.event_properties.plan}
${input.event_properties["Plan Type"]}

Handle missing fields

Because fields aren't guaranteed, guard against missing values:

  • ?? tests whether a value exists: <#if input.user_id??>…</#if>.
  • ! supplies a default when a value is missing: ${input.user_properties.email!} (empty string) or ${input.revenue!0}.
ftl
{
  <#if input.user_id??>
  "external_id": "${input.user_id}",
  </#if>
  "email": "${input.user_properties.email!}"
}

Useful built-ins

FreeMarker built-ins (?name) transform values. Common ones for JSON payloads:

Iterate over properties

Use <#list> with ?keys, and <#sep> to place commas between items only:

ftl
"user_properties": {
  <#list input.user_properties?keys as key>
    "${key}": ${UtilClass.toJsonString(input.user_properties[key])}<#sep>,</#sep>
  </#list>
}

Helper methods (FtlUtils)

Amplitude exposes helper methods for serializing values and other common transforms, so you don't have to hand-write the logic. Assign the helper once at the top of the template, then call its methods:

ftl
<#assign UtilClass=statics['com.amplitude.integrations.connector.utils.FtlUtils']>
{
  "user_properties": ${UtilClass.toJson(input.user_properties)}
}

Destination-specific helpers

Some destinations provide additional helper methods tailored to that destination. You can use those helpers only in that destination's template.

Examples

Each example shows the input event Amplitude forwards, the template you write, and the result Amplitude sends to your destination.

Simple: rename and pick fields

Map a few input fields into the shape your destination expects.

Input event:

json
{
  "event_type": "Song Played",
  "user_id": "user-123",
  "event_time": "2024-01-15T09:30:00.000",
  "event_properties": {
    "song_id": "abc-987"
  }
}

Template:

ftl
{
  "external_id": "${input.user_id}",
  "name": "${input.event_type}",
  "song": "${input.event_properties.song_id}"
}

Result:

json
{
  "external_id": "user-123",
  "name": "Song Played",
  "song": "abc-987"
}

Complex: guards, bracket notation, and iteration

Guard an optional field with ??, read a property whose name has a space with bracket notation, format a number with ?c, and serialize all user properties by looping with <#list>, emitting numbers and booleans raw and everything else through toJsonString.

Input event:

json
{
  "event_type": "Purchase Completed",
  "user_id": "user-123",
  "revenue": 12.5,
  "event_properties": {
    "Item Name": "Pro Plan"
  },
  "user_properties": {
    "email": "alex@example.com",
    "plan": "pro",
    "age": 30
  }
}

Template:

ftl
<#assign UtilClass=statics['com.amplitude.integrations.connector.utils.FtlUtils']>
{
  "event": "${input.event_type}",
  <#if input.user_id??>
  "user_id": "${input.user_id}",
  </#if>
  "item": "${input.event_properties["Item Name"]}",
  "revenue": ${input.revenue?c},
  "traits": {
    <#list input.user_properties?keys as key>
    <#assign value = input.user_properties[key]>
    "${key}": <#if value?is_number || value?is_boolean>${value}<#else>${UtilClass.toJsonString(value)}</#if><#sep>,</#sep>
    </#list>
  }
}

Result:

json
{
  "event": "Purchase Completed",
  "user_id": "user-123",
  "item": "Pro Plan",
  "revenue": 12.5,
  "traits": {
    "email": "alex@example.com",
    "plan": "pro",
    "age": 30
  }
}

Was this helpful?

For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.

On this page