Configure query filters

This is for:

Developer System Administrator

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.

Example

You apply 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 that originate from the widgets that are designated with a specific Scope/Component option combination.

Query filters are typically used to ensure that Coveo for ServiceNow components in your public-facing and internal portals only return items intended for their respective audiences.

Warning
WARNING

Filters, by themselves, don’t 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.

For example, 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.

However, if your ServiceNow source content security option is set to Everyone, we recommend that you secure your content by enforcing the search hub at the search token level. See Safely Apply Content Filtering for information on how to ensure that your source content is safely filtered and only accessible by the appropriate users.

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.

      Example

      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.

      Important

      • Component-specific query filters override scope-specific query filters. This means that when both a scope-wide and a component-specific query filter applies for a given component, only the component-specific query filter is used. If you want a scope-specific query filter to apply in addition to a component-specific filter, you must include the scope-specific query filter expression in your component-specific query filter (see examples).

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

    3. In the Filter field, enter a query syntax expression, or use the Script field if you need to define a query filter using custom logic.

    4. Click Submit.

Examples

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

  • You want the @source=="Help Section" scope query filter from the first example above to also apply to your Case Deflection panels (second example). Since component-specific query filters override scope-specific query filters, you include the @source=="Help Section" expression in your case deflection query filter by setting Filter to @source=="Help Section" @date>today-1y.

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

Test a Coveo query filter

Once you create a Coveo query filter in ServiceNow, we recommend that you test the query filter. To do so:

  1. In your ServiceNow instance, access the Coveo-powered search interface in the widget for which you set the query filter.

  2. Perform a relevant query that allows you to test the query filter.

  3. Visually inspect the search results to ensure that the query filter is successfully applied.

Example

You want to test the functionality of a Coveo query filter with the following settings:

  • Scope is set to Customer Service Portal

  • Component is set to Case Deflection Widgets

  • Filter is set to @source=="Help Section" @date>today-1y

Access the Case Deflection panel in your Service Portal, and perform a query that should return results from multiple sources and varying dates. Inspect the search results to ensure that only items from the Help Section appear, and that the items were updated or created less than a year ago.

Add a query filter to an update set (optional)

Coveo query filter records aren’t automatically saved to your current ServiceNow update set. If you’re testing your Coveo query filters in a non-production instance before enforcing them in your production instance, you can use a Global UI Action to add Coveo query filter records to your current 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?

Configure your Coveo Machine Learning models.