AireFlow Docs

Appearance

Escaping Mapped Values ​

INFO

Auto Escaping will be released in version 2.42.0, planned for release on 21/10/2026.

Special characters in a value mapped with Liquid can break the document it's mapped into. For example, a quote or line break breaks JSON, and a & or < breaks XML. With auto escaping turned on, AireFlow escapes each mapped value to suit its destination, so you don't need hand-written replace filters.

Turning on auto escaping ​

Auto escaping is set per task, with the Auto Escape Mappings switch in the task's properties. We recommend turning it on wherever possible.

  • New tasks created in the designer have it turned on.
  • Existing tasks have it turned off and keep working as before until you turn it on.
  • Once turned on and saved, it can't be turned off again in the designer.

The setting is kept when you export and import a workflow definition or create a new version. For definitions imported from a Git repository, add "AutoEscape": true to each task in the repository, or enable it in your dev environment and re-export the definition.

Which fields are escaped ​

FieldEscapingOutput for Tom & "TJ" <Jerry>
HTTP task body with a JSON Content-Type, and mutationsJSONTom \u0026 \u0022TJ\u0022 \u003CJerry\u003E
HTTP task body with an XML or HTML Content-Type, and emitted contexts (the Output Context field)XML/HTMLTom &amp; &quot;TJ&quot; &lt;Jerry&gt;
Everything else, including the HTTP task URL and headers, email fields and other Content-TypesNoneTom & "TJ" <Jerry>
  • Only the output of Liquid expressions ({{ ... }}) is escaped, not the text around them. XPath expressions aren't affected.
  • Non-ASCII characters are escaped too. For example, Zürich becomes Z\u00FCrich in JSON and Z&#xFC;rich in XML. Parsers read these back as the original value.
  • When the Content-Type is JSON and the mapped body starts with { or [, the body must be valid JSON, or the task fails with HTTP body is not valid JSON after mapping.

Examples ​

JSON HTTP body ​

Given a context where name is Tom & Jerry "TJ" and notes spans two lines, this body:

liquid
{ "name": "{{ context.name }}", "notes": "{{ context.notes }}" }

produces valid JSON:

json
{ "name": "Tom \u0026 Jerry \u0022TJ\u0022", "notes": "line one\nline two" }

Mutations are escaped the same way, so free text containing quotes, backslashes or line breaks can't produce an invalid patch document.

XML elements ​

An expression that refers to an element with child elements, such as {{ context }}, is inserted into XML and HTML output as markup rather than escaped text. Given a person element containing first and last elements:

liquid
<event>{{ context.person }}<source>form</source></event>

produces:

xml
<event><first>Ann</first><last>Lee &amp; Co</last><source>form</source></event>

Line breaks in HTML ​

newline_to_br escapes each line, then joins them with <br />:

liquid
<p>{{ context.notes | newline_to_br }}</p>

produces <p>line one<br />line &lt;two&gt;</p>.

HTTP task URL ​

The URL isn't escaped automatically. Use url_encode on values in a query string or path:

liquid
https://example.com/api/search?q={{ context.search | url_encode }}

For a b&c, this produces https://example.com/api/search?q=a+b%26c.

Turning escaping off with raw ​

To insert a value exactly as it is, such as a JSON object held in the context, use the raw filter:

liquid
"value": {{ updateContext.detailsJson | raw }}

WARNING

Only use raw for values you trust to be valid in that position. Otherwise, quotes or < in the value can break the output or inject extra fields.

Previews ​

The expression previews for HTTP task bodies and mutations show the escaped output. Emitted contexts don't have a preview.

Moving an existing task to auto escaping ​

Auto escaping doesn't remove hand-written escaping, so any left in place escapes values twice. For example, | escape would turn < into &amp;lt;.

  1. Export the workflow definition to keep a copy. Consider making the change in a new version, because the setting applies to each version's copy of the task separately.

  2. Remove manual escaping from the task's HTTP body, emitted context and mutations, such as:

    • | escape
    • | replace: '&', '&amp;' and similar replace filters for < and >
    • | replace: '"', '\"' and other replace filters that escape quotes, backslashes or newlines for JSON
    • the {% capture newline %} workaround

    Keep any url_encode filters in the URL.

  3. Turn on Auto Escape Mappings, check the previews, then save. Once saved, it can't be turned off again in the designer.