Transform JSON and XML using Liquid templates as maps in Azure Logic Apps

When you want to perform basic JSON transformations in your logic apps, you can use native data operations such as Compose or Parse JSON. For advanced and complex JSON to JSON transformations that have elements such as iterations, control flows, and variables, create and use templates that describe these transformations by using the Liquid open-source template language. You can also perform other transformations, for example, JSON to text, XML to JSON, and XML to text.

Before you can perform a Liquid transformation in your logic app, you must first create a Liquid template that defines the mapping that you want. You then upload the template as a map into your integration account. When you add the Transform JSON to JSON - Liquid action to your logic app, you can then select the Liquid template as the map for the action to use.

This article shows you how to complete these tasks:

  • Create a Liquid template.
  • Add the template to your integration account.
  • Add the Liquid transform action to your logic app.
  • Select the template as the map that you want to use.

Prerequisites

Create the template

  1. Create the Liquid template that you use as a map for the JSON transformation. You can use any editing tool that you want.

    For this example, create the sample Liquid template as described in this section:

    {%- assign deviceList = content.devices | Split: ', ' -%}
    
    {
       "fullName": "{{content.firstName | Append: ' ' | Append: content.lastName}}",
       "firstNameUpperCase": "{{content.firstName | Upcase}}",
       "phoneAreaCode": "{{content.phone | Slice: 1, 3}}",
       "devices" : [
          {%- for device in deviceList -%}
             {%- if forloop.Last == true -%}
             "{{device}}"
             {%- else -%}
             "{{device}}",
             {%- endif -%}
          {%- endfor -%}
       ]
    }
    
  2. Save the template by using the .liquid extension. This example uses SimpleJsonToJsonTemplate.liquid.

Upload the template

  1. Sign in to the Azure portal with your Azure account credentials.

  2. In the Azure portal search box, enter integration accounts, and select Integration accounts.

    Find "Integration accounts"

  3. Find and select your integration account.

    Select integration account

  4. On the Overview pane, under Components, select Maps.

    Select "Maps" tile

  5. On the Maps pane, select Add and provide these details for your map:

    Property Value Description
    Name JsonToJsonTemplate The name for your map, which is "JsonToJsonTemplate" in this example
    Map type liquid The type for your map. For JSON to JSON transformation, you must select liquid.
    Map SimpleJsonToJsonTemplate.liquid An existing Liquid template or map file to use for transformation, which is "SimpleJsonToJsonTemplate.liquid" in this example. To find this file, you can use the file picker. For map size limits, see Limits and configuration.

    Add Liquid template

Add the Liquid transformation action

  1. In the Azure portal, follow these steps to create a blank logic app.

  2. In the Logic App Designer, add the Request trigger to your logic app.

  3. Under the trigger, choose New step. In the search box, enter liquid as your filter, and select this action: Transform JSON to JSON - Liquid

    Find and select Liquid action

  4. Open the Map list, and select your Liquid template, which is "JsonToJsonTemplate" in this example.

    Select map

    If the maps list is empty, most likely your logic app isn't linked to your integration account. To link your logic app to the integration account that has the Liquid template or map, follow these steps:

    1. On your logic app menu, select Workflow settings.

    2. From the Select an Integration account list, select your integration account, and select Save.

      Link logic app to integration account

  5. Now add the Content property to this action. Open the Add new parameter list, and select Content.

    Add "Content" property to action

  6. To set the Content property value, click inside the Content box so that the dynamic content list appears. Select the Body token, which represents the body content output from the trigger.

    Select "Body" token for "Content" property value

    When you're done, the action looks like this example:

    Finished "Transform JSON to JSON" action

Test your logic app

By using Postman or a similar tool, post JSON input to your logic app. The transformed JSON output from your logic app looks like this example:

Example output

Liquid template considerations

  • Liquid templates follow the file size limits for maps in Azure Logic Apps.

  • The Transform JSON to JSON - Liquid action follows the DotLiquid implementation for Liquid. This implementation is a port to the .NET Framework from the Shopify implementation for Liquid and differs in specific cases.

    Here are the known differences:

    • The Transform JSON to JSON - Liquid action natively outputs a string, which can include JSON, XML, HTML, and so on. The Liquid action only indicates that the expected text output from the Liquid template's is a JSON string. The action instructs your logic app to parse input as a JSON object and applies a wrapper so that Liquid can interpret the JSON structure. After the transformation, the action instructs your logic app to parse the text output from Liquid back to JSON.

      DotLiquid doesn't natively understand JSON, so make sure that you escape the backslash character (\) and any other reserved JSON characters.

    • If your template uses Liquid filters, make sure that you follow the DotLiquid and C# naming conventions, which use sentence casing. For all Liquid transforms, make sure that filter names in your template also use sentence casing. Otherwise, the filters won't work.

      For example, when you use the replace filter, use Replace, not replace. The same rule applies if you try out examples at DotLiquid online. For more information, see Shopify Liquid filters and DotLiquid Liquid filters. The Shopify specification includes examples for each filter, so for comparison, you can try these examples at DotLiquid - Try online.

    • The json filter from the Shopify extension filters is currently not implemented in DotLiquid. Typically, you can use this filter to prepare text output for JSON string parsing, but instead, you need to use the Replace filter instead.

    • The standard Replace filter in the DotLiquid implementation uses regular expression (RegEx) matching, while the Shopify implementation uses simple string matching. Both implementations appear to work the same way until you use a RegEx-reserved character or an escape character in the match parameter.

      For example, to escape the RegEx-reserved backslash (\) escape character, use | Replace: '\\', '\\', and not | Replace: '\', '\\'. These examples show how the Replace filter behaves differently when you try to escape the backslash character. While this version works successfully:

      { "SampleText": "{{ 'The quick brown fox "jumped" over the sleeping dog\\' | Replace: '\\', '\\' | Replace: '"', '\"'}}"}

      With this result:

      { "SampleText": "The quick brown fox \"jumped\" over the sleeping dog\\\\"}

      This version fails:

      { "SampleText": "{{ 'The quick brown fox "jumped" over the sleeping dog\\' | Replace: '\', '\\' | Replace: '"', '\"'}}"}

      With this error:

      { "SampleText": "Liquid error: parsing "\" - Illegal \ at end of pattern."}

      For more information, see Replace standard filter uses RegEx pattern matching....

    • The Sort filter in the DotLiquid implementation sorts items in an array or collection by property but with these differences:

Other transformations using Liquid

Liquid isn't limited to only JSON transformations. You can also use Liquid to perform other transformations, for example:

Transform JSON to text

Here's the Liquid template that's used for this example:

{{content.firstName | Append: ' ' | Append: content.lastName}}

Here are the sample inputs and outputs:

Example output JSON to text

Transform XML to JSON

Here's the Liquid template that's used for this example:

[{% JSONArrayFor item in content -%}
      {{item}}
  {% endJSONArrayFor -%}]

The JSONArrayFor loop is a custom looping mechanism for XML input so that you can create JSON payloads that avoid a trailing comma. Also, the where condition for this custom looping mechanism uses the XML element's name for comparison, rather than the element's value like other Liquid filters. For more information, see Deep Dive on set-body Policy - Collections of Things.

Here are the sample inputs and outputs:

Example output XML to JSON

Transform XML to text

Here's the Liquid template that's used for this example:

{{content.firstName | Append: ' ' | Append: content.lastName}}

Here are the sample inputs and outputs:

Example output XML to text

Next steps