If you haven’t heard of it before, Liquid is a relatively easy-to-use and understand open-source language. It was created by Shopify and written in Ruby.
So, how and where do you use it?
Liquid can be used as a mapping language in integrations for transforming XML and JSON objects. These in turn, can be hosted as Azure functions which can use map data and build new JSON or XML objects which other systems can consume.
All of which is much quicker (and smarter) than writing a function to map the objects.
How come?
Do you need to quickly check a Liquid map’s output without redeploying for every change you make? With local testing, you can rapidly test changes within your code workspace and iteratively improve them.
This is especially useful when building JSON objects and testing the output iterations or conditional statements as you can see the structure and quickly correct it as required. You can also use Liquid for your debugging; simply put the payload as the input and run to see where the errors occur in the LiquidTransform. Any Liquid errors are printed in the console, which can speed up how quickly you can spot and fix them.
Another beneficial aspect of the LiquidTransform.exe is that you can leverage it to run automated tests on any Liquid transformation in a unit test suite.
Here’s how:
LiquidTransform.exe You can leverage an external tool which can be found here created by Samuel Kastberg. This executable allows you to pass parameters into a command terminal and will provide the transformed output using the DotLiquid engine.
After downloading the required files, open a command terminal and navigate to the folder level where the Liquidtransform.exe is currently situated.
You can then pass the command parameters to activate the mapping. The exe requires three parameters.
- The input data which the map reads from using a -t (template) prefix – Example: -t input.json
- The Liquid map will be used to transform using a -c (content) prefix – Example: -c mymap.Liquid
- The name of the output file for the mapping data to be written using a -d (destination) prefix Example : -d output.json
- Lastly, we append the -u (rubynaming) tag which will simulate the DotLiquid runtime using Azure Functions
However, note that you must use absolute paths when referencing the input parameters. An example snippet could look something like this: Liquidtransform.exe -t “C:\users\me\mymap.Liquid” -c ” C:\users\me\input.json” -d ” C:\users\me\output.json” –
Once executed it will output the result of the map into the output.json file.
You can use this within VS Code to provide an environment where you can change the map on one side, execute the query again and immediately see the output by opening output.json on the other side of VS Code as shown below:
Summary
Local testing with Liquid maps using the LiquidTransform.exe tool can save you time and effort in developing and refining JSON or XML objects.
It allows for quick testing and iteration without redeploying every time a change is made. Plus, it’s always helpful to have a tool that can assist with debugging and identifying errors in your code. Just make sure to use absolute paths when referencing input parameters!
So go ahead and try it out. And who knows, you might even discover a newfound love for DotLiquid maps. Happy coding!
For more information on the implementation used in Azure functions check out the git repository for dotLiquid here: https://github.com/dotliquid/dotliquid
