Share via


ServiceNow Knowledge Microsoft 365 Copilot connector

With the ServiceNow Knowledge Microsoft 365 Copilot connector, your organization can index knowledge-base articles that are visible to all users or restricted with user criteria permissions within your organization. After you configure the connector and index content from ServiceNow, end users can search for those articles in Microsoft Copilot and from any Microsoft Search client.

This article is for Microsoft 365 administrators or anyone who configures, runs, and monitors a ServiceNow Knowledge Copilot connector.

Capabilities

  • Index all types of knowledge articles
  • Enable your end users to ask questions related to your IT/HR workflows in Copilot.
    • How to request a new device?
    • How to create a new VPN connection?
    • How do I apply for leaves?
  • Use Semantic search in Copilot to enable users to find relevant content based on keywords, personal preferences, and social connections.
  • Support for Advanced user criteria permissions.
  • Customize the ServiceNow Knowledge URL in Copilot responses as set in your organization

Limitations

  • If both knowledge base and knowledge article-level permissions are defined, only the article-level permissions are honored. Knowledge base-level permissions are disregarded and therefore don't apply to the articles.
  • Doesn't index attachments & comments.
  • Doesn't support reading content from out-of-the-box or custom knowledge article templates, such as FAQs, How-to, What Is, or KCS article templates.

Prerequisites

  • ServiceNow Instance URL: To connect to your ServiceNow data, you need your organization's ServiceNow instance URL. Your organization's ServiceNow instance URL typically looks like https://your-organization-name.service-now.com. (Don’t have one? Check how to create a test instance)

  • Service Account: To connect to ServiceNow and allow the ServiceNow Knowledge Copilot connector to update knowledge articles regularly, you need a service account with read access to specific ServiceNow table records. The service account needs read access to the following ServiceNow table records to successfully crawl various entities.

    Feature Read access required tables Description
    Index knowledge articles available to Everyone kb_knowledge For crawling knowledge articles
    Index and support user criteria permissions kb_uc_can_read_mtom Who can read this knowledge base
    kb_uc_can_contribute_mtom Who can contribute to this knowledge base
    kb_uc_cannot_read_mtom Who can't read this knowledge base
    kb_uc_cannot_contribute_mtom Who can't contribute to this knowledge base
    sys_user Read user table
    sys_user_has_role Read role information of users
    sys_user_grmember Read group membership of users
    user_criteria Read user criteria permissions
    kb_knowledge_base Read knowledge base information
    sys_user_group Read user group segments
    sys_user_role Read user roles
    cmn_location Read location information
    cmn_department Read department information
    core_company Read company attributes
    Index extended table properties (optional) sys_db_object Read extended table details
    sys_dictionary Read extended table properties
    sys_properties Read properties to evaluate permissions

    You can create and assign a role for the service account you use to connect with Microsoft Search. Learn how to assign role for ServiceNow accounts. Read access to the tables can be assigned on the created role. To learn about setting read access to table records, see Securing Table Records.

    If you want to index properties from extended tables of kb_knowledge, provide read access to sys_dictionary and sys_db_object. Access to these tables is optional. You can index kb_knowledge table properties without access to the two additional tables.

  • Scripted REST API: If your ServiceNow instance uses Advanced Scripts in your Knowledge Base or Article-level user criteria, you'll need to use the Advanced flow. You will also need to create a Scripted REST API Endpoint. For more details, see Use Advanced Flow for the ServiceNow Knowledge Copilot connector.

Get started

This video provides a step-by-step guide on adding the ServiceNow Knowledge Copilot connector.

1. Display name

A display name is used to identify each reference in Copilot, helping users easily recognize the associated file or item. Display name also signifies trusted content. Display name is also used as a content source filter. A default value is present for this field, but you can customize it to a name that users in your organization recognize.

2. Select Simple or Advanced based on your user criteria setup

The Copilot connector for ServiceNow Knowledge supports two flows for user criteria permissions: Simple and Advanced. The default is Simple. If your ServiceNow instance uses Advanced Scripts in your Knowledge Base or Article-level user criteria, you'll need to use the Advanced flow. This ensures accurate permissions handling when ingesting content into Microsoft Graph.

3. ServiceNow URL

To connect to your ServiceNow data, you need your organization's ServiceNow instance URL. Your organization's ServiceNow instance URL typically looks like https://your-organization-name.service-now.com.

