ServiceNow Connector

Installation und Konfiguration

Mindbreeze GmbH, A-4020 Linz, 2023.

Diese Unterlagen sind streng vertraulich. Durch die Übermittlung und Präsentation dieser Unterlagen alleine werden keine Rechte an unserer Software, an unseren Dienstleistungen und Dienstleistungsresultaten oder sonstigen geschützten Rechten begründet. Die Weitergabe, Veröffentlichung oder Vervielfältigung ist nicht gestattet.

Aus Gründen der einfacheren Lesbarkeit wird auf die geschlechtsspezifische Differenzierung, z.B. Benutzer/-innen, verzichtet. Entsprechende Begriffe gelten im Sinne der Gleichbehandlung grundsätzlich für beide Geschlechter.

Einleitung

Mithilfe des ServiceNow Connectors können Sie ihre ServiceNow Instanz an Mindbreeze InSpire anbinden.

Bitte beachten Sie, dass gewisse Arten von ServiceNow-Berechtigungen im Connector nicht abgebildet sind und dies dazu führen kann, dass betroffene Dokumente in der Mindbreeze InSpire Suche nicht gefunden werden können. Folgende Berechtigungsarten werden nicht unterstützt:

„User Criteria“
- falls „Advanced“ gesetzt ist (bzw. „Script“, außer wenn das User Criteria von einem „HR Criteria“ generiert wurde)
„Access Control Lists“ („ACLs”)
- ACLs, die auf Spaltenebene definiert sind (z.B. [incident].[active]), unterstützt werden jedoch ACLs auf Tabellenebene (z.B. [incident].[-- None --])
- ACLs mit „Condition“ oder “Script” („Requires role” wird jedoch unterstützt)

Installation

Vor der Installation des ServiceNow Connectors muss sichergestellt werden, dass der Mindbreeze Server installiert und der SerivceNow Connector in der Lizenz inkludiert ist.

Konfiguration von ServiceNow

Damit Mindbreeze InSpire Ihre ServiceNow Instanz anbinden kann, müssen Sie zuerst Konfigurationen in Ihrer ServiceNow Instanz durchführen.

Bereitstellen eine Crawler Users

Legen Sie in ServiceNow einen neuen Benutzer an, der im Mindbreeze ServiceNow Connector zum Crawlen von ServiceNow verwendet werden kann (siehe ServiceNow Dokumentation: Create a user). Der Benutzer muss dabei folgende Rollen haben:

rest_api_explorer
web_service_admin

Zusätzlich muss der Benutzer Lesezugriff auf die benötigten Tabellen haben. Dies kann auf zwei verschiedene Arten realisiert werden:

Der Crawler User erhält die Rolle „admin“ und zusätzlich die Rolle „snc_read_only“, damit auf alle bereits berechtigten Tabellen nur mehr Read-Only Zugriff gewährt wird (empfohlene Variante)
Es werden feingranulare Berechtigungen auf Tabellen gesetzt (siehe Appendix: Feingranulare Crawler Berechtigungen)

OAuth2 Client erstellen

Aktivieren Sie in Ihrer ServiceNow-Instanz OAuth2 und erstellen Sie eine neue OAuth2 Application. Siehe ServiceNow Dokumentation: Enable OAuth with inbound REST

Konfiguration von Mindbreeze

Öffnen Sie das Mindbreeze Management Center im Browser, um mit der Konfiguration beginnen zu können.

Konfiguration des Index

Fügen Sie im Tab Indices mit dem Button +Add Index einen neuen Index hinzu. Wählen Sie den gewünschten Index Node und Client Service aus und geben Sie im Feld Data Source die Datenquelle ServiceNow an. Bestätigen Sie Ihre Eingaben anschließend mit dem Button Apply.

Konfiguration der Datenquelle

Konfigurieren Sie nun die Datenquelle.

Legende:

Mit * markierte Properties: Pflichtfeld, diese müssen explizit konfiguriert werden
Nicht speziell markierte Properties: optionale Felder

Connection Settings

Instance URL*	Die URL zur ServiceNow Instanz, z.B. https://mycompany.service-now.com/
Token URL*	Die URL zum Token Endpoint, z.B. https://mycompany.service-now.com/oauth_token.do
Grant Type*	Der Grant Type zum Abholen des OAuth2 Tokens (normalerweise „password“)
Client Id*	Die Client ID der in ServiceNow konfigurierten OAuth2 Application
Client Secret*	Das Client Secret der in ServiceNow konfigurierten OAuth2 Application
Username*	Der Username des Crawler Users
Password*	Das Passwort des Crawler Users

Download Settings

Page Size

Die Page Size der REST API Bulk Requests (default 1000)

Document Types (Tables)

Index <<TABLE_NAME>>

Wenn aktiv, wird die Tabelle indiziert (z.B. wenn „Index Knowledge Articles“ aktiv ist, werden Knowledge Articles gecrawlt)

Constraint Query for <<TABLE_NAME>>

Eine Constraint Query, um einzuschränken, welche Records einer Tabelle indiziert werden (mittles ServiceNow Filter, siehe Appendix: Constraint Queries)

Generic Tables

Wenn andere Tabellen außer Knowledge Articles, Catalog Items, Incidents oder Problems indiziert werden sollen, kann dies hier konfiguriert werden:

