Using a ServiceNow data source - Amazon Kendra

Using a ServiceNow data source

Amazon Kendra can connect to your ServiceNow instance to index your knowledge bases and a service catalog. For a walkthrough of creating a ServiceNow data source, see Getting started with a ServiceNow data source (Console).

When you use Amazon Kendra to index a ServiceNow instance, you can choose to index public knowledge bases and public service catalogs, or you can use a query to index specific knowledge bases, including private ones. You can connect to a ServiceNow instance using basic authentication and a ServiceNow administrative user, or you can use an OAuth 2.0 token and a user with read permission on instance tables.

For public knowledge bases in your ServiceNow instance, Amazon Kendra indexes only public articles. A public knowledge base must have the public role under Can Read, and Cannot Read must be null or not set.

Authentication

There are two forms of authentication that you can use with ServiceNow. The first, basic authentication, enables Amazon Kendra to connect to the ServiceNow instance using a user name and password. The user must have administrative permissions to the ServiceNow instance.

The second, OAuth, uses a token that follows the OAuth 2.0 authentication specification to identify Amazon Kendra and a user name and password. The user name and password must provide access to the ServiceNow knowledge base and service catalog.

Basic authentication

When you use basic authentication, you provide the user name and password of an administrative user of your ServiceNow instance. Amazon Kendra uses these credentials to connect to ServiceNow.

The user name and password for the ServiceNow instance must be stored in an AWS Secrets Manager secret. If you use the Amazon Kendra console, you can enter the ServiceNow credentials there to create a new secret, or you can choose an existing secret. If you use the Amazon Kendra API, you must provide the Amazon Resource Name (ARN) of an existing secret that contains your ServiceNow user name and password.

The secret must contain the username and password of the ServiceNow account that you want Amazon Kendra to use to access ServiceNow. The following is the minimum JSON structure that must be stored in the secret.

{ "username": "user-name", "password": "password" }

The secret can contain other information, but Amazon Kendra ignores it. For more information, see What is Secrets Manager in the AWS Secrets Manager User Guide.

When you create the ServiceNow data source, you specify an IAM role that grants Amazon Kendra permission to access resources required to index your ServiceNow instance. The data source IAM role must have permission to access the secret and to use the AWS Key Management Service (AWS KMS) key to decrypt it. For more information, see IAM role for ServiceNow data sources.

OAuth authentication

When you use OAuth authentication to connect to ServiceNow, you provide the client ID and secret that identifies Amazon Kendra to ServiceNow. You also provide a user name and password that is used to access the knowledge bases and service catalog.

The client ID, client secret, user name, and password must be stored in an AWS Secrets Manager secret. If you use the Amazon Kendra console, you can enter the ServiceNow credentials there to create an Secrets Manager secret, or you can choose an existing secret. If you use the Amazon Kendra API, you must provide the Amazon Resource Name (ARN) of an existing Secrets Manager secret that contains your ServiceNow credentials.

The secret must contain the user name, password, client ID and client secret for your ServiceNow instance. The following is the minimum JSON structure that must be stored in the Secrets Manager secret.

{ "username": "user-name", "password": "password", "clientId": "client-id", "clientSecret": "client-secret" }

The secret can contain other information, but Amazon Kendra ignores it. For more information, see What is Secrets Manager in the AWS Secrets Manager User Guide.

Generating the client ID and secret

You generate the OAuth client ID and secret using the ServiceNow console and then copy them to the Amazon Kendra console. Create the client ID and secret using the following procedure.

To create a ServiceNow client ID and secret

  1. Log in to the ServiceNow console.

  2. From the left menu, choose System OAuth and then choose Application Registry.

  3. Choose New to create a new registry.

  4. For the type of OAuth application, choose Create an OAuth application endpoint for external clients.

  5. Enter a name.

  6. You can enter your own client secret, or you can have ServiceNow generate one for you. Leave the defaults for the other fields.

  7. Choose Submit to create the registry containing the OAuth client secret and ID.

  8. After the registry is created, choose it from the list of registries.

  9. Copy the client secret and ID. You'll need them when you create the ServiceNow data source.