4. Authentication type

To authenticate and sync content from ServiceNow, choose one of three supported methods:

  1. Basic authentication

    Enter the username and password of ServiceNow account with knowledge role to authenticate to your instance.

  2. ServiceNow OAuth (recommended)


    [Click to expand] To use the ServiceNow OAuth for authentication, follow these steps.

    A ServiceNow admin needs to provision an endpoint in your ServiceNow instance, so that the ServiceNow Knowledge Copilot connector can access it. To learn more, see Create an endpoint for clients to access the instance in the ServiceNow documentation.

    The following table provides guidance on how to fill out the endpoint creation form:

    Field Description Recommended value
    Name Unique value that identifies the application that you require OAuth access for. Microsoft Search
    Client ID A read-only, auto-generated unique ID for the application. The instance uses the client ID when it requests an access token. NA
    Client secret With this shared secret string, the ServiceNow instance and Microsoft Search authorize communications with each other. Follow security best practices by treating the secret as a password.
    Redirect URL A required callback URL that the authorization server redirects to. For M365 Enterprise: https://gcs.office.com/v1.0/admin/oauth/callback,
    For M365 Government: https://gcsgcc.office.com/v1.0/admin/oauth/callback
    Logo URL A URL that contains the image for the application logo. NA
    Active Select the check box to make the application registry active. Set to active
    Refresh token lifespan The number of seconds that a refresh token is valid. By default, refresh tokens expire in 100 days (8,640,000 seconds). 31,536,000 (one year)
    Access token lifespan The number of seconds that an access token is valid. 43,200 (12 hours)

    Enter the client ID and client secret to connect to your instance. After connecting, use a ServiceNow account credential to authenticate permission to crawl. The account should at least have knowledge role. Refer to the table mentioned under the Service account in the Prerequisites section for providing read access to more ServiceNow table records and index user criteria permissions.

  3. Microsoft Entra ID OpenID Connect


    To use Microsoft Entra ID OpenID Connect for authentication, follow the steps below.
    1. Register a new application in Microsoft Entra ID

      To learn about registering a new application in Microsoft Entra ID, see Register an application. Select single tenant organizational directory. Redirect URI isn't needed. After registration, note down the Application (client) ID and Directory (tenant) ID.

    2. Create a client secret

      To learn about creating a client secret, see Creating a client secret. Take a note of client secret.

    3. Retrieve Service Principal Object Identifier

      Follow the steps to retrieve Service Principal Object Identifier

      1. Run PowerShell.

      2. Install Azure PowerShell using the following command.

        Install-Module -Name Az -AllowClobber -Scope CurrentUser
        
      3. Connect to Azure.

        Connect-AzAccount
        
      4. Get Service Principal Object Identifier.

        Get-AzADServicePrincipal -ApplicationId "Application-ID"
        

        Replace "Application-ID" with Application (client) ID (without quotes) of the application you registered in step 1. Note the value of ID object from PowerShell output. It's the Service Principal ID.

        Now you have all the information required from Azure portal. A quick summary of the information is given in the table below.

        Property Description
        Directory ID (Tenant ID) Unique ID of the Microsoft Entra tenant, from step 3.a.
        Application ID (Client ID) Unique ID of the application registered in step 3.a.
        Client Secret The secret key of the application (from step 3.b). Treat it like a password.
        Service Principal ID An identity for the application running as a service. (from step 3.c)
    4. Register the ServiceNow Application

      The ServiceNow instance needs the following configuration:

      1. Register a new OAuth OIDC entity. To learn, see Create an OAuth OIDC provider.

      2. The following table provides guidance on how to fill out OIDC provider registration form:

        Field Description Recommended Value
        Name A unique name that identifies the OAuth OIDC entity. Microsoft Entra ID
        Client ID The client ID of the application registered in the third-party OAuth OIDC server. The instance uses the client ID when requesting an access token. Application (Client) ID from step 3.a
        Client Secret The client secret of the application registered in the third-party OAuth OIDC server. Client Secret from step 3.b

        All other values can be default.

      3. In the OIDC provider registration form, you need to add a new OIDC provider configuration. Select the search icon against OAuth OIDC Provider Configuration field to open the records of OIDC configurations. Select New.

      4. The following table provides guidance on how to fill out OIDC provider configuration form:

        Field Recommended Value
        OIDC Provider Microsoft Entra ID
        OIDC Metadata URL The URL must be in the form https://login.microsoftonline.com/<tenandId">/.well-known/openid-configuration
        Replace "tenantID" with Directory (tenant) ID from step 3.a.
        OIDC Configuration Cache Life Span 120
        Application Global
        User Claim sub
        User Field User ID
        Enable JTI claim verification Disabled
      5. Select Submit and update the OAuth OIDC Entity form.

    5. Create a ServiceNow account.

      Refer to the instructions to create a ServiceNow account, create a user in ServiceNow.

      The following table provides guidance on how to fill out the ServiceNow user account registration

      Field Recommended Value
      User ID Service Principal ID from step 3.c
      Web service access only Checked

      All other values can be left to default.

    6. Enable Knowledge role for the ServiceNow account

      Access the ServiceNow account you created with ServiceNow Principal ID as User ID and assign the knowledge role. Instructions to assigning a role to a ServiceNow account can be found here, assign a role to a user. Refer to the table mentioned under Service account in the Prerequisites section for providing read access to more ServiceNow table records and index user criteria permissions.

      Use Application ID as Client ID (from step 3.1), and Client secret (from step 3.2) in admin center configuration wizard to authenticate to your ServiceNow instance using Microsoft Entra ID OpenID Connect.

