ServiceNow Connector
Installation und Konfiguration
Copyright ©
Mindbreeze GmbH, A-4020 Linz, 2021.
Alle Rechte vorbehalten. Alle verwendeten Hard- und Softwarenamen sind Handelsnamen und/oder Marken der jeweiligen Hersteller.
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 „Match All“ gesetzt ist
- 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)
- „HR Criteria”
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 allen bereits berechtigten Tabellen nur mehr Read-Only Zugriff gewährt wird (empfohlene Variante) oder
- 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:
|
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. |
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
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“, „Match All“: „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:
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:
|
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.: |
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
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) |
ServiceNow Cache Settings
Resolve ACLs | Rollen von ServiceNow ACLs werden aufgelöst. 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 Crawler die Option „Use Access Control Lists“ verwenden. |
Resolve User Criteria | Users, Groups, Roles, Companies, Locations und Departments von User Criteria werden aufgelöst. Das Feld “Script” wird dabei nicht berücksichtigt. Verwenden Sie diese Option, wenn Sie im Crawler die Option „Use User Criteria“ verwenden. |
Resolve HR Criteria | Aktivieren Sie diese Option, wenn Sie zusätzlich zu User Criteria auch HR Criteria verwenden. Diese Option hat keine Auswirkung, wenn Resolve User Criteria deaktiviert ist. |
CSV Logging (Advanced Settings)
Wenn aktiviert, werden Statistiken in der Datei "objects-log.csv" im aktuellen Log-Verzeichnis geschrieben. | |
Log All Objects | Wenn aktiviert, werden auch erfolgreich verarbeitete Objekte in die CSV-Datei geschrieben. Wirkt sich nur aus, wenn Log Objects to CSV aktiv ist. |
Dump User Criteria to CSV | Wenn aktiv, werden alle User Critera in die CSV-Datei „user-criteria-dump.csv“ im aktuellen Log-Verzeichnis geschrieben. |
Dump HR Criteria to CSV | Wenn aktiv, werden alle HR Critera in die CSV-Datei „hr-criteria-dump.csv“ im aktuellen Log-Verzeichnis geschrieben. |
Appendix
Feingranulare Crawler Berechtigungen (optional)
Wenn Sie mehr Kontrolle über die Berechtigungen des Crawler Users haben wollen, können Sie eigene Rollen definieren, damit der Crawler User Lesezugriff über die REST API auf die benötigten Tabellen erhält. Auf folgende Tabellen muss der Crawler User lesend zugreifen dürfen:
- Daten-Tabellen (je nachdem, welche Tabellen Sie indizieren wollen):
- sys_attachment
- kb_knowledge
- sc_cat_item
- incident
- problem
- … (weitere Tabellen, die Sie crawlen wollen)
- Metadaten zu Tabellen (Typ-Informationen, die für die Indizierung relevant sind)
- sys_dictionary
- sys_db_object
- sys_metadata
- Berechtigungen allgemein
- sys_user
- sys_user_grmember
- sys_user_has_role
- Berechtigungen über ACLs (nur notwendig, wenn Sie ACLs verwenden
- sys_security_acl
- sys_security_acl_role
- sc_category
- Berechtigungen über User Criteria (nur notwendig, wenn Sie User Criteria verwenden)
- sc_cat_item_user_criteria_mtom
- sc_cat_item_user_criteria_no_mtom
- kb_uc_can_contribute_mtom
- kb_uc_cannot_contribute_mtom
- kb_uc_can_read_mtom
- kb_uc_cannot_read_mtom
- user_criteria
- Berechtigungen über HR Criteria (nur notwendig, wenn Sie HR Criteria verwenden)
Constraint Queries
Damit der Crawler nur bestimmte Records indiziert, können diese gefiltert werden. Öffnen Sie dazu in ServiceNow eine beliebige Tabelle, die gefiltert werden soll und wenden Sie den Filter an. Klicken Sie mit einem Rechtsklick auf den Filter-Ausdruck und anschließend im Kontextmenü auf den Eintrag „Copy query“. Der kopierte Filter-Ausdruck aus dem Screenshot unterhalb würde folgendermaßen aussehen: active=true^article_type=text. Diesen Ausdruck können Sie in der Konfiguration der Datenquelle im Mindbreeze Management Center z.B. unter „Constraint Query for Knowledge Articles“ oder „Generic Tables“.“Constraint Query“ einfügen.