Table permissions

When you use OAuth authentication, you provide a user name and password. Amazon Kendra sends the user name and password to ServiceNow. ServiceNow uses them to determine the access that Amazon Kendra has to the ServiceNow instance. To index a knowledge base and service catalog, the user must have read permission on the following tables.

  • kb_category

  • kb_knowledge

  • kb_knowledge_base

  • kb_uc_cannot_read_mtom

  • kb_uc_can_read_mtom

  • sc_catalog

  • sc_category

  • sc_cat_item

  • sys_attachment

  • sys_attachment_doc

  • sys_user_role

Connecting to a ServiceNow instance

You provide ServiceNow connection information in the Amazon Kendra console or by using an instance of the ServiceNowConfiguration data type. You must provide the following information:

  • The ARN of the Secrets Manager secret that contains the credentials required to access the ServiceNow instance.

  • The version of the ServiceNow instance. For Amazon Kendra, this is LONDON for the London version and OTHERS for all other versions.

  • The ServiceNow instance host. For example, if the URL of the instance is https://your-domain.service-now.com, the host is your-domain.service-now.com.

  • Whether to index knowledge articles, service catalogs, or both. You must also provide the name of the ServiceNow field that contains the document body.

You can optionally provide the following information:

  • A ServiceNow query that selects documents from one or more knowledge bases. The knowledge bases can be public or private. For more information, see Specifying documents to index with a query.

  • The name of the ServiceNow field that contains the document title. This is typically the ServiceNow title field. If you don't specify a document title field, Amazon Kendra uses the document ID as the title.

  • Whether Amazon Kendra should index attachments to knowledge base or catalog items. If you choose to index attachments, you can specify the file type of attachments to exclude from the index.

  • Field mappings that map fields in your ServiceNow instance to fields in your Amazon Kendra index. For more information, see Mapping data source fields.

  • An inclusion pattern to specify the file type of document attachments to include in the index. If you specify an inclusion pattern, any attachment that doesn't match the pattern isn't indexed. If the pattern includes file types that Amazon Kendra does not support, those files won't be included. For a list of supported file types, see Types of documents.

  • An exclusion pattern to specify the file type of document attachments to exclude from the index. If you specify an exclusion pattern, any attachment that doesn't match the pattern is indexed.

If you specify both an inclusion and an exclusion pattern, attachments that match the exclusion pattern won't be indexed even if they match the inclusion pattern.

After you sync the data source for the first time, the inclusion and exclusion patterns can't be changed.

You can map ServiceNow properties to Amazon Kendra index fields. The following table shows the ServiceNow knowledge article properties that can be mapped and a suggested Amazon Kendra index field. You can also create custom ServiceNow fields that you map to Amazon Kendra index fields.

ServiceNow field name Suggested Amazon Kendra field name
content _document_body
displayUrl sn_display_url
first_name sn_ka_first_name
kb_category sn_ka_category
kb_catagory_name _category
kb_knowledge_base sn_ka_knowledge_base
last_name sn_ka_last_name
number sn_kb_number
published sn_ka_publish_date
repItemType sn_repItemType
short_description _document_title
sys_created_by sn_createdBy
sys_created_on _created_at
sys_id sn_sys_id
sys_updated_by sn_updatedBy
sys_updated_on _last_updated_at
url sn_url
user_name sn_ka_user_name
valid_to sn_ka_valid_to
workflow_state sn_ka_workflow_state

The following table shows the ServiceNow catalog properties that can be mapped and a suggested Amazon Kendra field.

ServiceNow field name Suggested Amazon Kendra field name
category sn_sc_category
category_full_name sn_sc_category_full_name
category_name _category
description _document_body
displayUrl sn_display_url
repItemType sn_repItemType
sc_catalogs sn_sc_catalogs
sc_catalogs_name sn_sc_catalogs_name
short_description _document_body
sys_created_by sn_createdBy
sys_created_on _created_at
sys_id sn_sys_id
sys_updated_by sn_updatedBy
sys_updated_on _last_updated_at
title _document_title
url sn_url