5. API Namespace (if you are using Advanced flow)

If you're using the Advanced flow, enter the API namespace that you created in your ServiceNow instance. For more details, see Advanced Flow for Microsoft 365 Copilot Connector for ServiceNow Knowledge.

6. Rollout to a limited audience

Deploy this connection to a limited user base if you want to validate it in Copilot and other Search surfaces before expanding the rollout to a broader audience. To know more about limited rollout, click here.

At this point, you're ready to create the connection for ServiceNow Knowledge. You can select the Create button and the ServiceNow Knowledge Copilot connector starts indexing articles from your ServiceNow account.

For other settings, like Access permissions, Data inclusion rules, Schema, and Crawl frequency, we have set defaults based on what works best with ServiceNow data. You can see the default values below:

Users  
Access permissions Only people with access to content in Data source.
Map Identities Data source identities mapped using Microsoft Entra IDs.
Content  
Query String active=true^workflow_state=published
Manage Properties To check default properties and their schema, click here
Sync  
Incremental Crawl Frequency: Every 15 mins
Full Crawl Frequency: Every Day

If you want to edit any of these values, you need to choose the Custom Setup option.

Get started with the ServiceNow Knowledge Copilot connector

Custom setup

Custom setup is for those admins who want to edit the default values for settings listed in the above table. Once you click Custom Setup, you see three more tabs: Users, Content, and Sync.

Users

Access permissions

The ServiceNow Knowledge Copilot connector supports access permissions visible to "Everyone" or "Only people with access to content in the data source". Indexed data appears in results and is visible to all users in the organization or users who have access to it via user criteria permission, respectively. Choose the one that is most appropriate for your organization.

If a knowledge article isn't enabled with a user criterion, it appears in the results for everyone in the organization.

Important

In ServiceNow, while assessing read permissions for a user, both article-level permissions and KB-level permissions are looked at. The ServiceNow Knowledge Copilot connector treats permissions differently:

  1. If the article contains 'Can Read' user criteria, then they are stamped on the article during ingestion and Knowledge Base 'Can Read' / 'Can Contribute' user criteria are ignored.

  2. If the article contains 'Cannot Read' user criteria, and if the corresponding Knowledge base also contains 'Cannot Read' user criteria, then both the user criteria are stamped on the article.

Note

If a user is part of the 'Can Read' user criteria at the article level but not in the 'Can Read' / 'Can Contribute' user criteria at the Knowledge Base level, then the user doesn't have access to the article in ServiceNow but does have access to the article in Microsoft Copilot, Microsoft Search, and other M365 surfaces. The workaround is to remove the user from the 'Can Read' user criteria at the article level.

Mapping identities

The default method for mapping your data source identities with Microsoft Entra ID is by checking whether the email ID of ServiceNow users is the same as the UserPrincipalName (UPN), or Mail of the users in Microsoft Entra ID. If you believe the default mapping wouldn't work for your organization, you can provide a custom mapping formula. To know more about, mapping Non-EntraID identities, click here.

