Setting up the SharePoint Online Search Connector

Set up the SharePoint Online Search Connector by configuring and connecting the Microsoft SharePoint tenant with your instance. Validate the connection to avoid any setup failures before indexing the sites for search.

Configure the Microsoft SharePoint tenant

Configure your Microsoft SharePoint tenant to get started with the SharePoint Online Search Connector.

Before you begin

As a Microsoft SharePoint administrator, create a custom application by specifying the root URL (https:// <sitename>.sharepoint.com), app domain, redirect URL, and other settings.
Important:
Starting with the Yokohama release, SharePoint Online Search Connector is being prepared for future deprecation. It’s hidden and no longer activated on new instances but continue to be supported.

For deprecation details, see the Deprecation Process [KB0867184] article in the Now Support knowledge base.

Ensure you complete the following prerequisites.

Role required: admin

About this task

Complete the following procedure from your Microsoft SharePoint account. For more information on creating and configuring custom applications, see the SharePoint development
Note:
When the permissions assigned in the Azure apps have privilege issues, the following error message appears: Error message: Method failed: (/_api/web/XXXXXXX) with code: 401 - Invalid username/password combo. Address this issue with the instructions available in KB1117977.
When you want the search results to display only the published versions of the documents, ensure you select Application permissions instead of the Delegated permissions while configuring the permissions explained in Microsoft SharePoint Online Spoke.
Note:
Admins can limit indexing to the published versions only, ensuring that drafts or unfinished work aren’t displayed in the search results.​

Procedure

  1. Navigate to Azure > Active Directory > App registrations > All applications, and select an existing app.
    Use an existing application or create an application.
Configured permissions
  1. Navigate to App registrations > API permissions, and click Add a permission.
  2. Select one of the following options:
    1. Navigate to Microsoft Graph > Delegated permissions for Graph.
    2. Navigate to Microsoft Graph > Application permissions for Graph.
    Add the Sites.ReadWrite.All permission from the Sites list. The Sites.ReadWrite.All permission helps with subscription creation.

    Add the User.Read permission from the Users list.

    These user permissions are used to crawl the Microsoft SharePoint data later.
  3. Navigate to Sharepoint > Application permissions > Sites, and select Sites.FullControl.All, Sites.Read.All, or Sites.Selected for REST.
    Enable the Sites.Selected permission by performing the following steps.
    1. In the Microsoft Azure application, enable the Sites.Selected and the User.Read.All permissions.
      Use any API client to provide read access for the following site collections.
      • Application X that is connected to a ServiceNow instance and has the Sites.Selected permission.
      • Application Y that is an admin application and has the Sites.Full.Control permission for Graph connection.
    2. Get a bearer token by calling the API method https://login.microsoftonline.com/{Tenant Id}/oauth2/v2.0/token.
      Payload:
      client_id={App Y client id}
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_secret={App Y client secret}
&grant_type=client_credentials
    3. Pass the token received in step b as the authorization token while calling the API method https://graph.microsoft.com/v1.0/sites/{site id}/permissions.
      Payload:
      {
"roles": [
"read"
],
"grantedToIdentities": [
{
"application": {
"id": "App X client id",
"displayName": "App X"
}
}
]
}
  4. Ensure you configure the required API permissions as shown in the following image:
    Figure 1. Configured permissions list
    SharePoint configured permission list
    For more information, see Configure Microsoft SharePoint Graph connection.
  5. Click Grant admin consent, select Yes, and click Save and Continue.
  6. Navigate to Authentication > Web > Redirect URLs and add the URL in this format https://<your Servicenow instance URL>/oauth_redirect.do, for example, https://eesharepoint.example.com/oauth_redirect.do and click Save.
  7. Navigate to Microsoft SharePoint Online Spoke and register the certificate and secret for your application.
  8. Click Add user on the Microsoft admin portal, specify the user details, and click Finish.
    Note:
    The search crawls the sites that you can access. Ensure that you select the user with appropriate permissions for only the required content. For more information, see user permissions. Selecting a high-level user can import more documents than you want to import.

    For more information, see Granting access via Azure AD App-Only.

What to do next

Complete the integration from your ServiceNow AI Search account. For more information, see Integrate the Microsoft SharePoint search sources with the AI Search profiles.

Connect your ServiceNow instance to a Microsoft SharePoint tenant

Connect your ServiceNow instance with a Microsoft SharePoint tenant. Create custom ServiceNow OAuth connections for Microsoft SharePoint to authenticate ServiceNow requests.

Before you begin

  • Ensure that you have working knowledge of the SharePoint developer program tools and other resources to configure the application.
  • Ensure that you’re aware of the ServiceNow® integrations.
Role required: sn_sp_con.admin and admin.

Procedure

  1. Navigate to ServiceNow instance > System OAuth > Application Registry.
  2. Click New.
    The system displays the message What kind of OAuth application?
  3. Select Connect to a third-party OAuth Provider.
  4. Create the following registries:
    1. On the Graph connection form, fill in the fields.
      For a description of the field value, see Graph connection form.
    2. On the REST connection form, fill in the fields.
      For a description of the field value, see REST connection form.
    3. Right-click the form header and click Save.
OAuth Entity Profile
  1. Navigate to the OAuth Entity Profiles [oauth_entity_profile] table to find the following entries:
    • <Graph application registry name>.default_profile
    • <REST application registry name>.default_profile

    Two system-generated OAuth entity profiles (REST and Graph) are created in the OAuth Entity Profiles [oauth_entity_profile] table. For more information, see Specify an OAuth profile

OAuth Entity Scopes
  1. Insert a row with the following values in the OAuth Entity Scopes [oauth_entity_scope] table:
    Table 1. OAuth Entity Scopes
    Graph REST
    Name: Any name of your choice Name: Any name of your choice
    OAuth Provider: Graph Application Registry record OAuth Provider: REST Application Registry record
    Application: Global Application: Global
    (For Delegated permissions) OAuthscope: offline_access https://graph.microsoft.com/Sites.ReadWrite.All

    (For Application permissions) OAuthscope: https://graph.microsoft.com/.default

    		OAuth Scope:https://<instance name>.sharepoint.com/
    For more information, see Specify an OAuth scope.
OAuth Entity Profiles Scopes
  1. Insert a row with the following values in the OAuth Entity Profiles Scopes [oauth_entity_profile_scope] table:
    Table 2. OAuth Entity Profiles Scopes
    Graph REST
    OAuth Entity Profile: Graph entity profile generated in the OAuth Entity Profiles [oauth_entity_profile] table. OAuth Entity Profile: REST entity profile generated in the OAuth Entity Profiles [oauth_entity_profile] table.
    OAuth Entity Scope: Select the graph OAuth Entity Scope [oauth_entity_profile_scope] table. OAuth Entity Scope: Select the REST OAuth Entity Scope [oauth_entity_profile_scope] table.
    Application: Global Application: Global
Credentials
  1. Navigate to Connections & Credentials > Credentials, and create the OAuth 2.0 credentials:
    1. On the Graph or REST credential forms, fill in the fields.
      Table 3. OAuth 2.0 credential form
      Field Description
      Name Name of your choice.
      OAuth entity profile (For Graph) Graph entity profile identified.

      (For REST) REST entity profile identified.
    2. Right-click the form header and click Save.
      Note:
      For more information on Entities, Connection & Credential Aliases, see Configure the SharePoint Graph Root Site Subscription connection and credential alias record.
Connection
  1. Navigate to Connections & Credentials > Connection, and click New to create HTTP(s) connections for the following Graph or REST.
    1. On the form, fill in the fields.
      Table 4. Connection form
      Field Description
      Name: Any name of your choice for Graph Name: Any name of your choice for REST
      Credentials: Select the graph Credentials Credentials: Select the REST Credentials
      Connection alias: sn_sp_spoke.MicrosoftSharePointGraph Connection alias: sn_sp_spoke.MicrosoftSharepointOnline
      Connection URL: https://graph.microsoft.com/v1.0/ Connection URL: https://<Host URL of your SharePoint instance>/
      Domain: Global Domain: Global
    2. Right-click the form header and click Save.
    For more information, see Connections and Credentials and Create an HTTP(s) connection.
Tenants
  1. Navigate to Microsoft Sharepoint Online > Tenants.
    1. Click New to create Graph or REST connections.
    2. On the form, fill in the fields.
      Table 5. Tenant connection form
      Field Description
      Name Name of your choice.
      Alias For Graph: sn_sp_spoke.MicrosoftSharePointGraph

      For REST: sn_sp_spoke.MicrosoftSharepointOnline
      SharePoint root URL Root URL as <SiteName>.sharepoint.com
      Tenant ID Tenant ID required for the Graph or REST connection.
      Domain Global
    3. Right-click the topic header and click Save.
    For more information, see Define tenants, Configure the SharePoint Graph Root Site Subscription connection and credential alias record, and Create aliases for multiple tenants
Certificates
  1. Navigate to System definition > Certificates > Microsoft SharePoint Online Certificate.
    1. Attach the file generated Java Key Store certificate on the Azure AD portal.
      For more information, see Attach a Java Key Store certificate.
    2. Update the Key store password with the password of the Java Key Store (.jks) file.
    3. Update the type to the Java key store.
    4. Right-click the topic header and click Save.
    For more information, see Configure the SharePoint Graph Root Site Subscription connection and credential alias record.
JWT keys
  1. Navigate to System OAuth > JWT keys > Microsoft SharePoint Online JWT Keys.
    1. Update signing key with password of Certificate (.cer) file.
    2. Right-click the topic header and click Save.
  2. Navigate to System OAuth > JWT providers > Microsoft SharePoint Online JWT Provider.
    1. Update the aud claim with https://login.microsoftonline.com/<Tenant-id>/oauth2/token.
    2. Update the iss and sub claim with the respective client ids on the Azure ad app registrations.
    3. Click Save.
Connection
  1. Navigate to Connections & Credentials > Connection.
    1. Open the REST connection record and on the Attributes tab, specify the Base 64 encoded certificate Thumbprint.
      Note:
      The SharePoint app thumbprint value is hex encoded. Encode the same in the Base64 format in the connection record.
    2. Select the following Credentials option:
      • (For Graph): Navigate to the [Credentials] table (oauth_2_0_credentials), open Graph, and click Get OAuth Token.

        Ensure that you log in to your Microsoft SharePoint instance with the credentials of the user that you created to get the OAuth token for the Graph connection. Store the credentials in the instance.

      • (For REST): Go to the [Credentials] table (oauth_2_0_credentials), open REST, and click Get OAuth Token.

        Ensure that you log in to your Microsoft SharePoint instance with the Tenant administrator credentials to get the OAuth token for the REST connection. Store the credentials in the instance.

        Validate the credential to avoid any configuration failure. For more information on validating the SharePoint connection, see Validate the Microsoft SharePoint connection.

    3. Click Save.
Trusted Domains
  1. Go to Trusted Domains table (sn_ais_spoke_trusted_domains) and click New to create a domain record.
    1. On the form, fill in the fields.
      Table 6. Domain record form
      Field Description
      Name Name of your choice.
      Domain <Host URL of your Microsoft SharePoint tenant>.
    2. Click Save.
      For more information, see Set up the AI Search spoke.
      Note:
      Ensure you create a trusted domain record for each tenant, when there are multiple tenants.
Sharepoint Ingest User
  1. Navigate to Connections & Credentials > Connection & Credential Aliases > Sharepoint Ingest User (sn_sp_con.Sharepoint_Ingest_User).
    1. Click New on Credentials to create a Basic Auth Credential for ingesting external content by AIS.
    2. Specify the User name and Password of the user (sys_user) who has the ais_external_content role.
      ingest user
      Note:
      In the example screenshot, the user abel.tuter is the sys_user who has the ais_external_content role assigned.
    3. Click Submit.
      For more information, see Create aliases for multiple tenants.
    4. Configure the AI Search server connection before you proceed with the next steps.

    The Entity View Action Mapper (EVAM) configuration is available by default with Employee Center Pro version 32.0.

    For more information on EVAM definition, see Create an EVAM action definition and Create a multi-data source list display in Entity View Action Mapper.

Result

Your configuration is complete.

What to do next

Validate the Microsoft SharePoint connection to rule out any configuration failure before indexing a sample site.

Validate the Microsoft SharePoint connection

Run a validation after you connect your ServiceNow instance with a Microsoft SharePoint tenant to check for any errors in the configuration.

Before you begin

Role required: admin

About this task

The validation rules out any configuration failure and ensures a seamless setup process.

Procedure

  1. Navigate to System UI > UI Pages > Sharepoint utility.
  2. Select Try it to navigate to the SharePoint Connection validation page.
  3. Enter the required details and select Validate.
    The errors, if any, are displayed in the Response section.
  4. Check the Table name links and fix the errors based on the Current Value and Expected Value displayed in the Response section.

    If any information is missing, the Error field shows the data.

    If there are no errors, the Response section displays a successful validation.

What to do next

Index sites for search. For more information, see Index sites for search.