Add a ServiceNow source

This is for:

Developer System Administrator

In order for your support agents and customers to be able to view items from your ServiceNow instance in their query results, as a member of the Administrators or Content Managers built-in groups, you must create a ServiceNow source in your Coveo organization.

Notes

  • The Coveo for ServiceNow integration isn’t required to create a ServiceNow source.

    You can create a ServiceNow source to index content from your ServiceNow instance even if you’re not using the Coveo for ServiceNow integration. That is, even if you don’t install the Coveo for ServiceNow application in your ServiceNow instance. For example, you can index your ServiceNow content so that the items appear in search results in a Coveo-powered search interface outside of ServiceNow.

  • A ServiceNow source isn’t required even if you’re using the Coveo for ServiceNow integration.

    Typically, you’ll want to index your ServiceNow content and make it searchable in ServiceNow when using the Coveo for ServiceNow integration. However, you can choose to index content only from other sources, or you can index content from ServiceNow as well as other sources.

Regardless of whether you’re using the Coveo for ServiceNow integration, the procedure to create a ServiceNow source is as detailed in this article.

To create a properly functioning ServiceNow source, you must:

  1. Create a crawling account.

  2. Create a ServiceNow source.

  3. Build or rebuild your source.

  4. Verify your source fields and mappings.

Tip
Leading practice

The number of items that a source processes per hour (crawling speed) depends on various factors, such as network bandwidth and source configuration. See About crawling speed for information on what can impact crawling speed, as well as possible solutions.

Source key characteristics

Features Supported Additional information

ServiceNow version

Latest cloud version

Following available ServiceNow releases

Indexable content

items from any ServiceNow system table, such as:

  • Knowledge base articles

  • Knowledge base questions

  • Knowledge base answers

  • Knowledge base comments

  • Problems

  • Incidents

  • Catalog items

  • Catalog tasks

  • Customer service cases

  • HR cases

Content update operations

refresh

check

By default, the refresh operation doesn’t take account of deleted records.

rescan

check

Takes place every day by default.

rebuild

check

Content security options

Same users and groups as in your content system

check

Coveo for ServiceNow only partially supports ServiceNow permissions. See "Content Security" tab for more information.

Specific users and groups

check

Everyone

check

Create a crawling account

Before you create your ServiceNow source, you must create a user in your ServiceNow instance that your source will use as a crawling account to retrieve your ServiceNow content and make it searchable.

  1. Create a user in your ServiceNow instance that will be used as the crawling account. Make sure to:

  2. Grant the crawling account read access to your ServiceNow content. To do so, assign the crawling account one or more user roles that have read access to the following ServiceNow tables, including all the corresponding table rows (records) and columns (fields).

    Tip

    To make this task easier to manage, create a user role in ServiceNow, such as coveo_crawling, that’s used only to provide read access to the crawling account, and then assign the user role to the following tables and tables rows as well as to the crawling account.
    Note

    The following tables must have access to web services. Ensure that the Allow access to this table via web services checkbox is enabled for the table in the Application Access tab in ServiceNow.

    • All the tables that you choose to index for your ServiceNow source.

    • All the following ServiceNow tables, including all the corresponding table rows (records) and columns (fields):

      Purpose Table

      Global

      sys_db_object

      sys_dictionary

      sys_group_has_role

      sys_properties

      sys_security_acl

      sys_security_acl_role

      sys_user

      Note

      To support locked-out ServiceNow users in your search interface, you must also grant the crawling account specific access to the locked_out field in the sys_user table.

      sys_user_grmember

      sys_user_has_role

      sys_user_role

      Domain Separation

      Note

      Requires the Domain Separation plugin.

      domain

      domain_contains

      Service Catalog and Knowledge Base

      kb_uc_can_contribute_mtom

      kb_uc_can_read_mtom

      kb_uc_cannot_read_mtom

      sc_cat_item_user_criteria_mtom

      sc_cat_item_user_criteria_no_mtom

      sc_category

      sc_category_user_criteria_mtom

      sc_category_user_criteria_no_mtom

      user_criteria

  3. Grant the crawling account access to locked-out user data in ServiceNow.

  4. (Optional) Set additional settings.