Content

[Content] Query string

With a ServiceNow query string, you can specify conditions for syncing articles. It's like a Where clause in a SQL Select statement. For example, you can choose to index only articles that are published and active. To learn about creating your own query string, see Generate an encoded query string using a filter.

[Content] Manage properties

Here, you can add or remove available properties that you want to index from your ServiceNow data source. Additionally, you can

  • define the schema for the property (define whether a property is searchable, queryable, retrievable, or refinable), Learn more about schema attributes here.
  • change the semantic label, if needed. Know more about semantic labels here.
  • add an alias to the property to enhance search relevance. Learn more about aliases here.
  • customize the URL property value in your desired format. Learn more about it here or refer to the following section for quick steps.

The list of properties that you select here can impact how you can filter, search, and view your results in Microsoft 365 Copilot. By default, Microsoft ServiceNow Knowledge Copilot connector indexes certain properties.


[Select to expand the default indexed properties]
|Property |Semantic Label |Description |Schema Attributes| |---|---|---|---| |AccessUrl| url | The target URL of the item in the data source. | Retrieve | |Active| | A boolean field indicating if the article is currently active and can be viewed or searched by users. | | |ArticleType | | The format of the article, often an HTML or Wiki type. | Query | |Author| Authors | All the people who participated/collaborated on the item in the data source | Query, Refine Retrieve | |CanReadUserCriteria | | Provides the user criteria which defines the audience that has access to view the article. | | |CannotReadUserCriteria | | Provides the user criteria which defines the audience that is explicitly denied access to view the article. | | |CmdbCi | | A reference to a Configuration Item (CI) from the CMDB, linking the article to a specific asset or service. | Query, Retrieve, Search | |Description | | A brief summary of the article's content, which helps users understand what the article is about from search results. | Retrieve, Search | |Direct | | This field's function is not a common and is likely a customization. | | |DisableCommenting | | A boolean field to prevent users from adding comments to the article | | |DisableSuggesting | | A boolean field to prevent users from suggesting changes to the article. Removes 'Flag Article' button from the article | | |DisplayAttachments | | A boolean field that controls whether attachments are displayed on the article's page. | | |EntityType | | The type of entity the article is about (Knowledge) | Query, Refine, Retrieve | |Flagged | | A boolean field that is set to 'true' if a user has flagged the article for review due to an issue with its content. | Query | |GeneratedWithNowAssist | | A flag that indicates if the article was created with the help of ServiceNow's AI assistant. | Query | |HelpfulCount | | The number of times users have marked the article as helpful. | | |IconUrl |IconUrl |Icon URL that represents the article's category or type. | Retrieve | |Image | | A reference to an image used for the article's thumbnail displays next to short description | | |InstrumentationMetadata | | A field that stores technical metadata about the article's creation and usage. | | |ItemPath | | The path of the article within the knowledge base hierarchy. | Query, Refine, Retrieve, Search | |KbCategory | | The category the article belongs to within its knowledge base. | Query, Retrieve, Search | |KbKnowledgeBase | | The knowledge base the article is stored in. | Query, Retrieve, Search | |KbKnowledgeBaseUrl | | A URL linking to the knowledge base | Query, Retrieve | |Meta | | A field to add search keywords (meta tags) to the article to improve search engine results. | | |MetaDescription | | A short description used in search engine results | Retrieve, Search | |Number | | A unique identifier automatically assigned to the knowledge article, such as 'KB0000001' | Query, Retrieve, Search | |PreviewContent | | The content used for a quick preview of the article. | Retrieve | |Published | | A date/time stamp indicating when the article was published and made visible to users. | Query, Retrieve | |Rating | | The average rating given to the article by users. | Query, Retrieve | |ReplacementArticle | | A field that points to a newer, more up-to-date article that has replaced this one. | | |Retired | | A date/time stamp for when the article was retired | | |Roles | | Specifies which user roles can view or search the article. If empty, all users can see | | |ShortDescription | Title | The title of the item that you want to be shown in Copilot and other search experiences | Query, Retrieve, Search| |Source | | The source task from which the article originated, can be another record in ServiceNow (like an incident or problem). | Query | |SysClassName | | Identifies the template for the knowledge. Knowledge for standard templates, Other values can be FAQ, How to, etc. | | |SysCreatedBy | Created by | Name of the person who created the article | Query, Refine, Retrieve| |SysCreatedOn | Created date time |Data and time that the article was created | Query, Refine, Retrieve| |SysDomain | | The domain to which the knowledge article belongs in a multi-domain instance | | |SysDomainPath | | System-generated string that represents the hierarchical path of a knowledge article's domain. | | |SysId | | The unique 32-character ID for the article, used for backend identification. | Query, Retrieve | |SysModCount | | The number of times the article has been modified. | Retrieve | |SysTags | | Keywords or tags that can be added to the article to improve searchability and organization. | Query, Refine, Retrieve, Search | |SysUpdatedBy | Last modified by | Name of the person who most recently edited the article. | Query, Refine, Retrieve| |SysUpdatedOn | Last modified date time | Date and time when the item was last modified | Query, Refine, Retrieve| |SysViewCount | | The number of times the article has been viewed. | Query, Retrieve | |TaxonomyTopic | | A reference to a topic in a defined taxonomy, used for a structured organization. | Query, Retrieve, Search | |Topic | | Another field for article categorization | Query, Retrieve, Search | |UseCount | | The number of times the article has been attached to another record, like an incident or problem. | | |ValidTo | | The expiration date of the article. After this date, article will not be returned in search result | Query, Retrieve | |ViewAsAllowed | | Allow a permitted user to search and view this article as another user | | |WorkflowState| | The current state of the article in its lifecycle, such as 'Draft', 'Review', 'Published', or 'Retired'. | Query, Refine, Retrieve | |Content `Content`| | The main body of the article, where the detailed information is written. | Search |

