Creating 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 Cloud organization.

In a Coveo-powered search interface, the source content is accessible to either everyone or the source creator only (see Content Security). 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

To allow Coveo to retrieve your ServiceNow content, you must create a crawling account.

This account must:

  • Have read access to the ServiceNow content you want to make searchable.

  • Have access to web services.

  • Have its time zone set to GMT.

You may also want to grant the account read access to the sys_audit_delete table to retrieve deletion changes.

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 Name

Enter your instance name. Typically, a ServiceNow instance URL includes the instance name.

Your instance URL is https://myinstance.service-now.com, so your instance name is myinstance.

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 (see Leverage Many Coveo Indexes). 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 name, 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.

    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.

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

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"
      ]
    }
  ]
}

“Content Security” Tab

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

“Access” Tab

In the Access tab, determine whether each group and API key can view or edit the source configuration (see Understanding 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.

If you remove the Edit access level from all the groups of which you’re a member, you won’t be able to edit the source again after saving. Only administrators and members of other groups that have Edit access on this resource will be able to do so. To keep your ability to edit this resource, you must grant the Edit access level to at least one of your groups.

Completion

Click Add 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 do not already appear on the Fields page (i.e., they do not already exist for another source), you must add them before building your source.

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.

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 (see the sysparm_query in the ServiceNow Table API Reference).

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.

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

What’s Next?

Recommended Articles