Liquid is an open-source template language developed by Shopify and written in Ruby. It is the resolution of Shopify themes and is used to load dynamic content on storefronts.
The codebase was ported to .NET as another open-source project called DotLiquid. Dynamics 365 Portals (formerly Adxstudio) use DotLiquid as the Liquid Template Engine of their portal. The syntax between the original liquid and dot liquid is very similar.
Within the CRM portal, we will be using it from the web template to retrieve data from CRM via FetchXML.
Where it can be used?
You can use liquid to create Web Templates, inside Copy (HTML) field of a Web Page, or in Code Snippets.
Let us consider a scenario in which we will search for an account by an account name and will return only contacts accounts associated with an account we are retrieving.
So follow the following steps:
Create the FetchXML query
Go to Advanced Find in Dynamics 365 create criteria as shown in the following screenshot. Behind the screen it will generate the FetchXML. So to download it click on the Download FetchXML button on top ribbon.
Here is the generated FetchXML
Create Web Template
Now follow the following steps to create a web template:
1. Under the Portals tab in Dynamics 365, click on Web Templates.
2. Click create new.
3. Enter your Liquid code into the Web Template with your revised XML and save.
Name: This is the name of the Web Template.
Website: This pull-down has the list of websites that are active in the portal. Select the website that will be using this FetchXML query.
MIME Type: "JSON"
Source: Enter the source code here
Here is the detail explaination of the above code.
Line 1-2: These are the parameters that are being passed into the Web Template.
Note: cacheString is a random number that is used to generate and pass to FetchXML query.
Line 4: This is a Liquid statement that names the FetchXML query. This line is stats that FetchXML starts here.
Line 5-22: This is a slightly altered version of the FetchXML.
Line 23: Close the FetchXML code that we started inline 4.
Note: Get data from the FetchXML and put it in the JSON format. This open square bracket is the start of that. It will allow us to return an array of objects.
After the square bracket, start a "for" loop with liquid to get everything returned from the FetchXML query. Use "for" loop to cycle through the FetchXML query name that we created on line 4 (accounts) and returning each object as an entity named "item".
Line 25-33: The data returned is JSON object. The format is name:value so on line 29 the name is "mainphone" and the value is the telephone1 returned from our FetchXML and contained in the item entity.
Lines 27-28: The primarycontactid is a lookup in Dynamics 365, the value returned from the FetchXML needs to define whether to get the id or the name. Here we are trying to retrieve both.
Line 34: Here there is a Liquid logic to add a comma to JSON format if there is more than one entity (in this case accounts) returned.
Note: Here its possible to return more than one entity if needed.
Line 35: Here Liquid for loop is ended and also close square bracket (]).
Create Page Template
Click create new.
Enter the following details and save.
Name: Name of Web Template
Website: Website on which Portal is run
Type: Web Template
Web Template: Select the web template that we created in step 2.
Use Website Header and Footer: Uncheck this if it is selected. It will add the header and footer to the data returned but we only want the JSON data returned.
Description: Add description.
Under the Portals tab in Dynamics 365 select the Web Pages option.
Click create new
Enter in the following data and save.
Name: Name for Web Page
Website: Website for Portal
Parent Page:This sets the parent page and affects the URL address used to call the FetchXML page. Mostly used page is Home page.
Partial URL: Set partial url.
Page Template:Page template from step 3
Publishing State: Select "Published" from this pull down to activate this page on the portal.
Hidden From Sitemap: Set it to Yes to hide Fetch query pages from the sitemap
To test your query we need to log into the portal. Login and then go to the URL you created and enter the parameters. The results can be seen below. It worked, the JSON is returned.
Note: If you only see two empty square brackets " [ ] " nothing got returned from your query. So check for following 3 points.
1. Check your Query
2. The entity you are trying to return is enabled on the portal through security
3. the person logged in has access to that account