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.

You can use the Content Security tab to select whether the source content is accessible to everyone, the source creator only, or as determined by your source permissions system. By default, a ServiceNow source starts a rescan every day to retrieve ServiceNow content changes, i.e., item additions, modifications, and deletions (see Edit a Source Schedule).

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 in your ServiceNow source Content to Include configuration.

    • 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

      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:

Then, when adding or editing your ServiceNow source, follow the instructions below.

"Configuration" Tab

In the Add/Edit a ServiceNow Source panel, the Configuration tab is selected by default. It contains your source’s general and content information, as well as other parameters.

General Information

Source Name

Enter a descriptive name for your source.

Instance URL

Enter your instance URL.

EXAMPLE

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

Character Optical Recognition (OCR)

Check this box if you want Coveo Cloud to extract text from image files or PDF files containing images. OCR-extracted text is processed as item data, meaning that it’s fully searchable and will appear in the item Quick View.

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 to Include" Section

We recommend tailoring the default source JSON configuration to your needs. This code determines which objects and metadata Coveo indexes. By default, it retrieves incidents, problems, knowledge base articles, knowledge base questions, answers, and comments, catalog items, tasks, customer service cases, HR cases, and users. See Configuration Reference for details on each configuration property.

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 About ServiceNow Knowledge Blocks.

To index fields in child tables that are not included in the parent table, see Index Child-Only Table Fields.

EXAMPLE

With the following configuration, you index published knowledge base articles, catalog items, and incidents, as well as some relevant metadata, such as their author, their price, and their severity level respectively.

{
  "tables": [
    {
      "name": "kb_knowledge",
      "query": "workflow_state=published",
      "fields": [
        "article_type",
        "category",
        "description",
        "flagged",
        "kb_category",
        "kb_knowledge_base",
        "number",
        "published",
        "rating",
        "short_description",
        "text",
        "topic",
        "wiki",
        "workflow_state",
        "author",
        "meta",
        "sys_view_count",
        "valid_to"
      ],
      "references": {
        "author": [
          "name",
          "user_name",
          "title",
          "email"
        ],
        "kb_category": [
          "label",
          "value"
        ],
        "kb_knowledge_base": [
          "title"
        ]
      }
    },
    {
      "name": "sc_cat_item",
      "fields": [
        "availability",
        "billable",
        "cost",
        "description",
        "list_price",
        "meta",
        "name",
        "price",
        "short_description",
        "type"
      ],
      "references": {
        "category": [
          "title"
        ]
      }
    },
    {
      "name": "incident",
      "fields": [
        "category",
        "subcategory",
        "caused_by",
        "close_code",
        "incident_state",
        "parent_incident",
        "resolved_at",
        "severity"
      ]
    }
  ]
}
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 index the child table separately. To do so:

  1. In the JSON query field for the parent table, exclude the child table objects from the parent table using the expression sys_class_name!=<TABLE_NAME>, where TABLE_NAME is the child table to exclude.

  2. Add the child table that you want to index to the JSON configuration, and then add the desired child table fields to the fields array.

EXAMPLE

The table task has a child table named incident and another named change_request. You want to index the u_incident_special and u_change_special fields from incident and change_request respectively, which are not included in table task. To do so, exclude the child table objects from the parent table using "query": "sys_class_name!=incident^sys_class_name!=change_request", and then add the incident and change_request child tables to the JSON to include the u_incident_special and u_change_special fields repectively.

{
  "tables": [
    {
      "name": "task",
      "query": "sys_class_name!=incident^sys_class_name!=change_request",
      "fields": [
        "action_status",
        "approval",
        "assigned_to"
        "author"
      ],
    },
    {
      "name": "incident",
      "fields": [
        "u_incident_special",
        "action_status",
        "approval",
        "assigned_to"
        "author"
      ],
    },
    {
      "name": "change_request",
      "fields": [
        "u_change_special",
        "action_status",
        "approval",
        "assigned_to"
        "author"
      ],
    }
  ]
}

"Content Security" Tab

Select who will be able to access the source items through a Coveo-powered search interface. For details on these options, 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, determine whether each group and API key can view or edit the source configuration (see Resource Access):

  1. In the Access Level column, select View or Edit for each available group.

  2. On the left-hand side of the tab, if available, click Groups or API Keys to switch lists.

Completion

  • If you’re creating a new source, click Add and Build Source/Add Source.

  • If you’re editing an existing source, click Save and Rebuild Source/Save.

If you edited your source JSON configuration, create your source fields. Otherwise, proceed to Create Your Source Mappings.

Create Your Source Fields

If you edited the JSON configuration in the Content to Include section, you may have decided to index some metadata in fields that aren’t Coveo Cloud default fields.

If these fields don’t already appear on the Fields page (i.e., they don’t already exist for another source), you must add them before building your source.

EXAMPLE

