Configuring Coveo Query Filters

A Coveo™ query filter is a query syntax expression (e.g., @source=="Help Section") that gets added to the constant query expression of a query through the search token used to authenticate the search request in order to limit that query to a specific subset of items in the index.

In the Coveo for ServiceNow integration, a query filter can apply globally to all queries originating from a specific scope (e.g., to all Coveo for ServiceNow components in your Service Portal), or only to queries originating from a specific component/scope combination (see Standard Components and Scopes). Queries originating from a component for which both a scope-wide and a component-specific query filter would apply use the component-specific query filter only (the scope-wide query filter is ignored for that component).

You will typically use query filters to ensure that Coveo for ServiceNow components in your public-facing and internal portals only return items intended for their respective audiences.

Standard Components and Scopes

The following table lists the standard valid Coveo for ServiceNow component/scope combinations:

Component Scope
coveo-main-search CustomerServicePortal
coveo-searchbox CustomerServicePortal
coveo-deflection-2column CustomerServicePortal
coveo-case-deflection CustomerServicePortal
coveo-agent-panel Fulfiller

Creating a Coveo Query Filter

The following procedure explains how a ServiceNow instance administrator or developer can create a new Coveo query filter.

To create a new Coveo query filter

  1. In the Now Platform UI of your ServiceNow instance:
    1. Navigate to Coveo > Coveo Query Filters.
    2. Click New.
    3. In the new record form:
      1. In the Scope field, enter the scope you want to define a query filter for (see Standard Components and Scopes).

        Specifying a value for the Scope field is mandatory.

      2. If you want to create a component-specific query filter, in the Component field, enter the name of the target Coveo for ServiceNow component (see Standard Components and Scopes).
      3. In the Filter field, enter a valid query syntax expression (see Coveo Cloud Query Syntax Reference).

        If you need to define a query filter through custom logic rather than as a hard-coded string, use the Script field rather than the Filter field.

        Defining a dynamic query filter by getting the current user company ID (see ServiceNow API Reference - GlideSystem)

        function filter() {
            var currentUser = gs.getUser();
            return '@companyid=' + gs.info(currentUser.getCompanyId());
        }
        filter();
        
      4. Click the Submit button.
  • You want queries originating from your Service Portal to be limited to items from the Help Section source in your index. You create a @source=="Help Section" query filter, setting Scope to CustomerServicePortal, and leaving Component empty.
  • You want queries originating from case deflection panels in your Service Portal to be limited to items updated less than a year ago. You create a @date>today-1y query filter, setting Scope to CustomerServicePortal and Component to coveo-deflection-2column (or coveo-case-deflection).

    Remember that when both a scope-wide and a component-specific query filters would apply for a given component, only the component-specific query filter is used.

    This means that if you want the @source=="Help Section" expression from the first example to also apply to your Coveo case deflection panels, you must include that expression in your component-specific query filter (i.e., set its Filter to @source=="Help Section" @date>today-1y).

Testing a Coveo Query Filter

The following procedure explains how a ServiceNow instance administrator or developer can test a previously created Coveo query filter.

To test a Coveo query filter

  1. Navigate to a page within the scope (and possibly, using the specific component) of the query filter you want to test (e.g., https://myinstance-service-now.com/sp?id=search).
  2. In the URL query string, add &debug=true, then press Enter on your keyboard.
  3. Click the Relevance Inspector button that now appears on top of the search component.
  4. In the Relevance Inspector modal:
    1. Select the Execution Report tab.
    2. In the Authentication table, find the Pipeline Output > Query restriction > filter cell; its value should correspond to the expression of the most specific query filter defined for that Coveo for ServiceNow component (e.g., @date>today-1y).

What’s Next

You should now access your Coveo Cloud organization through the Coveo Cloud administration console to configure your query pipelines and Coveo Machine Learning models (see Configuring Your Query Pipelines and Coveo ML Models).