Support locked-out users

Your Coveo-powered search interface supports locked-out ServiceNow users. This means that users that are locked-out of their ServiceNow account won’t be able to access ServiceNow content in your search interface.

To configure support for locked-out users, you must grant the crawling account specific access to the locked_out field in the sys_user table via an access control list (ACL).

Important

You must still grant the crawling account specific access to the sys_user.locked_out field as detailed in this section even if you’ve already granted the crawling account access to the sys_user table and all its corresponding rows (records) and columns (fields).

This is because an ACL already exists by default in ServiceNow that limits access to the sys_user.locked_out field to admins only. Therefore, your crawling account won’t have access to the sys_user.locked_out field unless you grant it specific access.

If your crawling account is an admin account, the default ACL already gives the account access so no further action is required.

Create an ACL rule in your ServiceNow instance with the following configuration:

Type: record
Operation: read
Table: User (sys_user)
Field: Locked out (locked_out)
Requires role: <A role that's assigned to the crawling account>
ACL

Optional settings

  • For added security, enable the Web Service Access Only field for the crawling account. This sets the crawling account as a non-interactive account in ServiceNow.

  • By default, the crawler retrieves changes in content state, such as from "Published" to "Retired". To retrieve deletions of records as well:

    1. Grant the crawling account read access to the sys_audit_delete table.

    2. After you create your ServiceNow source:

      1. On the Sources (platform-ca | platform-eu | platform-au) page, click the ServiceNow source and then click More > Edit configuration with JSON in the Action bar.

      2. In the Edit configuration with JSON panel that opens, set the FetchDeletedRecords parameter value to true, and then click Save.

Add a ServiceNow source

Notes

  • The Coveo for ServiceNow integration isn’t required to create a ServiceNow source.

    You can create a ServiceNow source to index content from your ServiceNow instance even if you’re not using the Coveo for ServiceNow integration. That is, even if you don’t install the Coveo for ServiceNow application in your ServiceNow instance. For example, you can index your ServiceNow content so that the items appear in search results in a Coveo-powered search interface outside of ServiceNow.

  • A ServiceNow source isn’t required even if you’re using the Coveo for ServiceNow integration.

    Typically, you’ll want to index your ServiceNow content and make it searchable in ServiceNow when using the Coveo for ServiceNow integration. However, you can choose to index content only from other sources, or you can index content from ServiceNow as well as other sources.

Regardless of whether you’re using the Coveo for ServiceNow integration, the procedure to create a ServiceNow source is as detailed in this article.

  1. Ensure that you’ve created a crawling account.

  2. On the Sources (platform-ca | platform-eu | platform-au) page, click Add source, and then click ServiceNow.

    Tip
    Leading practice

    It’s best to create or edit your source in your sandbox organization first. Once you’ve confirmed that it indexes the desired content, you can copy your source configuration to your production organization, either with a snapshot or manually.

    See About non-production organizations for more information and best practices regarding sandbox organizations.

  3. Specify your source settings on the Add a ServiceNow source page. Refer to the following sections for detailed information on the source settings:

Note

You can save your source settings at any time by clicking Add and build source/Add source, or Save and rebuild source/Save. By default, a ServiceNow source starts a rescan every day to retrieve ServiceNow content changes, such as item additions, modifications, and deletions. However, you can edit your source rescan schedule.

"Configuration" tab

On the Add a ServiceNow source page, the Configuration tab is selected by default. It contains your source’s general information, as well as other parameters.

General information

Source name

Enter a name for your source.

Tip
Leading practice

A source name can’t be modified once it’s saved, therefore be sure to use a short and descriptive name, using letters, numbers, hyphens (-), and underscores (_). Avoid spaces and other special characters.
Instance URL

Enter your instance URL.

Example

Your instance URL is https://myinstance.service-now.com.

Optical character recognition (OCR)

If you want Coveo to extract text from image files or PDF files containing images, enable the appropriate option.

The extracted text is processed as item data, meaning that it’s fully searchable and will appear in the item Quick view. See Enable optical character recognition for details on this feature.

Project

If you have the Enterprise edition, use the Project selector to associate your source with one or multiple Coveo projects.