You decided to retrieve picture URIs and to have Coveo Cloud populate the otheraddress field with this data. In the source JSON configuration, the item metadata therefore contains:

"otheraddress": "%[picture.uri]"

However, since the otheraddress field isn’t a default field like author or date and since no other source already uses it, you must create it.

Create Your Source Mappings

Once all the fields your source will populate appear on the Fields page, create a mapping rule for each for these fields.

In the Edit the Mappings of a Source panel, you can choose to create a mapping that applies to all indexed items or just to some specific ones (e.g., kb_incident items). For a list of the pieces of metadata we recommend you index with certain types of item, see Recommended Metadata.

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 Cloud extracts a title or a description to display instead.

Build or Rebuild Your Source

On the Sources page, in the source Status column, click Start initial build or Start required rebuild to respectively start retrieving the source content or make your changes effective.

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

Configuration Reference

tables (Array)

Each object in the tables array represents a ServiceNow table to index.

name (String, Required)

The table name in ServiceNow.

Example: sc_cat_item

query (String)

The query to perform to index specific objects in a table. Only the objects matching this query will be retrieved.

Use the ServiceNow syntax to formulate your query.

Example: workflow_state=published retrieves only the ServiceNow objects whose state is "Published".

fields (Array of String, Required)

The names of the metadata fields to index for each row in the table.

You don’t need to specify essential system fields such as sys_id and sys_updated_on, since Coveo always indexes this information.

Example:

"fields": [
  "category",
  "description",
  "type"
]

references (Object)

A key-value store in which each key represents the name of a ServiceNow object related to the requested table (e.g., "author"), and each value (array of string) represents a set of metadata fields to request from that object (e.g., ["name", "email"]).

Example:

"references": {
  "author": [
    "name",
    "title",
    "email"
  ]
}

The extracted metadata is prefixed with the reference key, e.g., author.name.

When you index the following item types, we recommend you index some basic pieces of metadata, which will be useful in your Coveo-powered search interface. Click the desired item type to jump to the recommended metadata.

incident

  • opened_by

    • name

    • sys_id

  • caller_id

    • name

    • title

    • sys_id

  • closed_by

    • name

    • sys_id

  • assigned_to

    • name

    • title

    • sys_id

  • cmdb_ci

    • name

    • sys_id

  • number

  • state

  • closed_at

  • impact

  • priority

  • work_notes

  • short_description

  • description

  • sys_id

  • incident_state

  • urgency

  • comments

  • comments_and_work_notes

  • category

  • sntable

  • short_description

kb_knowledge

  • author

    • name

    • sys_id

  • kb_category

    • label

    • sys_id

    • value

  • short_description

  • rating

  • description

  • text

  • image

  • sys_view_count

  • meta_description

  • meta

  • category

  • sntable

  • short_description

kb_social_qa_question

  • profile

    • sys_id

    • name

  • top_answer

    • sys_id

    • answer

    • vote

  • accepted_answer

    • sys_id

    • answer

    • votes

  • kb_category

    • label

    • sys_id

  • sys_id

  • question_details

  • sys_created_on

  • views

  • question

  • votes

  • sntable

  • question

sc_cat_item

  • category

    • title

    • sys_id

    • sys_name

  • delivery_time

  • type

  • price

  • image

  • ignore_price

  • omit_price

  • name

  • short_description

  • icon

  • description

  • sys_class_name

  • sys_id

  • cost

  • picture

  • sntable

  • short_description

sn_customerservice_case

  • parent

    • number

    • sys_id

  • closed_by

    • name

    • sys_id

  • assigned_to

    • name

    • sys_id

  • opened_by

    • name

    • sys_id

  • incident

    • number

    • sys_id

  • account

    • name

    • sys_id

  • product

    • sys_id

    • name

  • cmdb_ci

    • name

    • sys_id

  • contract

    • number

    • short_description

    • sys_id

  • number

  • state

  • impact

  • priority

  • short_description

  • sys_class_name

  • comments_and_work_notes

  • closed_at

  • subcategory

  • work_notes

  • description

  • close_notes

  • sys_id

  • urgency

  • action_status

  • category

  • sntable

  • short_description

sn_hr_core_case

  • parent

    • number

    • sys_id

  • additional_assignee_list

    • name

    • title

    • sys_id

  • closed_by

    • name

    • title

    • sys_id

  • assigned_to

    • name

    • title

    • sys_id

  • opened_for

    • name

    • title

    • sys_id

  • opened_by

  • hr_service

    • sys_id

    • name

  • cmdb_ci

    • name

    • sys_id

  • number

  • state

  • impact

  • priority

  • short_description

  • sys_class_name

  • comments_and_work_notes

  • escalation

  • details

  • closed_at

  • opened_at

  • work_notes

  • description

  • sys_id

  • urgency

  • sntable

  • short_description

Recommended Articles