[Content] Customize URL property

You can customize the URL property (AccessURL) as per your organization's needs. For example, if the URL of the ServiceNow Knowledge articles in your organization is different from the ServiceNow URL, which opens up through the citation links present in responses to your queries in Microsoft Search or Copilot, then you can use this customization capability to configure the value of the AccessURL property in your desired manner.

Note

Currently to use this capability of customizing the schema property, you need to create a new ServiceNow Knowledge connection for your copilot connector. We do not currently support editing an existing connection to make this change in the schema property.

Following are the steps to customize the value of any schema property:

  • During connection setup before you publish your connection, select 'Custom Setup' shown at the top of the window & then successfully 'Authenticate' your instance first.
  • Next before publishing, select 'Content' tab & go down to the 'Manage Properties' section
  • In the table shown under the 'Properties' Column, select the URL property (for example, AccessUrl) which you want to customize
  • In the right-side panel that opens, look for 'Default expression' section
  • Under this section, enter the default expression that you want to set for the property in the 'New default expression' text field box.
    • For any variable components within the expression, reference them by their precise Property Name enclosed within the symbols ${ and }
  • Do remember to select 'Save changes' at the bottom of the side panel once all the details are provided for the changes to be saved & become effective for preview.
  • Once the expression is defined, you can preview the results by selecting 'Preview data' shown at top the 'Content' tab & scrolling right to the property you customized to ensure the expression is correctly captured as set by you.

For example:

Let us assume that in the ServiceNow Knowledge instance for your organization, the URL for a knowledge article is shown as

https://instancedomain.service-now.com/sp?id=kb_article&sys_id=1A2bcd3e45f6ghij17890kl1mn2345678o

So, we need to use the entire URL as it is and just replace the article specific variable component, which is sys_id in this case, with the Exact Property Name (including case match) used to index the sys_id in the connector properties. Look for the table under Manage Properties under Content Tab & search for the property you are looking for (which is SysId in this case). So, here we need to provide the expression as

https://instancedomain.service-now.com/sp?id=kb_article&sys_id=${SysId}


[Select to Expand] Check how to add rules for further customizing the URL based on Knowledge Base

