ServiceNow Connector

Installation and Configuration

Mindbreeze GmbH, A-4020 Linz, 2021.

These documents are strictly confidential. The submission and presentation of these documents does not confer any rights to our software, our services and service outcomes, or any other protected rights. The dissemination, publication, or reproduction hereof is prohibited.

For ease of readability, gender differentiation has been waived. Corresponding terms and definitions apply within the meaning and intent of the principle of equal treatment for both sexes.

Introduction

Using the ServiceNow connector, you can connect your ServiceNow instance to Mindbreeze InSpire.

Please be aware that certain types of ServiceNow authorizations are not displayed in the connector, which may prevent the documents concerned from being found by the Mindbreeze InSpire search. The following authorization types are not supported:

“User Criteria”
- if “Match All” is set
- if “Advanced” is set (“Script”, except if the User Criteria was generated by an "HR Criteria”)
“Access Control Lists” (ACLs)
- ACLs that are defined at the column level (e.g. [incident].[active]); however, table-level ACLs are supported (e.g. [incident].[-- None --])
- ACLs with “Condition” or “Script” (however, “Requires role” is supported)

Installation

Before installing the ServiceNow connector, make sure that the Mindbreeze server is installed and the ServiceNow connector is included in the license.

Configuring ServiceNow

To enable Mindbreeze InSpire to connect to your ServiceNow instance, you first need to configure your ServiceNow instance.

Creating a crawler user

Create a new user in ServiceNow that can be used in the Mindbreeze ServiceNow connector to crawl ServiceNow (see ServiceNow document: Create a user). For this, the user must have the following roles:
rest_api_explorer
web_service_admin
The user must also have read access to the necessary tables. This can be achieved in two different ways:
Either the crawler user is assigned the role of “admin” and also the role “snc_read_only,” so that only read-only access is granted for all the tables that are already authorized (recommended option) or
Permissions are set for tables at a granular level (see appendix: Granular crawler permissions)

Creating an OAuth2 client

Enable OAuth2 in your ServiceNow instance and create a new OAuth2 application. See the ServiceNow documentation: Enable OAuth with inbound REST

Configuring Mindbreeze

To begin configuration, open the Mindbreeze Management Center in your browser.

Configuring the index

Add a new index in the Indices tab with the +Add Index button. Select the desired Index Node and Client Service and enter the data source ServiceNow in the Data Source field. Afterwards, confirm your entries by clicking the Apply button.

Configuring the data source

Now you can configure the data source.

Legend:

Properties marked with an *: required fields – these must be explicitly configured
Properties not specifically marked: optional fields

Connection settings

Instance URL*	The URL of the ServiceNow instance; for example, https://mycompany.service-now.com/
Token URL*	The token endpoint URL; for example, https://mycompany.service-now.com/oauth_token.do
Grant Type*	The grant type for retrieving the OAuth2 token (usually “password”)
Client ID*	The client ID of the OAuth2 application that is configured in ServiceNow
Client Secret*	The client secret of the OAuth2 application that is configured in ServiceNow
Username*	The crawler user’s username
Password*	The crawler user’s password

Download settings

Page Size

The page size of the REST API bulk requests (default 1000)

Document types (tables)

Index <<TABLE_NAME>>

When enabled, the table is indexed (for example, if “Index Knowledge Articles” is enabled, knowledge articles are crawled)

Constraint Query for <<TABLE_NAME>>

A constraint query to restrict which records in a table are indexed (using the ServiceNow filter; see appendix: Constraint queries)

Generic Tables

If you want to index tables other than knowledge articles, catalog items, incidents, or problems, you can configure that here:

Table Name*	The name of the table
Constraint Query	Limits the records to be indexed using the ServiceNow filter; see appendix: Constraint queries.
Fields	A list of the table columns to be indexed (separated by a line break). If the list has no entries, all columns are indexed
Title Column*	The column name to be used as the title
Content Column	The column name to be used as document content
Content Extension	The file extension (such as txt or html). Only relevant if Content Column is set

ServiceNow cache settings

Use Access Control Lists

Roles of ServiceNow ACLs are set to Mindbreeze documents. Only ACLs at the table level (no support at the column level) are included. In addition, the “Condition” and “Script” fields are not supported. Use this option if you are using “Resolve ACLs” in the principal resolution service.

Use User Criteria

ServiceNow user criteria are set as Mindbreeze ACLs on knowledge articles and catalog items. The “Script” field is not supported.

Use this option if you use the option “Resolve User Criteria” in the principal resolution service.

KB Article Principals Size Optimization

Reduces the number of principal containers when user criteria are used. This option is active by default and should not normally be disabled. However, if it is to be disabled anyway, then it must also be disabled in CachingServiceNowPrincipalResolutionService for the permissions to work correctly.

If you use the “Use Access Control Lists” option, ACL references must be configured in the index. To do this, enable the “Use ACL References” option in the advanced settings of the index configuration.

In addition, we recommend that you configure the following options to hide documents in the search that are only used as ACL references:

Dynamic Constraint Source Expr: category:Undefined
Dynamic Constraint Pattern: NOT aclReference:true
Dynamic Constraint Static Fraction: NOT aclReference:true

CSV logging

ServiceNow user criteria that are not supported by this plugin are logged in “objects-log.csv” in the current log directory:

Caching principal resolution service: user criteria that cannot be resolved (“Advanced”: “true,” “Match All”: “true”)

The following settings can be configured both in the crawler settings and in the caching principal resolution service settings:

Log Objects to CSV (advanced setting)

If enabled, processed objects are also logged

Log Level (advanced setting)

Three levels:

INFO: Successfully processed objects are also logged.
WARNING, ERROR: Objects that were not successfully processed (unsupported user criteria, see above) are also logged.

This setting is only effective when "Log Objects to CSV" is enabled.

Dump User Criteria to CSV

If enabled, CSV dump files are stored in the current log directory:

catalog-category-dump.csv
catalog-item-dump.csv
knowledge-article-dump.csv
knowledge-base-dump.csv

Crawler settings

Open URL Template*

A template for the URL that is used to open a search result. The placeholders {{instnace_url}}, {{table}} and {{{sys_id}} can be used; for example:
{{instance_url}}/nav_to.do?uri=%2F/{{table}}.do?sys_id={{sys_id}}

Configuring the Caching Principal Resolution Service

Now configure the ServiceNow Caching Principal Resolution service. To do this, click on the “+ Add Service” button in the “Indices” tab under “Services” and select the service “CachingServiceNowPrincipalResolutionService.”

To connect the crawler and the caching principal resolution service, select the added CachingServiceNowPrincipalResolutionService in the “Caching Principal Resolution Service” field in the ServiceNow crawler configuration (data source).

The following tables explain the settings that you can configure for the caching principal resolution service.

Legend:

Properties marked with an *: required fields – these must be explicitly configured
Properties not specifically marked: optional fields