Sure, you can handle it. But should you?
Let our experts manage the tech maintenance while you focus on your business.
Let our experts manage the tech maintenance while you focus on your business.
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)
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, z.B. https://myorganization.service-now.com/. |
Token URL* | Die URL zum Token Endpoint, z.B. https://myorganization.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
Einstellung | Beschreibung |
Page Size | Die Page Size der REST API Bulk Requests (default 1000) |
Document Types (Tables)
Einstellung | Beschreibung | ||||||||||||||
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
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 | 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:
Einstellung | Eingabe |
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:
Einstellung | Beschreibung |
Log Objects to CSV (Advanced Setting) | Wenn aktiv, werden prozessierte Objekte mitprotokolliert. |
Log Level (Advanced Setting) | Drei Optionen stehen zur Auswahl:
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
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.: |
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
Connection Settings
Einstellung | Beschreibung |
Instance URL* | Die URL zur ServiceNow Instanz, z.B. https://myorganization.service-now.com/. |
Token URL* | Die URL zum Token Endpoint, z.B. https://myorganization.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
Einstellung | Beschreibung |
Eine Constraint Query, um einzuschränken, welche User beim Updaten des Caches von ServiceNow abgeholt werden. (mittels ServiceNow Filter, siehe Appendix: Constraint Queries) Mit dieser Option kann der Cache auf relevante User eingeschränkt werden. | |
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. |
Extended User Criteria Conditions, welche aufgelöst werden sollen. Die Conditions können entweder mit dem internen Spaltennamen angegeben werden (z.B. „u_my_condition“) oder mit dem Anzeigenamen (z.b. „My Condition“). Wichtig: Konfigurieren Sie diese Option identisch zu der Option im ServiceNow Crawler. Ansonsten kann die Zugriffsstruktur nicht korrekt abgebildet werden. | |
Resolve Knowledge Article User Criteria | Wenn diese Option aktiviert ist, werden die User Criteria für Knowledge Article aufgelöst. Für bessere Performance oder Berechtigungskontrolle können Sie diese Option deaktivieren, wenn Sie keine Knowledge Articles indizieren. |
Eine Constraint Query, um einzuschränken, welche Knowledge Article User Criteria aufgelöst werden (mittles ServiceNow Filter, siehe Appendix: Constraint Queries) Diese Option sollte identisch zum Crawler konfiguriert sein. | |
Resolve Catalog Item User Criteria | Wenn diese Option aktiviert ist, werden die User Criteria für Catalog Items aufgelöst. Für bessere Performance oder Berechtigungskontrolle können Sie diese Option deaktivieren, wenn Sie keine Catalog Items indizieren. |
Constraint Query for Catalog Items | Eine Constraint Query, um einzuschränken, welche Category Item User Criteria aufgelöst werden (mittles ServiceNow Filter, siehe Appendix: Constraint Queries) Diese Option sollte identisch zum Crawler konfiguriert sein. |
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. |
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 ServiceNow Crawler deaktiviert werden, damit die Berechtigungen korrekt funktionieren. |
Resolve Empty User Criteria to All Users | Wenn diese Option aktiviert ist, werden alle leere User Criteria (User Criteria ohne gesetzte Kriterien) auf alle ServiceNow Benutzer aufgelöst. Das bildet das Verhalten in ServiceNow ab. Sie können diese Option deaktivieren, wenn Sie keine leere User Criterias verwenden. |
Advanced User Criteria Resolution | Siehe nächster Abschnitt. |
Advanced User Criteria Resolution (Advanced Settings)
Sie können hier Regeln konfigurieren, wie welche User Criteria aufgelöst werden, um spezielle Berechtigungen in Mindbreeze InSpire abzubilden. Dies ist vor allem dann sinnvoll, wenn Sie User Criteria verwenden, die von Mindbreeze InSpire standardmäßig nicht unterstützt werden.
Dies betrifft User Criteria, bei denen „Advanced“ gesetzt ist (bzw. „Script“, außer wenn das User Criteria von einem „HR Criteria“ generiert wurde).
Einstellung | Beschreibung | ||||||||||
UC Selection: Column Name | Die User Criteria Spalte / Feld in ServiceNow, auf die das „UC Selection: Column Pattern“ angewandt wird.
| ||||||||||
UC Selection: Column Pattern | Das Pattern, das auf die User Criteria Spalte / Feld („UC Selection: Column Name“) angewandt wird. Das Pattern ist eine Java Regex, bei der „.“ (Punkt) auch auf \n\r matcht (z.B. für Feld script relevant). Achten Sie darauf, dass ein vollständiger Match auf das Feld erfolgen muss, sodass die „Result Action“ für ein übereinstimmendes User Criteria durchgeführt wird. Z.B. würde auf den Feldwert „My User Criteria“
| ||||||||||
Resolution Action | Hier können Sie definieren, wie die User Criteria aufgelöst werden, für die „UC Selection: Column Name / Patter“ übereinstimmen.
|
CSV Logging (Advanced Settings)
Einstellung | Beschreibung |
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. Erstellen Sie eigene ACL Regeln für alle diese Tabellen, da bei manchen Tabellen Default ACL Regeln existieren, welche nur auf bestimme Einträge Zugriff geben, was zu unerwartetem Verhalten führen kann.
Auf folgende Tabellen muss der Crawler User lesend zugreifen dürfen:
- Daten-Tabellen (je nachdem, welche Tabellen Sie indizieren wollen):
- sys_attachment (Alle Felder)
- kb_knowledge (Alle Felder)
- sc_cat_item (Alle Felder)
- incident (Alle Felder)
- problem (Alle Felder)
- … (weitere Tabellen, die Sie crawlen wollen) (sys_id, sys_updated_on, alle Felder die zum Indizieren konfiguriert wurden)
- Metadaten zu Tabellen (Typ-Informationen, die für die Indizierung relevant sind)
- sys_dictionary (Alle Felder)
- sys_db_object (Alle Felder)
- sc_req_item (stage, cat_item)
- Berechtigungen allgemein
- Berechtigungen über ACLs (nur notwendig, wenn Sie ACLs verwenden
- sys_security_acl (sys_id, name, operation, condition, advanced, script, type, active)
- sys_security_acl_role (sys_user_role, sys_security_acl)
- Berechtigungen über User Criteria (nur notwendig, wenn Sie User Criteria verwenden)
- Für Category Items (nur notwendig, wenn Sie Category Items indizieren und auflösen)
- sc_category_user_criteria_mtom (Alle Felder)
- sc_category_user_criteria_no_mtom (Alle Felder)
- sc_cat_item_user_criteria_mtom (Alle Felder)
- sc_cat_item_user_criteria_no_mtom (Alle Felder)
- Für Category Items (nur notwendig, wenn Sie Category Items indizieren und auflösen)
- Für Knowledge Article (nur notwendig, wenn Knowledge Article indiziert und aufgelöst werden)
- user_criteria (Alle Felder)
- sc_category (Alle Felder)
- Berechtigungen über HR Criteria (nur notwendig, wenn Sie HR Criteria verwenden)
- Abhängige Tabellen (Tabellen, auf die nicht direkt zugegriffen wird, sondern die Beziehungen auf andere Tabellen haben, welche für die Indizierung verwendet werden)
- sc_cat_item_delivery_plan (Table Access, wird gebraucht für sc_cat_item)
- sys_scope (Table Access, wird für alle Tabellen gebraucht)
- topic (Table Access, wird gebraucht für sc_cat_item)
- core_company (Table Access, wird gebraucht für incident, sys_user)
- cmdb_ci (Table Access, wird gebraucht für incident, problem)
- cmdb_ci_service (Table Access, wird gebraucht für incident)
- sys_glide_object (Table Access, wird gebraucht für sys_dictionary)
- cmn_location (Table Access, wird gebraucht für sys_user)
- cmn_department (Table Access, wird gebraucht für sys_user)
- sys_security_type (Table Access, wird gebraucht für sys_security_acl)
- sys_security_operation (Table Access, wird gebraucht für sys_security_acl)
- sc_homepage_renderer (Table Access, wird gebraucht für sc_category)
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.