"Authentication" section

Select an authentication option:

  • If you select OAuth 2.0, which is the most secure and therefore recommended option:

    1. Click Authorize Account.

    2. In the Sign in to ServiceNow window that appears, enter your ServiceNow Instance URL, Client Id, and Client Secret, and then click Authorize.

      Tip
      Leading practice

      You can find the client ID and client secret in the Coveo application registry in ServiceNow as follows:

      1. In the Now Platform UI of your ServiceNow instance, navigate to System OAuth > Application Registry.

      2. In the Applications Registries list, click the Coveo registry.

      3. To view the client secret, switch the instance application to AI-Powered Search & Recommendations by Coveo in the ServiceNow banner, and then click Client Secret Lock next to the Client Secret field.

    3. In the ServiceNow window that appears, do one of the following:

      • If a login screen appears, enter the credentials of your source crawling account, and then click Login.

      • If a login screen doesn’t appear, ensure that the username that appears at the top of the ServiceNow window corresponds to your source crawling account. If it doesn’t correspond, click Not You?, enter the credentials of your crawling account, and then click Login.

        Authentication Window

    4. Click Allow.

Note

Once you’ve authorized your account, the OAuth 2.0 handshake must be refreshed once in a while. The default lifespan of a token is two years, but ServiceNow allows you to change this duration.

  • If you select Basic authentication, enter the Username and Password of a dedicated ServiceNow account that has access to the content you want to make searchable. See Source Credentials Leading Practices.

"Content security" tab

Select who will be able to access the source items through a Coveo-powered search interface. For details on this parameter, see Content security.

Note

Coveo for ServiceNow only partially supports ServiceNow permissions. If you select the Same users and groups as in your content system option, keep in mind that:

  • Coveo supports ServiceNow base system roles, user criteria, access control lists (ACLs), and domain separation.

  • Coveo doesn’t support ServiceNow advanced (scripted) permissions in both user criteria records and ACLs. If a user criteria record or ACL uses only advanced permissions, and no other condition such as roles, the user criteria record or ACL essentially has no user access criteria as far as Coveo is concerned. As a result, the associated indexed item will be accessible to everyone. However, you can replicate the advanced permissions using query filters, or you can use custom table fields to index user permissions in user criteria records with advanced permissions.
Important

When using the Everyone content security option, see Safely apply content filtering for information on how to ensure that your source content is safely filtered and only accessible by intended users.

"Access" tab

In the Access tab, specify whether each group (and API key, if applicable) in your Coveo organization can view or edit the current source.

For example, when creating a new source, you could decide that members of Group A can edit its configuration, while Group B can only view it.

For more information, see Custom access level.

"Content to include" tab

These settings determine which items and metadata your Coveo for ServiceNow source indexes.

Default configuration

When you create a new ServiceNow source, the source is preconfigured to retrieve metadata from certain basic tables and fields. However, we recommend that you modify the default configuration to suit your needs.

Tip
Leading practice

  • Set the View filter to Selected in the table list header to view only the tables that are currently set to be indexed by your source.

  • If your ServiceNow instance tables don’t appear in the Content to include tab, click Add source, and then re-open your source.

The following table lists the ServiceNow tables that are indexed by default:

Item Table label Table name

Incidents

Incident

incident

Problems

Problem

problem

Knowledge base articles

Knowledge

kb_knowledge

Catalog items

Catalog Item

sc_cat_item

Catalog tasks

Catalog Task

sc_task

Modify the source index configuration

