Configuring Coveo Query Filters

A Coveo™ query filter is a query syntax expression that gets added to the constant query expression (cq) 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.

You applied the @source=="Help Section" query filter to the widgets of your Service Portal. As a result, @source=="Help Section" is added to any query sent to Coveo via these widgets. So, if a user types Speedbit watch wristband in the Coveo Searchbox widget, the items returned are those that match these keywords and that come from the Help Section source. Items matching these keywords but coming from another content source are not returned in the user’s search results.

In the Coveo for ServiceNow integration, a query filter applies globally to all queries originating from a specific component/scope combination (see About the Scope and Component Options).

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.

  • Component-specific query filters override scope-specific query filter. So, if you want a scope-specific query filter to apply in addition to a component-specific filter, you must adapt the latter so that it includes the former (see note below).

  • Nested queries should never be in a query filter, as they prevent caching and will slow down all queries.

Filters, by themselves, do not protect the security of filtered content. Never add a source with public access when it contains sensitive information and use a pipeline filter to exclude it.

In the following cases, sensitive content from a public source could be exposed:

  • A colleague not understanding the reason for the filter could modify or remove the filter.

  • Using other pipelines not having a similar filter from other search interfaces or directly from the API.

You can ensure security by enforce the search hub at the search token level (see Search Token Authentication). Moreover, search hubs defined on the client-side that are used as conditions in pipelines do not safeguard the security of your filters.

Creating a Coveo Query Filter

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

  1. In the Now Platform UI of your ServiceNow instance:
    1. Navigate to Coveo > Query Filters.
    2. Click New.
    3. In the new record form:
      1. In the Scope field, enter the target widget scope (see About the Scope and Component Options).

        Customer Service Portal

      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.
      3. In the Filter field, enter a valid query syntax expression (see Coveo Cloud Query Syntax Reference).

        @author="John Smith"

        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 Submit.
  • 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 Customer Service Portal, 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 Customer Service Portal and Component to Case Deflection Widgets.

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" scope query filter from the example above to also apply to your Coveo case deflection panels, you must include this 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.

  1. Navigate to a page within the scope (and possibly, using the specific component) of the query filter that 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 (Coveo ML) models (see Configuring Your Query Pipelines and Coveo ML Models).