Set up the ServiceNow service for ServiceNow Knowledge connector ingestion

The ServiceNow Knowledge Microsoft 365 Copilot connector enables organizations to index ServiceNow knowledge-base articles into Microsoft 365 Copilot and search experiences. This article provides information about the configuration steps that ServiceNow admins must complete before your organization deploys the ServiceNow Knowledge connector.

For information about how to deploy the connector, see Deploy the ServiceNow Knowledge connector.

Setup checklist

The following checklists list the steps involved in configuring the environment and setting up the connector prerequisites.

Configure the environment

Set up prerequisites

Configure the ServiceNow environment

The following sections describe the admin tasks to configure the ServiceNow environment to enable and optimize the connection.

Identify the ServiceNow instance URL

The ServiceNow instance URL generally has the following format:

https://<your-organization-name>.service-now.com

To verify the URL for your ServiceNow instance, check the ServiceNow admin dashboard or the sign in URL used by your organization.

If you have a custom URL:

• In your ServiceNow instance, go to All > Custom URL > Custom URLs.

Identify the ServiceNow portal configuration

By default, when users select links generated by Copilot for ServiceNow content, the URLs follow the standard format:

https://<your-organization-name>.service-now.com/kb_view.do?sys_kb_id=bf1ab5ee47c31e90af178339736d

If your organization uses a different URL, you can customize the URL when you deploy the connector. For more information, see Customize values for certain schema properties.

Define ServiceNow attribute mapping

By default, Microsoft Entra ID maps identities from your data source by checking whether the email ID of ServiceNow users matches the user principal name (UPN) or Mail attribute in Microsoft Entra ID.

If this default mapping doesn’t meet your organization’s needs, you can define a custom mapping formula. For more information, see Map your non-Entra ID identities.

Check for advanced scripts and hierarchical permissions in ServiceNow

Determine whether knowledge articles in your ServiceNow environment have the following settings:

• Advanced scripts enabled in User Criteria
• Hierarchical permissions configured

These settings can affect indexing behavior and access control when content is surfaced in Microsoft 365 experiences like Copilot.

To determine whether any User Criteria has advanced scripts enabled, run the following API call:

<ServiceNowURL>/api/now/table/user_criteria?advanced=true&sysparm_limit=1

If your instance uses advanced script-based user criteria, select Advanced flow when you deploy the connector. For more information, see Choose flow based on user criteria.

What are hierarchical permissions?

ServiceNow Knowledge supports setting permissions at both the knowledge base (parent) level and the individual article (child) level. These permissions are evaluated together to determine whether a user has access to an article. This model is referred to as hierarchical permissions.

Hierarchical permissions are supported for the ServiceNow Knowledge connector (preview only). This feature isn't available in government or sovereign clouds or dedicated forests in multi-tenant environments. For more information, see Set up hierarchical permissions (preview).

Set up connector prerequisites

The following sections describe the prerequisite steps to complete before deploying the ServiceNow connector.

Create service account and set up permissions to index items

To connect to ServiceNow and allow the ServiceNow Knowledge connector to update items regularly, you need a service account with read access to specific ServiceNow table records. The following table lists the required table records.

** Access to these tables is only required when you choose the simple flow. If you choose advanced flow for reading user criteria, you don't need access to these tables.

You can create and assign a role for the service account you use to connect with Microsoft Search. For more information, see Assign a role to a user. You can assign read access to the tables to the role you create.

For information about how to create a user, assign a role, and grant read permissions on all the applicable table records, see Grant table access to a user in ServiceNow.

If the service account doesn't have the required permissions—or if row or field-level permissions are restricted—specific items are excluded from indexing on the Microsoft side.

If the service account doesn’t have access to the full User Criteria table, inconsistent behavior related to user permissions, including unintended content oversharing, can occur.

Identify item count for ingestion

The following default filter is applied during indexing. If you need to make changes, edit the query string during connector setup. For more information, see Customize query string.

active=true^workflow_state=published

To verify the item count expected for ingestion:

1. Go to the following URL: https://<instance-name>.service-now.com/api/now/table/kb_knowledge?sysparm_fields=sys_id&workflow_state=published. This URL opens a list of sys_ids.

   Note

   If you edit the default query string for indexing selected articles, use the corresponding URL to reflect those query conditions.

2. Open Developer Tools in the same window and type the following code in the console window:

       fetch('<<same URL as in 1>>')
       .then(res => res.json())
       .then(data => console.log("Count of sys_ids:", data.result.length))
       .catch(err => console.error(err));
   

3. Note the item count.

When the connector is set up and item sync is completed, you can check the indexed item count against this expected count to verify that all articles are indexed. For more information, see View connection statistics.

Set up REST API

To allow the connector to fetch advanced user criteria, create a scripted REST API in your ServiceNow instance.

• Elevate your role in ServiceNow to security_admin.

Create access control:

1. In ServiceNow, go to All > System Security > Access Control (ACL).
2. Choose New to create a new ACL.
3. Set the following values:
   • Type: REST_Endpoint
   • Operation: Execute
   • Name: Microsoft Copilot
   • Role: admin (or the same role assigned to the crawling account)
4. Choose Submit.

Create the scripted REST API:

1. Go to All > System Web Services > Scripted Web Services > Scripted REST APIs.
2. Choose New.
3. Enter the following information:
   • Name: Microsoft Copilot
   • API ID: microsoft_copilot
4. Choose Submit.
5. From the Scripted REST API list page, choose Microsoft Copilot.
6. Set Default ACLs to Microsoft Copilot. To avoid any issues with authorization, also add the Scripted REST External Default ACL.

Add a resource to the API:

1. On the Resources tab, choose New.