This section describes how to select the objects and metadata that your Coveo for ServiceNow source indexes.

  1. In your ServiceNow source, select the Content to include tab.

    Content to Include

    1

    The system table list shows the tables that are available in the ServiceNow instance that you specified for the Instance URL field.

    2

    The column (fields) list shows the table fields, including fields from referenced tables, that correspond to the currently highlighted system table in the system table list.
    Tip
    Leading practice

    • Set the View filter to Selected in the table list header to view only the tables that are currently set to be indexed by your source.

    • If your ServiceNow instance tables don’t appear in the Content to include tab, click Add source, and then re-open your source.

    From the Content to include tab, you can:

    • Enable or disable a system table. Your source indexes the metadata for a table only when the table is selected.

    • Enable or disable fields for a system table. Your source indexes the metadata only from selected fields when the associated system table is enabled. You should limit the number of fields to retrieve to reduce the request payload and improve the general performance of the connector.

    • Apply a query to a selected system table to index or exclude specific records.

  2. To enable or disable a system table:

    1. In the left pane, enter the table label or name in the search field to locate the system table in the list.

    2. Check or clear the Select box for the table to enable or disable the table respectively.

      Note

      If you’re using knowledge blocks in your ServiceNow instance, and your ServiceNow source is configured to index knowledge articles, the ServiceNow source automatically indexes the content of knowledge blocks that are included in knowledge articles. For more information, see Index ServiceNow knowledge blocks.

  3. To select the table fields to index:

    1. If required, locate and click the corresponding system table in the left pane to open the corresponding column (field) list in the right pane. You must enable a system table to select its fields.

    2. In the right pane, enter the column label or name in the search field to locate the field in the list.

    3. Check or clear the Select box for the field to enable or disable the field respectively. Some essential system fields are always indexed by Coveo and can’t be disabled, such as sys_id and sys_updated_on. For reference fields, you can select the field to index the corresponding metadata, and then expand the field to also index a specific field from the referenced table.

      Example

      For the author field, you choose to index metadata from the name field from the referenced table as follows:

      Reference Field

      The extracted metadata for a field in a referenced table is always prefixed with the reference field (key). In this example, the extracted metadata is author.name.

      Note

      To index fields in child tables that aren’t, included in the parent table, see Index child-only table fields.

  4. To apply or edit a query for the table:

    1. If required, locate and click the corresponding system table in the left pane to open the corresponding column list in the right pane. You must enable a system table to apply or edit a table query.

    2. Click Query in the column list header, and then enter or edit the query expression in the text field using ServiceNow syntax. For example, enter workflow_state=published to retrieve only the table objects whose state is "Published".

    Note

    A view icon appears next to Query when the table contains a query expression.

    Applied Query

  5. Click Save and rebuild source/Save.

    Note

    Your ServiceNow source doesn’t automatically delete a field or its mapping rule if you choose to no longer index that field. Unused fields don’t impact your Coveo organization negatively, however you can choose to delete unused fields. Default Coveo fields, however, can’t be deleted. To delete an unused field, access the mapping panel for your source, locate and click the field mapping rule, and then click Delete. Then, delete the field from the Coveo index.

Index child-only table fields

When you choose to index a table that has one or more child tables, Coveo automatically indexes all child tables. However, if a child table has a field that’s not included in the parent table, Coveo doesn’t automatically index that child table field. To index a field that’s specific to a child table, you must exclude the child table from the parent table, and then index the child table separately. To do so:

  1. In your ServiceNow source, select the Content to include tab.

  2. In the left pane, enter the parent table label or name in the search field to locate the system table in the list.

  3. Click the parent table to open the corresponding column list in the right pane.

  4. Click the Query icon in the column list header.

  5. In the query filter text field, exclude the child table objects from the parent table by entering the expression sys_class_name!=<TABLE_NAME>, where TABLE_NAME is the child table to exclude. To exclude multiple child tables, use ^ to separate the table entries, such as "sys_class_name!=<TABLE_NAME>^sys_class_name!=<TABLE_NAME>". For example, to exclude the child tables incident and change_request, enter "sys_class_name!=incident^sys_class_name!=change_request".

  6. Index the child table separately as follows:

    1. In the left pane, enter the child table label or name in the search field to locate the table in the list.

    2. Enable the child table.

    3. Click the child table to open the corresponding column list, and enable the fields that you want to index.

Build or rebuild your source

You must build the source in order for Coveo to retrieve the source content and apply changes to your source settings. You can build or rebuild your source as follows:

  • You can choose to build when saving the source by clicking Add and build source/Save and rebuild source.

  • If you chose not to build when saving your source settings, you can build your source directly from the Sources (platform-ca | platform-eu | platform-au) page by clicking Launch build or Start required rebuild in the Status column for your source. If Launch build or Start required rebuild doesn’t appear on the Sources (platform-ca | platform-eu | platform-au) page for your source, click the source, and then click More > Rebuild in the Action bar.