Table Name*	Der Tabellenname
Constraint Query	Einschränkung der zu indizierenden Records mittels Service Now Filter, Siehe Appendix: Constraint Queries
Fields	Eine Liste von Spalten der Tabelle, die indiziert werden sollen (getrennt durch Zeilenumbruch). Wird die Liste leer gelassen, werden alle Spalten indiziert
Title Column*	Der Spaltenname, der als Titel verwendet werden soll
Content Column	Der Spaltenname, der als Dokumentinhalt verwendet werden soll
Content Extension	Die Dateierweiterung (z.B. txt oder html). Nur relevant, wenn Content Column gesetzt ist

ServiceNow Cache Settings

Use Access Control Lists	Rollen von ServiceNow ACLs werden auf Mindbreeze Dokumente gesetzt. Dabei werden nur ACLs auf Tabellen-Ebene (kein Support auf Spalten-Ebene) berücksichtigt. Außerdem werden die Felder „Condition“ und „Script“ in den ServiceNow ACLs nicht berücksichtigt. Verwenden Sie diese Option, wenn Sie im Principal Resolution Service die Option „Resolve ACLs“ verwenden.
Use User Criteria	ServiceNow User Criteria werden als Mindbreeze ACLs auf Knowledge Articles und Catalog Items gesetzt. Das Feld “Script” wird dabei nicht unterstützt. Verwenden Sie diese Option, wenn Sie im Principal Resolution Service die Option „Resolve User Criteria“ verwenden.
Extended User Criteria Conditions	Extended User Criteria Conditions, welche im ServiceNow Caching Principal Resolution Service aufgelöst werden. Wenn es in ServiceNow Extended User Criteria Conditions gibt, die hier nicht angegeben sind, können Dokumente die diese Conditions verwenden, nicht gefunden werden. Da in diesem Fall mehr Requests gegen die ServiceNow API gemacht werden müssen, kann sich dies auch negativ auf die Crawl Geschwindigkeit auswirken. Wichtig: Konfigurieren Sie diese Option identisch zu der Option im ServiceNow Caching Principal Resolution Service. Ansonsten kann die Zugriffsstruktur nicht korrekt abgebildet werden.
KB Article Principals Size Optimization	Reduziert die Anzahl der Principal Containers, wenn User Criteria verwendet werden. Diese Option ist standardmäßig aktiv und sollte normalerweise nicht deaktiviert werden. Wenn Sie jedoch trotzdem deaktiviert werden soll, dann muss sie auch im CachingServiceNowPrincipalResolutionService deaktiviert werden, damit die Berechtigungen korrekt funktionieren.

Wenn Sie die Option „Use Access Control Lists” verwenden, müssen ACL-Referenzen am Index konfiguriert werden. Aktivieren Sie dazu in den Advanced Settings in der Index-Konfiguration die Option „Use ACL References“.

Zusätzlich wird empfohlen, die folgenden Optionen zu konfigurieren, um die Dokumente in der Suche zu verstecken, die nur als ACL-Referenzen verwendet werden:

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

Eine allgemeine Dokumentation zu diesen „Dynamic Constraints“ Einstellungen finden sie hier.

CSV Logging

Von diesem Plugin nicht unterstützte ServiceNow User Criteria werden in „objects-log.csv“ des aktuellen Log-Verzeichnisses mitprotokolliert:

Caching Principal Resolution Service: User Criteria, die nicht aufgelöst werden können („Advanced“: „true“)

Die folgenden Einstellungen können sowohl in den Crawler Settings als auch in den Caching Principal Resolution Service Settings vorgenommen werden:

Log Objects to CSV (advanced setting)

Wenn aktiv, werden prozessierte Objekte mitprotokolliert

Log Level (advanced setting)

3 Levels:

INFO: Auch erfolgreich prozessierte Objekte mitprotokolliert.
WARNING, ERROR: nicht erfolgreich prozessierte Objekte (nicht unterstütze User Criteria, siehe oben) mitprotokolliert.

Diese Einstellung ist nur effektiv, wenn „Log Objects to CSV“ aktiv ist.

Dump User Criteria to CSV

Wenn aktiv, werden CSV Dump Files im aktuellen Log-Verzeichnis abgelegt:

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

Crawler Settings

Open URL Template*

Ein Template für die URL, die zum Öffnen eines Suchresultats verwendet wird. Die Platzhalter {{instnace_url}}, {{table}} und {{sys_id}} können dabei verwendet werden, z.B.:
{{instance_url}}/nav_to.do?uri=%2F/{{table}}.do?sys_id={{sys_id}}

Konfiguration des Caching Principal Resolution Service

Konfigurieren Sie nun den ServiceNow Caching Principal Resolution Service. Klicken Sie dazu im Tab „Indices“ unter „Services“ auf den Button „+ Add Service“ und wählen Sie den Service „CachingServiceNowPrincipalResolutionService“ aus.

Um den Crawler und das Caching Principal Resolution Service zu verbinden, wählen Sie bei der ServiceNow Crawler Konfiguration (Data Source) im Feld „Caching Principal Resolution Service” den hinzugefügten CachingServiceNowPrincipalResolutionService aus.

Die folgenden Tabellen beschreiben die Einstellungen, die Sie beim Caching Principal Resolution Service vornehmen können.

Legende:

Mit * markierte Properties: Pflichtfeld, diese müssen explizit konfiguriert werden
Nicht speziell markierte Properties: optionale Felder