ServiceNow Graph Connector

The ServiceNow Graph connector allows your organization to index knowledge-based articles visible to users according to the user criteria permissions within your organization. After you configure the connector and index content from ServiceNow, users can search for the articles from any Microsoft Search client.

Note

Read the Setup for your Graph connector article to understand the general Graph connectors setup process.

This article is for anyone who configures, runs, and monitors a ServiceNow Graph connector. It supplements the general setup process, and shows instructions that apply to only for the ServiceNow Graph connector. This article also includes information about Troubleshooting and Limitations.

Step 1: Add a Graph connector in the Microsoft 365 admin center

Follow the general setup instructions.

Step 2: Name the connection

Follow the general setup instructions.

Step 3: Connection Settings

To connect to your ServiceNow data, use your organization's ServiceNow instance URL credentials for this account, the Client ID, and Client Secret for OAuth authentication.

Your organization’s ServiceNow instance URL typically looks like https://<your-organization-domain>.service-now.com. Along with this URL, you need an account for setting up the connection to ServiceNow and for allowing Microsoft Search to update the articles from ServiceNow based on the refresh schedule. The account should at least have knowledge role. Learn how to assign role for ServiceNow accounts.

Note

If you want to crawl user and group identities to honor access permissions of knowledge articles in Microsoft Search results, the account should have access to read the following table records in ServiceNow:

  • kb_uc_can_contribute_mtom
  • kb_uc_can_read_mtom
  • kb_uc_cannot_read_mtom
  • kb_uc_cannot_contribute_mtom
  • sys_user
  • sys_user_has_role
  • sys_user_grmember
  • user_criteria
  • kb_knowledge_base
    You can create and assign a role for the account you use to connect with Microsoft Search. Read access to the tables can be assigned on that role. To learn about setting read access to table records, see Securing Table Records.

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

  1. Basic authentication
  2. ServiceNow OAuth (recommended)
  3. Azure AD OpenID Connect

Basic authentication

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

ServiceNow OAuth

To use ServiceNow OAuth for authentication, provision an endpoint in your ServiceNow instance. The Microsoft Search app will use it to access the instance. 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. https://gcs.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 (1 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.

Azure AD OpenID Connect

To use Azure AD OpenID Connect for authentication, follow the steps below.

Step 3.a: Register a new application in Azure Active Directory

To learn about registering a new application in Azure Active Directory, 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.

Step 3.b: Create a client secret

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

Step 3.c: 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 3.a. 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 Azure Active Directory 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)

Step 3.d: Register 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. Azure AD
    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 Azure AD
    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.

Step 3.e: Create a ServiceNow account

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

Step 3.f: 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.

Use Application ID as Client ID from step 3.a, and Client secret from step 3.b, to authenticate to your ServiceNow instance using Azure AD OpenID Connect.

Step 4: Select properties and filter data

In this step, you can add or remove available properties from your ServiceNow data source. Microsoft 365 has already selected few properties by default.

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.

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

Step 5: Manage search permissions

The ServiceNow connector supports search permissions visible to Everyone or Only people with access to this data source. Indexed data appears in the search results and is visible to users in the organization who have access to them respectively. ServiceNow Connector supports default user criteria permissions without advanced scripts. When the connector finds a user criteria with advanced script, all data using that user criteria won't be shown in search results.

If you select Only people with access to this data source, you need to further choose whether your ServiceNow instance has Azure Active Directory (AAD) provisioned users or Non-AAD users.

Note

The ServiceNow connector is in preview if you choose Only people with access to this data source.

Note

If you choose AAD as the type of identity source, make sure you are assigning UPN source property to email targeted property in ServiceNow. To verify or change your mappings, see Customizing user provisioning attribute-mappings for SaaS applications in Azure Active Directory.

If you chose to ingest an ACL from your ServiceNow instance and selected "non-AAD" for the identity type, see Map your non-Azure AD Identities for instructions on mapping the identities.

Step 6: Assign property labels

Follow the general setup instructions.

Step 7: Manage schema

Follow the general setup instructions.

Step 8: Choose refresh settings

Follow the general setup instructions.

Note

For identities, only full crawl scheduled will be applied.

Step 9: Review Connection

Follow the general setup instructions.

Troubleshooting

After publishing your connection, customizing the results page, you can review the status under the Connectors tab in the admin center. To learn how to make updates and deletions, see Manage your connector.

Limitations

ServiceNow Graph connector has the following limitations in its latest release:

  • Indexing knowledge articles available to everyone in an organization is a generally available feature.
  • Only people with access to this data source feature under Manage Search permissions step is in preview and processes only user criteria permissions. Any other type of access permissions won't be applied in the search results.
  • User criteria with advanced scripts aren't supported in the current preview version. Knowledge articles with an access restriction will be indexed with deny everyone access, and won't appear in search results to any user until we support them.