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:

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.

    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

      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 page:

        1. Click the ServiceNow source.

        2. In the Action bar, click More, and then select Edit JSON.

        3. Set the FetchDeletedRecords parameter value to true.

        4. Click Save.

Add or Edit a ServiceNow Source

Before you start:

To add or edit your source:

  1. On the Sources 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, in the Action bar click Edit.

  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:

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.

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.

Since the OCR feature is available at an extra charge, you must first contact Coveo Sales to add this feature to your organization license. You can then enable it for your source.

Index

When adding a source, if you have more than one logical (non-Elasticsearch) index in your organization, select the index in which the retrieved content will be stored. If your organization only has one index, this drop-down menu isn’t visible and you have no decision to make.

  • To add a source storing content in an index different than default, you need the View access level on the Logical Index domain (see Privilege Management and Logical Indexes Domain).

  • Once the source is added, you can’t switch to a different index.

"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. Your client ID and client secret can be found in the Coveo application registry:

      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. In the ServiceNow window that appears, enter the credentials of your source crawling account, and then click Login. See Source Credentials Leading Practices.

    4. Under [Application registry name] would like to connect to your ServiceNow account on instance [instance name], click Allow.

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.

If you select the Determined by source permissions option, keep in mind that permission indexing is partially supported. 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.

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

  • 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

Knowledge base questions

Social Q&A Question

kb_social_qa_question

Knowledge base answers

Social Q&A Answer

kb_social_qa_answer

Knowledge base comments

Social Q&A Comment

kb_social_qa_comment

Catalog items

Catalog Item

sc_cat_item

Catalog tasks

Catalog Task

sc_task

Customer service cases

Case

sn_customerservice_case

HR cases

HR Case

sn_hr_core_case

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

      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.

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

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

    Applied Query

  5. Click Save and rebuild source/Save.

    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 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 in the Sources page for your source, click the source, click More, and then click Rebuild.

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

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.

Recommended Articles