Once the source is built, you can review its content in the Content Browser.

Note

By default, a ServiceNow source starts a rescan every day to retrieve ServiceNow content changes, such as item additions, modifications, and deletions. However, you can edit your source rescan schedule.

About source fields and mappings

mappings define what Coveo index fields contain for each source item.

Your ServiceNow source automatically includes mapping rules for the system table fields that are indexed by default. If you choose to index non-default fields, your ServiceNow source automatically creates the field in the Coveo index, as well as the associated mapping rule in your source. All fields are created using the ServiceNow prefix sn followed by the fieldname, and the mapping rule is set based on the fieldname metadata.

Example

You choose to index a field named closed_by. Your ServiceNow source creates a field named snclosedby with its mapping rule set to %[closed_by].

Verify and edit your source field mappings

The default mapping rules are suitable in most instances, however you can modify the mappings as required.

Example

In your ServiceNow source, the title field is mapped with the following rule: %[uri]. As a result, in your search interface, this item has a URL in place of its title. This makes it difficult for a search interface user to know at a glance whether this item is relevant to their query.

Search-result

Therefore, you could change the title field mapping rule to %[title] or %[short_description] so that Coveo extracts a title or a description to display instead.

Do one or both of the following to verify and edit your field mappings:

Create additional source fields and mappings (optional)

In certain situations, you may want to create a field in addition to the fields that are created automatically by your source. For example, you may want to create a field that’s used across many sources and mapped to different metadata for each source, or you may want to create a field that aggregates many metadata for a single source.

To create additional fields and mappings:

  1. Add a field to the Coveo index manually.

  2. Create a mapping rule in each source that you want to use the new field.

  3. Build the sources that you modified.

Safely apply content filtering

The best way to ensure that your indexed content is seen only by the intended users is to enforce content security by selecting the Same users and groups as in your content system option. Should this option be unavailable, select Specific users and groups instead.

However, if you need to configure your source so that the indexed source content is accessible to Everyone, you should adhere to the following leading practices. These practices ensure that your source content is safely filtered and only accessible by the appropriate users:

Following the above leading practices results in a workflow whereby the user query is authenticated server side via a search token that enforces the search hub from which the query originates. Therefore, the query can’t be modified by users or client-side code. The query then passes through a specific query pipeline based on a search hub condition, and the query results are filtered using the filter rules.

Configure the search token

When using query filters to secure content, the safest way to enforce content security is to authenticate user queries using a search token that’s generated server side. For instance, when using this approach, you can enforce a search hub value in the search token. This makes every authenticated request that originates from a component use the specified search hub, and therefore be routed to the proper query pipeline. Because this configuration is stored server side and encrypted in the search token, it can’t be modified by users or client-side code.

Implementing search token authentication requires you to add server side logic to your web site or application. Therefore, the actual implementation details will vary from one project to another.

The following procedure provides general guidelines:

  1. Authenticate the user.

  2. Call a service exposed through Coveo to request a search token for the authenticated user.

  3. Specify the userIDs for the search token, and enforce a searchHub parameter in the search token.

Note

You can specify other parameters in the search token, such as a query filter.

For more information and examples, see Search token authentication.

Required privileges

You can assign privileges to allow access to specific tools in the Coveo Administration Console. The following table indicates the privileges required to view or edit elements of the Sources (platform-ca | platform-eu | platform-au) page and associated panels. See Manage privileges and Privilege reference for more information.

Note

The Edit all privilege isn’t required to create sources. When granting privileges for the Sources domain, you can grant a group or API key the View all or Custom access level, instead of Edit all, and then select the Can Create checkbox to allow users to create sources. See Can Create ability dependence for more information.
Actions Service Domain Required access level

View sources, view source update schedules, and subscribe to source notifications

Content

Fields

View

Sources

Organization

Organization

Edit sources, edit source update schedules, and edit source mappings

Organization

Organization

View

Content

Fields

Edit

Sources

View and map metadata

Content

Source metadata

View

Fields

Organization

Organization

Content

Sources

Edit

What’s next?

Schedule source updates.