Copyright ©
Mindbreeze GmbH, A-4020 Linz, 2020.
All rights reserved. All hardware and software names used are brand names and/or trademarks of their respective manufacturers.
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.
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:
Before installing the ServiceNow connector, make sure that the Mindbreeze server is installed and the ServiceNow connector is included in the license.
To enable Mindbreeze InSpire to connect to your ServiceNow instance, you first need to configure your ServiceNow instance.
Enable OAuth2 in your ServiceNow instance and create a new OAuth2 application. See the ServiceNow documentation: Enable OAuth with inbound REST
To begin configuration, open the Mindbreeze Management Center in your browser.
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.
Now you can configure the data source.
Legend:
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 |
Page Size | The page size of the REST API bulk requests (default 1000) |
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:
|
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. |
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:
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:
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:
|
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: |
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:
Instance URL* | The URL for 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 |
Page Size | The page size of the REST API bulk requests (default 1000) |
Resolve ACLs | Roles of the ServiceNow ACLs are resolved. 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 use the “Use Access Control Lists” option in the crawler. |
Resolve User Criteria | User criteria users, groups, roles, companies, locations, and departments are resolved. The “Script” field is not supported. Use this option if you use the “Use User Criteria” option in the crawler. |
Dump User Criteria to CSV | If enabled, all user criteria are written to the CSV file “user-criteria-dump.csv” in the current log directory. |
If you would like to have more control over the permissions of the crawler user, you can define separate roles so that the crawler user has read access to the appropriate tables through the REST API. The crawler user must have read access to the following tables:
You can use filters to ensure that the crawler only indexes specific records. To do this, open any table in ServiceNow that you want to filter and apply the filter. Right-click on the filter expression and then click on the “Copy query” entry in the context menu. The filter expression copied from the screenshot below will look like this: active=true^article_type=text. You can define this expression in the configuration of the data source in the Mindbreeze Management Center; for example, under “Constraint Query for Knowledge Articles” or “Generic Tables.” Insert “Constraint Query.”