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 aren’t returned in the user’s search results.

In the Coveo for ServiceNow integration, a query filter applies globally to all queries originating from the widgets designated by a specific Scope/Component option combination.

You’ll 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. We strongly advise against creating a source whose content is accessible to everyone and using a pipeline filter to exclude sensitive information.

In the following cases, sensitive content from a source whose content is accessible to everyone 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.

Create a Coveo Query Filter

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

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 option value.

      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 query syntax expression or, if you rather need to define a query filter through custom logic, use the Script field.

    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.

  • Defining a dynamic query filter by getting the current user company ID:

      (function(){
          var currentUser = gs.getUser();
          return '@companyid=' + gs.info(currentUser.getCompanyId());
      })();
    
  • See also Example: Securing Knowledge Base Articles.

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).

Test 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 Relevance Inspector 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).

Add a Query Filter to an Update Set (Optional)

Thanks to ServiceNow update sets, you can group a series of changes to apply them all at once to another instance. This allows you to test your changes in a non-production instance before enforcing them in your production instance. Changes to Coveo query filters can be added to an update set for this purpose.

To add a query filter to your current update set, in the record form of the desired filter, under Related Links, click Add to Update Set.

Example: Securing Knowledge Base Articles

This query filter allows you to secure knowledge base articles. As a result, through a Coveo for ServiceNow search interface, an end user can only access published articles from the Global domain and from their own domain.

(function(){
    var user = gs.getUser();
    var userDomainId = user.getDomainID();
    var userFilters = [];
    if (gs.nil(userDomainId)) {
        // Blocks all content since all users must have a domain
        userFilters.push('NOT @uri');
    } else {
        // Filter: KB - domain
        // User is not at a top-level domain
        if (userDomainId != gs.getProperty('acme.int.coveo.toplevel_domain')) {
            userFilters.push('(NOT @snsysdomainsysid OR @snsysdomainsysid=="' + userDomainId + '")');
        }
    }
    // Filter: KB - state
    userFilters.push('(NOT @snworkflowstate OR @snworkflowstate==Published)');
    return userFilters.join(' AND ');
})();

What’s Next?

Recommended Articles