You can additionally bypass the default expression for select knowledge articles by adding rules for defining different default expressions based on property filter like Knowledge Base. Following are the steps to set the rules for defining another default expression for specific items:

  • Repeat steps 1 to 4 as mentioned earlier.

  • Under the section 'Set additional rules to configure expressions', select 'Add new rules'

  • Upon selecting 'Add new rule', a new section opens in the side panel wherein you can

    • Select the 'Filter Property', that is, 'KbKnowledgeBase' for ServiceNow Knowledge
    • Provide the 'Value' for the Filter property using the exact case format as it is in your connection's schema properties. If you want to set the same expression for multiple values of the property, then provide the names of all values separated by comma.
    • Define the 'Expression' that you want to set for items belonging to those filter properties.
  • Once you enter all the details, select 'Save changes' to save your changes & set the rule for the expression

  • You return to the previous side panel & see that the new rule is added in a table shown under the sub section 'Set additional rules to configure expressions'

  • Do remember to again select 'Save changes' at the bottom of the side panel once all the details are provided for the changes to be saved & become effective for preview.

  • If there are more rules to be added, uou can further select 'Add new rule' & follow the same steps to set the new rule.

  • You can also edit or delete an existing rule by selecting the 3 dots (...) that appear on the right-hand side of each row for the rules & then selecting either the 'Edit' or 'Delete' action.

  • Once the expression is defined, you can preview the results by selecting 'Preview Data' shown at top the 'Content' tab & scrolling right to the desired Property to validate the customized expression.

    [Note:]

    • If an item is part of multiple rules defined here, then the rule which was defined first in the order of rules is applied, i.e. From the table, the rule which appears first in the table gets applied.
    • The changes to the URL property, i.e., setting of default expressions, addition of rules or any edit/delete of rule, starts reflecting in the copilot results only after the next scheduled periodic full crawl.

For example:

In ServiceNow Knowledge, if the default URL expression needs to be set differently for articles belonging to "HR" & "IT" knowledge base, then set rule by choosing Filter as "KbKnowledgeBase", defining its values which are separated by comma as "HR, IT", & then defining the expression as per the knowledge article from these knowledge bases, let’s say like this-

https://instancedomain.service-now.com/esc?id=kb_article&sys_id=${SysId}

[Content] Preview data

Use the preview results button to verify the sample values of the selected properties and query filter.

Sync

The refresh interval determines how often your data is synced between the data source and the ServiceNow Knowledge Copilot connector index. There are two types of refresh intervals – full crawl and incremental crawl. For more details, click here.

You can change the default values of the refresh interval from here if you want to.

Read and Deny Access to Knowledge Articles in the ServiceNow Knowledge Copilot connector

[Click to expand] Here is a scenario-wise depiction of how the connector treats access permissions based on user criteria in ServiceNow Knowledge:

Note

Terms used in the table below:

  • No criteria: No user criteria are defined for the article or Knowledge base. (Different from empty criteria where a user criteria is defined but within the criteria all fields are empty)
  • Default user criteria: User criteria defined using ServiceNow fields like Users, Groups, Roles, Location, Department, etc.
  • Empty criteria: A User criteria where all fields have empty values.

How Read access is determined

Knowledge Base   Knowledge Article Access
Can read Can contribute Can read
Any criteria Any criteria Default user criteria Default user criteria followed
Any criteria Any criteria Default + Advanced criteria Default user criteria followed. Advanced criteria ignored.
Any criteria Any criteria Empty criteria + Any criteria Access provided to every ServiceNow user
Default user criteria Default user criteria No criteria Default user criteria followed. [Note: If the 'Cannot Contribute' user criteria is not present, then default criteria from both 'Can read' and 'Can Contribute' are followed. But if the 'Cannot Contribute' user criteria is present, then 'Can Contribute' user criteria is not stamped.]
Default + Advanced criteria Default + Advanced criteria No criteria Default user criteria followed. Advanced criteria ignored.
Empty criteria Any criteria No criteria Access provided to every ServiceNow user

How Deny access is determined

Knowledge Base Knowledge Article Access
Cannot read Cannot read
Default user criteria Default user criteria Both criteria at base and article level are honored.
Advanced criteria Any criteria Deny access to everyone.
Any criteria Advanced criteria Deny access to everyone.
Empty criteria + Default user criteria Any criteria Deny access to everyone.
Any criteria Empty criteria Deny access to everyone.

Troubleshooting

After publishing your connection, you can review the status in the Connectors section of the admin center. To learn how to make updates and deletions, see Manage your connector. You can find troubleshooting steps for commonly seen issues here: Troubleshooting the ServiceNow Knowledge Copilot connector.

If you have issues or want to provide feedback, contact Microsoft Graph | Support.