Contextual Queries and Liquid Objects

In addition to the usual Coveo Cloud query syntax, Coveo for Microsoft Dynamics 365 uses the Liquid query syntax to interact with CRM form content (see Coveo Cloud Query Syntax Reference). This syntax is similar to the Liquid object syntax, which is used for CRM Portal customization (see Liquid objects).

Available Liquid Objects

Coveo for Microsoft Dynamics 365 provides objects reading Microsoft Dynamics 365 form values. The table below lists these objects.

Object Description
form Reads field values from the CRM form. Uses Xrm.Page.getAttribute() method to retrieve the values.
record Reads field values from the CRM form. Uses Xrm.Page.data.entity.attributes method to retrieve the values. Includes an id key to inject the ID of the displayed record in Coveo queries.

form and record offer access to the same form fields, but they use different API calls to fetch them. To see which fields are available, execute one of the following lines in the development console of your browser when viewing the desired form in the Unified Interface. Alternatively, you can inspect the form configuration and get the field names from there.

Xrm.Page.getAttribute().forEach(att => console.log(att.getName()))
Xrm.Page.data.entity.attributes.forEach(att => console.log(att.getName()))

These commands print the field names that you can use in Liquid objects.

Form field values are scoped under the form object. It is therefore recommended to access the title form field with {{ form.title }}, for instance.

Interacting with Text Fields

The Liquid query syntax allows your Coveo for Microsoft Dynamics 365 search page to interact with the text fields of the CRM form in which the search page is embedded.

You embed a Coveo search panel in a support case form and want the title of the displayed case to influence the Coveo search results. You can inject the case title at query time using the following syntax:

{{ form.title }}

Interacting with Lookup Fields

Similarly, you can make the Coveo search panel take certain lookup fields into account when querying your index.

You embed a Coveo search panel in a support case form. You want the search results to be influenced by the content of cases previously solved for the customer that opened the displayed case. You can get the customer name or ID using the following syntax:

{{ form.customerid.id }} // Returns the customer's ID.
{{ form.customerid.name }} // Returns the customer's name.

Interacting with Option Set Fields

To have Coveo for Microsoft Dynamics 365 interact with Option Set fields such as statuscode, you can inject the string value of an option and the corresponding number in a query .

You embed a Coveo search panel in a support case form (see Adding a Coveo Search Page to an Entity View). You want the search results to be influenced by the content of cases in the same state as the displayed case. You can get the case state using the following syntax:

{{ form.statuscode.text }} // Returns the string value of the option, e.g., "In Progress".
{{ form.statuscode.value }} // Returns the option set number, e.g., 2.

Injecting Raw Strings

You can inject a raw string in a place that requires the Coveo Liquid query syntax using the following syntax:

{{ 'raw string' }}
{{ "another raw string" }}

Defining Custom Context Objects

You can specify your own context objects in a contextual query. You can either make context objects implement the CoveoForDynamics.IContextObject interface or use the predefined CoveoForDynamics.ContextObject class available in Coveo for Microsoft Dynamics 365 search pages.

You embed a Coveo search panel in a support case form (see Adding a Coveo Search Page to an Entity View). You want to use a custom object called user to boost information related to the support agent. You define your own context object:

var globalContext = Xrm.Utility.getGlobalContext();
var userData = {
    id: globalContext.getUserId(),
    name: globalContext.getUserName()
}
var userContextObject = new CoveoForDynamics.ContextObject(userData);
CoveoForDynamics.ContextObjects.register("user", userContextObject);

You then use this context object in a Coveo javascript component with {{ user.id }} and {{ user.name }}.

Formatting Form Values Using Filters

You can specify filters to format CRM form fields before they are injected in Coveo queries.

You embed a Coveo search panel in a support case form (see Adding a Coveo Search Page to an Entity View). You want to filter out the record being displayed by the CRM form. The field record.id returns a GUID formatted with dashes (-). You have to remove the dashes for the query to work properly.

{{ record.id }} // returns d4cde4f3-5f41-4cfe-9cd7-d1af54c873bc
{{ record.id | remove: "-" }} // returns d4cde4f35f414cfe9cd7d1af54c873bc

Available filters

Filter Description Example
remove Removes a value from a given string. {{ record.id | remove: "-","d" }}

Defining Custom Liquid Filters

You can define your own filters. To do so, you need to define a JavaScript function that takes a string as input, with as many other parameters as you need and returns a string. Then, register your function with the CoveoForDynamics.Filters.registerFilter method.

You embed a Coveo search panel in a support case form (see Adding a Coveo Search Page to an Entity View). Some field returns HTML. You would like to remove the HTML tags before injecting the string in your query.

var stripHtml = function(str) {
    return str.replace(/<\/?[^>]+(>|$)/g, "");
};
CoveoForDynamics.Filters.registerFilter("strip_html", stripHtml);