ServiceNow Connector
Installation und Konfiguration

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).
- ACLs vom Typ „Deny Unless“ (um den unbefugten Zugriff auf Dokumente zu verhindern, führen ACLs mit dem Entscheidungstyp „Deny Unless“ zu einer ACL vom Typ „DENY everyone“ für die Tabelle und ihre Dokumente).

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

Einstellung

Beschreibung

Instance URL*

Die URL zur ServiceNow Instanz.

Beispiel:

https://myorganization.service-now.com/

ServiceNow Credential*

Das Credential, das im „Network“ Tab vorher erstellt wurde.

Das Credential muss als OAuth 2 Credential und mit den folgenden Einstellungen erstellt werden:

Einstellung	Eingabe
Access Token URL	https://myorganization.service-now.com/oauth_token.do
Client ID	Die Client ID der OAuth2 Application, die in ServiceNow konfiguriert ist.
Username	Der Username des Crawler Users.
Password	Das Passwort des Crawler Users.
Client Secret	Das Client Secret der OAuth2 Application, die in ServiceNow konfiguriert ist.

[Deprecated] Token URL

Diese Einstellung ist veraltet und sollte leer bleiben. Verwenden Sie stattdessen die Einstellung „ServiceNow Credential“.

[Deprecated] Client Id*

Diese Einstellung ist veraltet und sollte leer bleiben. Verwenden Sie stattdessen die Einstellung „ServiceNow Credential“.

[Deprecated] Client Secret*

Diese Einstellung ist veraltet und sollte leer bleiben. Verwenden Sie stattdessen die Einstellung „ServiceNow Credential“.

[Deprecated] Username*

Diese Einstellung ist veraltet und sollte leer bleiben. Verwenden Sie stattdessen die Einstellung „ServiceNow Credential“.

[Deprecated] Password*

Diese Einstellung ist veraltet und sollte leer bleiben. Verwenden Sie stattdessen die Einstellung „ServiceNow Credential“.

Download Settings

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

Document Types (Tables)

Einstellung	Beschreibung
Index Knowledge Articles	Wenn aktiv, wird die Tabelle indiziert (z.B. wenn „Index Knowledge Articles“ aktiv ist, werden Knowledge Articles gecrawlt). Standardeinstellung: Aktiviert
Constraint Query for Knowledge Articles	Schränkt den Crawler ein, um nur bestimmte Knowledge Articles zu indizieren. Für mehr Informationen, siehe das Kapitel Constraint Queries.
Index Catalog Items	Wenn aktiv, wird die Tabelle indiziert (z.B. wenn „Index Catalog Items“ aktiv ist, werden Catalog Items gecrawlt). Standardeinstellung: Aktiviert
Constraint Query for Catalog Items	Schränkt den Crawler ein, um nur bestimmte Catalog Items zu indizieren. Für mehr Informationen, siehe das Kapitel Constraint Queries.
Index Incidents	Wenn aktiv, wird die Tabelle indiziert (z.B. wenn „Index Incidents“ aktiv ist, werden Incidents gecrawlt). Standardeinstellung: Aktiviert
Constraint Query for Incidents	Schränkt den Crawler ein, um nur bestimmte Incidents zu indizieren. Für mehr Informationen, siehe das Kapitel Constraint Queries.
Index Problems	Wenn aktiv, wird die Tabelle indiziert (z.B. wenn „Index Problems“ aktiv ist, werden Problems gecrawlt). Standardeinstellung: Aktiviert
Constraint Query for Problems	Schränkt den Crawler ein, um nur bestimmte Problems zu indizieren. Für mehr Informationen, siehe das Kapitel Constraint Queries.
Generic Tables Definiert Tabellen für die Indizierung, die keine Knowledge Article, Catalog Items, Incidents oder Problems sind.
Table Name*	Der Tabellenname.
Constraint Query	Einschränkung der zu indizierenden Records mittels Service Now Filter. Für mehr Informationen, siehe das Kapitel 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

Einstellung	Beschreibung
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 (Advanced Setting)	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.
Enable Default ACLs (Advanced Setting)	Werden für ein Dokument keine ACLs abgerufen, werden die ACL Principals angewandt, die in der folgenden Einstellung „Default ACL Principals“ definiert sind.
Default ACL Principals (Advanced Setting)	Definiert eine Liste von Principals, die angewendet werden, wenn die vorherige Einstellung „Enable Default ACLs“ aktiviert ist. Pro Zeile kann ein Principal definiert werden. Standardeinstellung: „everyone“

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:

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

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:

Einstellung	Beschreibung
Log Objects to CSV (Advanced Setting)	Wenn aktiv, werden prozessierte Objekte mitprotokolliert.
Log Level (Advanced Setting)	Drei Optionen stehen zur Auswahl: 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

Einstellung	Beschreibung
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

Wählen Sie im neuen oder bestehenden Service in der Einstellung „Service“ die Option CachingServiceNowPrincipalResolutionService aus. Für mehr Informationen über weitere Konfigurationsoptionen und über das Erstellen und das grundlegende Konfigurieren eines Cache für einen Principal Resolution Service, siehe Installation & Konfiguration - Caching Principal Resolution Service.

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