Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
With the ServiceNow Catalog Microsoft 365 Copilot connector, your organization can list service catalog items 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 catalog items 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 Catalog Copilot connector. It supplements the general instructions provided in the Set up Copilot connectors in the Microsoft 365 admin center article. For more information, see the setup process for the connector.
Capabilities
- Index all types of Catalog items.
- Enable your end users to ask questions related to your IT/HR workflows in Copilot.
- Help me request a new device.
- Help me reset my password.
- Use Semantic search in Copilot to enable users to find relevant content based on keywords, personal preferences, and social connections.
- Support for advanced flow user criteria in catalog items or catalog categories.
Limitations
ServiceNow Catalog Copilot connector has the following limitations in its latest release:
- If both Catalog Category and Catalog item-level user criteria or permissions are defined, only the catalog item-level user criteria are honored. Catalog category-level user criteria are disregarded and therefore do not apply to the items.
- Doesn't index attachments.
- Doesn't support custom widgets.
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. For more information, see Create a test instance. - Service Account: To connect to ServiceNow and allow Copilot connector to update catalog items regularly, you need a service account with read access to specific ServiceNow table records. The service account needs
readaccess to the following ServiceNow table records to successfully crawl various entities.
| Feature | Read access required tables | Description |
|---|---|---|
| Index catalog items available to Everyone | sc_cat_item | For crawling catalog items. |
| Index catalog categories | sc_category | Read Catalog category information. |
| Index and support user criteria permissions | sc_cat_item_user_criteria_mtom | Who can access this catalog item. |
| sc_cat_item_user_criteria_no_mtom | Who cannot access this catalog item. | |
| sc_category_user_criteria_mtom | Who can access this catalog category. | |
| sc_category_user_criteria_no_mtom | Who cannot access this catalog category. | |
| user_criteria | Read user criteria permissions. | |
| Index user related information | sys_user | Read user information. |
| sys_user_has_role | Read role information of users. | |
| sys_user_grmember | Read group membership of users. | |
| sys_user_group | Read user group segments | |
| sys_user_role | Read user roles. | |
| cmn_location | Read user location information. | |
| cmn_department | Read user department information. | |
| core_company | Read user company attributes. | |
| Index extended table properties (optional) | sys_db_object | Read extended table details. |
| sys_dictionary | Read extended table properties. |
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 to the created role. To learn about setting read access to table records, see Granting Table Access to a User in ServiceNow.
If you want to index properties from extended tables of sc_cat_item, provide read access to sys_dictionary and sys_db_object. Access to these tables is optional. You can index sc_cat_item table properties without access to the two additional tables.
- Scripted REST API: If your ServiceNow instance uses Advanced Scripts in your Catalog Category or Catalog item-level user criteria, you need to use the Advanced flow. You also need to create a Scripted REST API Endpoint. For more details, see Use Advanced Flow for the ServiceNow Catalog Copilot connector.
Get started
Add ServiceNow Catalog 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 ServiceNow Knowledge Copilot connector supports two flows for user criteria permissions: Simple and Advanced. The default is Simple.
- If your ServiceNow instance uses Advanced Scripts in your Catalog Category or Catalog-item user criteria, you need to use the Advanced flow. This ensures accurate permissions handling when ingesting content into Microsoft Graph. For more details on how to make changes to your ServiceNow account, see Use Advanced Flow for the ServiceNow Catalog Copilot connector.
- If you select Simple flow, then all the items or categories, where advanced flow user criteria are applied, result in Deny-all access for everyone as those advanced user criteria are not evaluated.
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:
4.1. Basic authentication
Enter the username and password of ServiceNow account with catalog role to authenticate to your instance.
4.2. ServiceNow OAuth
[Click to expand] To use ServiceNow OAuth for authentication, follow these steps.
A ServiceNow admin needs to provision an endpoint in your ServiceNow instance so that the ServiceNow Catalog Copilot connector can access it. To learn more, see [Create an endpoint for clients to access the instance](https://docs.servicenow.com/bundle/xanadu-platform-security/page/administer/security/task/t_CreateEndpointforExternalClients.html) 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 for which you require OAuth access. | 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 catalog 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.
4.3. Microsoft Entra ID OpenID Connect
To use Microsoft Entra ID OpenID Connect for authentication, follow the following steps.
#### 4.3.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 is not needed. After registration, note down the Application (client) ID and Directory (tenant) ID.
4.3.2. Create a client secret
To learn about creating a client secret, see Creating a client secret. Take a note of client secret value.
4.3.3. Retrieve Service Principal Object Identifier
Follow the steps to retrieve the Service Principal Object Identifier.
Run PowerShell.
Install Azure PowerShell using the following command.
Install-Module -Name Az -AllowClobber -Scope CurrentUserConnect to Azure.
Connect-AzAccountGet 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 4.3.1. Note the value of the ID object from the PowerShell output. It's the Service Principal ID.
Now you have all the information required from the Azure portal. A quick summary of the information is given in the following table.
| Property | Description |
|---|---|
| Directory ID (Tenant ID) | Unique ID of the Microsoft Entra tenant, from step 4.3.1. |
| Application ID (Client ID) | Unique ID of the application registered in step 4.3.1. |
| Client Secret | The secret key of the application (from step 4.3.2). Treat it like a password. |
| Service Principal ID | An identity for the application running as a service. (from step 4.3.d) |
4.3.4. Register the ServiceNow Application
The ServiceNow instance needs the following configuration:
Register a new OAuth OIDC entity. To learn, see Create an OAuth OIDC provider.
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 4.3.1 Client Secret The client secret of the application registered in the third-party OAuth OIDC server. Client Secret from step 4.3.2 All other values can be default.
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.
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 4.3.1. |
| OIDC Configuration Cache Life Span | 120 |
| Application | Global |
| User Claim | sub |
| User Field | User ID |
| Enable JTI claim verification | Disabled |
- Select Submit and update the OAuth OIDC Entity form.
4.3.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 4.3.3 |
| Web service access only | Checked |
All other values can be left to default.
4.3.6. Enable the catalog role for the ServiceNow account
Access the ServiceNow account you created with ServiceNow Principal ID as User ID and assign the catalog role. Instructions for assigning a role to a ServiceNow account can be found here, assign a role to a user. Refer to the table at the beginning of Prerequisites for providing read access to more ServiceNow table records and index user criteria permissions.
Use Application ID as Client ID (from step 4.3.1), and Client secret (from step 4.3.2) in admin center configuration assistant to authenticate to your ServiceNow instance using Microsoft Entra ID OpenID Connect.
5. API Namespace (if you are using Advanced flow)
If you are using the Advanced flow, enter the API namespace that you created in your ServiceNow instance. For more details, see Advanced Flow for Microsoft Copilot Connector for ServiceNow Catalog.
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 are ready to create the connection for ServiceNow Catalog. You can select the Create button, and the ServiceNow Catalog Copilot connector starts indexing catalog items 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 in the following table:
| 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 | type!=bundle^sys_class_name!=sc_cat_item_guide^type!=package^active=true |
| Manage Properties | To check default properties and their schema, go to Content > Manage Properties Section |
| 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.
Custom setup
Custom setup is for those admins who want to edit the default values for settings. Once you click Custom Setup, you see three more tabs: Users, Content, and Sync.
Users
[Users] Access Permissions
The ServiceNow Catalog Microsoft Copilot connector supports access permissions visible to "Everyone" or "Only people with access to content in data source". Indexed data appears in results and is visible to all users in the organization or users who have access to them via user criteria permission, respectively. Choose the one that is most appropriate for your organization.
If a catalog item is not 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 catalog item-level user criteria or permissions and catalog category-level user criteria are looked at. The ServiceNow Knowledge Copilot connector treats permissions differently:
If the catalog item contains 'Available For' user criteria, then they are stamped on the catalog item during ingestion and Catalog Category 'Available for' / 'Not Available For' user criteria are ignored.
If the catalog item contains 'Not available for' user criteria, and if the corresponding catalog category also contains some 'Not available for' user criteria, then both the user criteria are stamped on the catalog item.
Note
If a user is part of the 'Available for' user criteria at the catalog item level but not a part of the 'Available for' user criteria at the Catalog category level, then the user doesn't have access to the catalog item in ServiceNow but does have access to the catalog item in Microsoft Copilot, Microsoft Search, and other M365 surfaces. The workaround is to remove the user from the 'Available for' user criteria at the catalog item level.
[Users] Map Identities
Here, you can choose whether your ServiceNow instance has Microsoft Entra ID provisioned users or non-Azure AD users. To identify which option is suitable for your organization:
- Choose the default mapping option of “Microsoft Entra ID” if 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 would not work for your organization, choose the “Non-Azure AD” option if the email ID of ServiceNow users is different from the UserPrincipalName (UPN) of users in Microsoft Entra ID. You can provide a custom mapping formula. Know more about mapping Non-EntraID identities here.
Note
- If you choose Microsoft Entra ID as the type of identity source, the connector maps the email IDs of users obtained from ServiceNow directly to UPN property from Microsoft Entra ID.
- If you chose "Non-Azure AD" for the identity type, see Map your non-Azure AD Identities for instructions on mapping the identities. You can use this option to provide the mapping regular expression from email ID to UPN.
- Updates to users or groups governing access permissions are synchronized only during periodic full crawls. Incremental crawls do not currently support the processing of updates to item permissions or group membership updates.
Content
[Content] Filter using Query string
With a ServiceNow query string, you can specify conditions for syncing catalog items. It is like a Where clause in a SQL Select statement. For example, you can choose to index only items that are 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.
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 Catalog Copilot connector indexes the following properties:
| Source property | Semantic label | Description | Schema |
|---|---|---|---|
| AccessUrl | url |
Target URL of the item in the data source. | Retrieve |
| Authors | Authors |
Name of people who participated/collaborated on the item in the data source. | Query, Retrieve |
| Category | The category within the catalog. | Query | |
Description Content |
Description of the catalog item. | Search | |
| EntityType | Entity type for catalog items | Query, Retrieve | |
| IconUrl | IconUrl |
Icon url that represents the item’s category or type. | Retrieve |
| Name | Title |
Title of the item that you want shown in search and other experiences. | Retrieve, Search |
| ScCatalogs | The specific catalog to which the item belongs. | Query | |
| ShortDescription | A brief summary of the item's purpose. | Retrieve, Search | |
| SysCreatedBy | Created by |
Name of the person who created the item in the data source. | Query, Retrieve |
| SysCreatedOn | Created date time |
Date and time that the item was created in the data source. | Query, Retrieve |
| SysID | Unique identifier for an item. | Retrieve | |
| SysUpdatedBy | Last modified by |
Name of the person who most recently edited the item in the data source. | Query, Retrieve |
| SysUpdatedOn | Last modified date time |
Date and time the item was last modified in the data source. | Query, Retrieve |
[Content] Preview data
Use the preview results button shown at the top of the content page to verify the sample values of the selected properties and query filter.
Sync
Define incremental & full crawl frequencies
The refresh interval determines how often your data is synchronized between the data source and the ServiceNow Catalog Copilot connector index. There are two types of refresh intervals:
- Full crawl: Synchronizes all data at scheduled intervals.
- Incremental crawl: Updates only the changed or new data.
You can change the default values of the refresh interval from here if you want to or just continue with the recommended defaults. Find more details here.
You can see the default values in the following table:
| Refresh intervals | Default frequency |
|---|---|
| Incremental Crawl | Every 15 min |
| Full Periodic Crawl | Every day |
Note
- Identities or access permissions are only updated with full crawl.
- Incremental crawls do not update permissions or ACLs.
Troubleshooting
After publishing your connection, customizing the results page, 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.
If you have any other issues or want to provide feedback, reach out to us at Microsoft Graph | Support