2. Fill in the details:

   • Name: GetAllUserCriteria
   • Relative Path: /user_criteria
   • Script: Paste the following code:

   (function execute (/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
       var queryParams = request.queryParams;
       var user = new String(queryParams.user);
       return (new sn_uc.UserCriteriaLoader()).getAllUserCriteria(user);
   })(request, response);
   

3. Make sure both of the following are checked:

   • Requires authentication
   • Requires ACL authorization

4. Make sure that ACLs is set to Microsoft Copilot. To avoid any issues with authorization, also add the Scripted REST External Default ACL.

5. Choose Update.

To verify the setup:

1. Confirm that the following is the Resource Path: /api/<API Namespace>/microsoft_copilot/user_criteria.
2. Choose Update to save the configuration.

The Microsoft 365 admin enters the API Namespace when they deploy the ServiceNow Knowledge connector. In the following example, the API namespace is abcdef.

/api/abcdef/microsoft_copilot/user_criteria

Set up hierarchical permissions (preview)

Hierarchical permissions allow the ServiceNow Knowledge connector to evaluate user permissions for any ServiceNow knowledge article. The connector evaluates the user criteria applied at the knowledge base (parent) and the knowledge article (child) level according to the rules that ServiceNow uses. For more information about how ServiceNow evaluates article permission, see Managing access to knowledge bases and knowledge articles.

To set up hierarchical permissions:

• During connector deployment, for Select based on your user criteria setup in ServiceNow, choose Advanced. If you chose Simple when you set up the connector, update your existing connector to use Advanced.

  Note

  When you choose Advanced, you must configure scripted REST API in ServiceNow in your ServiceNow instance **when you select "Advanced". Follow the steps documented in Set up REST API.

• Provide read access to the sys_properties table to the service account used for connector setup. For more information, see Grant table access to a service account in ServiceNow.

  Note

  • If the user and role is already set up, follow the steps in the Grant row-level access and Grant field-level access sections and add the role (Copilot Connector Account) to the new ACLs you create for the sys_properties table access.

• Use * in the field name to apply access to all fields for the table.

Internally, you need read only access to the name and value field for the following properties, which are critical for evaluating hierarchical ACL:

• glide.knowman.apply_article_read_criteria
• glide.knowman.block_access_with_no_user_criteria

If you don't want to provide access to all the fields in the sys_properties table, to restrict the account to have access only to required fields:

1. Create a new ACL and grant access to row-level access to the sys_properties table only for the specific properties you want to read. Provide the following values:

   1. Type: record
   2. Application: Global
   3. Active: checked
   4. Decision Type: Allow if
   5. Admin overrides: checked
   6. Operation: read
   7. Name: System Property [sys_properties]. Keep the adjacent field cell as --None--.
   8. Applies To:
      1. Select Name, operator is, and provide the field name: glide.knowman.apply_article_read_criteria.
      2. Select the OR operator.
      3. In the second line, select Name, operator is, and provide the field name: glide.knowman.block_access_with_no_user_criteria.
   9. Under Conditions > Requires Roles, select the role for which you want to allow this ACL, and create the ACL.

2. Create another new ACL and grant access to the Name field for the property. Provide the following values:

   1. Type: record
   2. Application: Global
   3. Active: checked
   4. Decision Type: Allow if
   5. Admin overrides: checked
   6. Operation: read
   7. Name: System Property [sys_properties]. In the adjacent field, select Name.
   8. Applies To:
      1. Select Name, operator is, and provide the field name: glide.knowman.apply_article_read_criteria. 1. Select the OR operator. 1. In the second line, select Name, operator is, and provide the field name: glide.knowman.block_access_with_no_user_criteria.
   9. Under Conditions > Requires Roles, select the role for which you want to allow this ACL, and create the ACL.

3. Create another new ACL and grant access to the Value field for the property. Provide the following values:

   1. Type: record
   2. Application: Global
   3. Active: checked
   4. Decision Type: Allow if
   5. Admin overrides: checked
   6. Operation: read
   7. Name: System Property [sys_properties]. In the adjacent field, select Value.
   8. Applies To:
      1. Select Name, operator is, and provide the field name: glide.knowman.apply_article_read_criteria. 1. Select the OR operator. 1. In the second line, select Name, operator is, and provide the field name: glide.knowman.block_access_with_no_user_criteria.
   9. Under Conditions > Requires Roles, select the role for which you want to allow this ACL, and create the ACL.

The three ACLs you created allow you to restrict the service account to only the necessary permissions. This restriction allows it to fetch the required details to determine the permission evaluation flow in your ServiceNow instance.

Add Microsoft 365 IP address to the allowlist

If any network configurations—such as firewall or proxy settings—block access to ServiceNow, make sure to add the IP addresses listed in IP firewall rules to the allowlist.

For information about ServiceNow-specific controls, see IP Address Access Control.

Resolve connector setup issues with ServiceNow SSO configuration

If your ServiceNow instance is configured with single sign-on (SSO), you might encounter the following issues during connector setup:

• During the OAuth process, a Logout successfully window might appear without prompting for ServiceNow credentials.
• Microsoft 365 admin credentials might be used to authorize the ServiceNow connection instead of the intended service account.

By default, ServiceNow attempts to connect using Microsoft 365 admin credentials through SSO from a browser sign in. This behavior can cause the connection to fail and result in the Logout successfully message.

To resolve these issues:

1. Open a private browser window and sign in using the ServiceNow service account credentials.

2. In a new tab, sign in to the Microsoft 365 admin center using Microsoft 365 admin credentials.

   Note

   The initial sign in might default to ServiceNow SSO. If that happens, switch to the correct credentials.

3. Retry the OAuth configuration. You should now see a window prompting you to authorize the connection using the service account credentials.

Next step