Create a ServiceNow Source

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.

To create a properly functioning ServiceNow source, you must:

Tip

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

Searchable content types

check

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

Determined by source permissions

check

Coveo for ServiceNow only partially supports ServiceNow permissions. Coveo supports ServiceNow base system roles, user criteria, ACLs, and domain separation. Coveo does not support ServiceNow advanced (scripted) permissions. 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.

Source creator

check

Everyone

check

Create a Crawling Account

Before you create your ServiceNow source, you must create a crawling account in ServiceNow. The crawling account is essentially a user in ServiceNow that is used only by your Coveo ServiceNow source to retrieve your ServiceNow content and make it searchable.

When creating the crawling account:

  • Set the crawling account Time Zone to GMT.

  • Set the crawling account credentials based on the Source Credentials Leading Practices.

  • Grant the crawling account read access to the following ServiceNow tables by assigning one or more ServiceNow user roles, which have read access to the tables, to the crawling account.

    Tip: To make this task easier to manage, create a user role in ServiceNow, such as coveo_crawling, that is used only to provide read access to the crawling account, and then assign the user role to the tables below as well as to the crawling account.

    Note

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

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

    • All of the following ServiceNow tables:

      Purpose Table

      Global

      sys_user

      sys_security_acl

      sys_security_acl_role

      sys_user_role

      sys_user_grmember

      sys_user_has_role

      sys_group_has_role

      sys_db_object

      sys_dictionary

      Domain Separation

      Note

      Requires the Domain Separation plugin.

      domain

      domain_contains

      Service Catalog and Knowledge Base

      user_criteria

      sc_category

      sc_category_user_criteria_mtom

      sc_category_user_criteria_no_mtom

      sc_cat_item_user_criteria_mtom

      sc_cat_item_user_criteria_no_mtom

      kb_uc_can_read_mtom

      kb_uc_cannot_read_mtom

      kb_uc_can_contribute_mtom

  • 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. On the Sources (platform-eu | platform-au) page, click the ServiceNow source, and then click More > Edit JSON in the Action bar.

      3. In the Edit a Source JSON Configuration panel that opens:

        1. Set the FetchDeletedRecords parameter value to true.

        2. Click Save.

Add or Edit a ServiceNow Source

Before you start:

To add or edit your source:

  1. On the Sources (platform-eu | platform-au) page, do one of the following:

    • To create a new source, click Add source, and then click ServiceNow.

    • To edit an existing source, click your ServiceNow source, and then click Edit in the Action bar.

  2. Specify your source settings in the Add/Edit a ServiceNow Source subpage. 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

In the Add/Edit a ServiceNow Source subpage, 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

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.

Character Optical Recognition (OCR)

If you want Coveo to extract text from image files or PDF files containing images, check the appropriate box. OCR-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.

Note

Contact Coveo Sales to add this feature to your organization license.

"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

      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 have 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

If you select the Determined by source permissions option, keep in mind that Coveo for ServiceNow only partially supports ServiceNow permissions. Coveo supports ServiceNow base system roles, user criteria, ACLs, and domain separation. Coveo does not support ServiceNow advanced (scripted) permissions. 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

We strongly advise against creating a source whose content is accessible to everyone. However, if you need to configure your source so that the indexed source content is accessible to Everyone, 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, set whether each group and API key can view or edit the source configuration (see Resource Access):

  1. If available, in the left pane, click Groups or API Keys to select the appropriate list.

  2. In the Access Level column for groups or API keys with access to source content, select View or Edit.

"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
  • 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, click 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
    • 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 cannot 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 are not 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 is not included in the parent table, Coveo does not automatically index that child table field. To index a field that is 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, click 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.

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 an 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 multiple sources and mapped to different metadata for each source, or you may want to create a field that aggregates multiple 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.

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

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 either the Source creator or Determined by source permissions option when available.

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 to ensure that your source content is safely filtered and only accessible by the appropriate users:

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.

What's next for me?