Integrationen Such-API
Kurzübersicht
Im Hinblick auf eine größere Flexibilität und die Erweiterung der Unternehmenssuche um neue Funktionen haben wir Integrationen Such-API entwickelt. Die Integrations-API ist der Kanal, um Suchergebnisse von Fremdherstellern in die Workstation Unternehmenssuche aufzunehmen.
Mit der Integrations Search API können Sie Integrationen mit der Unternehmenssuche verbinden, damit Sie Suchfunktionen hinzufügen können, die die Erfahrung auf Workstation steuern.
Dieser Artikel stellt die Workstation - Integrationen Search API vor.
Fremdintegrationen erweitern die WalkMe Workstation um zwei wichtige Funktionen.
- Unternehmenssuche - mit einer einzigen, einheitlichen Suche können Benutzer Anwendungen und Ressourcen finden.
- Widgets für den Startbildschirm - sie starten Prozesse direkt in der Workstation und vereinfachen den Zugriff auf häufig verwendete Tools und Ressourcen.
Wie funktioniert es
Zur Erstellung einer neuen Integration, die mit der Integrations-API verbunden ist, sind zwei Schritte erforderlich
- Einrichtung - Erstellen einer neuen Integration.
- Runtime- eine Anfrage der API (Suchanfrage) erhalten und eine Antwort (Suchergebnisse) liefern.
In diesem Dokument werden beide Abläufe erläutert.
Einrichtung
Zur Erstellung einer neuen Integration müssen Sie WalkMe die folgenden Parameter übermitteln:
|
Parameter |
Beschreibung |
| apiUrl |
Endpunkt, an den die Workstation-Dienste die Suchanfrage senden werden. Erforderlich |
| apiKey |
Ihr Service Unique Identifier (Eindeutige Kennung Ihres Dienstes) authentifiziert die Abfragequelle. Erforderlich |
| System-GUID |
Befindet sich im Bildschirm „Workstation-App Settings >Info“. Erforderlich |
| appDescription |
Kurzbeschreibung für die App, die den Nutzern auf der Integrations-Seite angezeigt wird. Beispiel für ein richtiges Format- "Durchsuchen Sie Google Drive-Dateien direkt von der Workstation." Erforderlich |
| customName |
Bezeichnung der Integration, die auf der Seite Integrationen, in den Suchergebnissen und im App-Filter angezeigt wird. Erforderlich |
| customImage |
URL des Symbols, das auf der Integrations-Seite, in den Suchergebnissen und im App-Filter angezeigt wird. Erforderlich |
Wenn Sie eine neue Integration erstellen möchten, wenden Sie sich an Ihren Customer Success Manager und geben Sie die in der obigen Tabelle aufgeführten Parameter sowie die entsprechende System-GUID an.
Künftig wird diese Funktion in die WalkMe-Konsole aufgenommen und vom Systemadministrator verwaltet.
Wie in der nachfolgenden Abbildung beschrieben, beginnt die Einrichtung in der DB (in Zukunft in der Konsole). Nach Angabe der Einrichtungsparameter testen wir die Integration, damit wir eine einwandfreie Antwort erhalten.
Dieser Test wird mit einem „Dummy-Benutzer“ durchgeführt, der auf unserer Seite erstellt wird. Eine Konfiguration oder Einrichtung auf der Seite des externen Dienstes ist nicht erforderlich, da es sich um einen regulären Suchabfrage-Aufruf handelt, der anzeigt, ob der Ablauf erfolgreich abgeschlossen wurde.
Laufzeit
Ausgangspunkt für den Ablauf ist, dass der Endbenutzer in der Workstation-App etwas sucht.
Es wird ein API-Aufruf an den API-Endpunkt (URL) mit dem angegebenen API-Schlüssel unter folgenden Bedingungen erstellt-
- Der Benutzer gibt 3 oder mehr Zeichen ein (oder 2 Zeichen auf Chinesisch/Japanisch).
- Die Zeitüberschreitung für die Suche beträgt 300 ms (Millisekunden) ab dem letzten eingegebenen Zeichen (auch als Entprellzeit bezeichnet). Das bedeutet, der Nutzer kann Buchstaben in einem kontinuierlichen Tempo eingeben, wobei jeder Buchstabe die Suche nicht auslöst, sondern sie erst nach Ablauf der Zeitspanne beginnt.
Sobald diese Suchanfrage angestoßen wird, sendet die Integrations Such-API einen Suchanfrageaufruf mit den Parametern.
Suchablauf
Suchabfrage
Von der Integrations API gesendet:
POST <apiURL>/(search)Content-type: application/jsonHeaders:{ Authorization: <apiKey>}Body:{ "user": "user@email.com" "system": "652c91b1ec444c76a313a68f69478b93" "env": "prod" "term": "itay"} |
|
Parameter |
Beschreibung |
| Benutzer | E-Mail des Benutzers |
| System | System-GUID- eine 32-Zeichen-Kette |
| env | Art der Workstation-Umgebung Verfügbare Werte
|
| Laufzeit | Suchabfrage, die in der Workstation-App eingegeben wird |
Suchergebnisse
An Integrationen API gesendet (als POST-Aufruf):
Body:[{ "id": "b2f8510d-9547-4d53-978f-6fc24371c113", "title": "Creating a user", "description": "WalkMe does not collect personally identifiable information (PII) other than IP addresses in logs for security purposes, end users' approximate geolocation (country and city in which they are located) and masked IP addresses for the ongoing operation of the WalkMe system.", "mimeType": "Answers", "externalType": "Article", "created": "2022-01-30T14:35:16.57Z", "modified": "2022-01-30T14:37:07.40Z", "source": "confluence", "category": "Gitlab Service User creation and configuration", "detail": "Account Management", "relationaltime": "2022-01-30T14:35:16.57Z" }}] |
API-Referenz
| Attribut | Typ | Beschreibung |
| Id | String (Zeichenfolge) |
Die eindeutige Artikelkennung. Erforderlich |
| Titel | String (Zeichenfolge) |
Artikelbezeichnung Erforderlich |
| Beschreibung | String (Zeichenfolge) |
Die Beschreibung/Zusammenfassung des Artikels. Ist diese Option aktiviert, wird der Titel des Suchergebnisses fett gedruckt und die Beschreibung darunter angezeigt. Optional |
| Link | URL |
Die URL für den Zugriff auf den Artikel nach dem Anklicken des Suchergebnisses. Erforderlich |
| mimeType | String (Zeichenfolge) |
Die Filterkategorie, in der der Artikel angezeigt werden soll. Es muss eine genaue Übereinstimmung einer der folgenden Optionen in dieser Liste angezeigt werden-
Erforderlich |
| externalType | String (Zeichenfolge) |
Der Artikeltyp Beispielsweise Artikel, Dashboard, Fall usw. Wenn sie ausgefüllt ist, wird sie auf dem Element neben dem Namen der Integration angezeigt. Optional |
| Erstellt | Datum Uhrzeit |
Das Datum und die Uhrzeit, zu der das Objekt erstellt wurde. Dieser Parameter wird nicht auf der Benutzeroberfläche angezeigt, sondern dient der Sortierung. Optional |
| Geändert | Datum Uhrzeit |
Das Datum und die Uhrzeit, zu der das Element kürzlich aktualisiert wurde. Dieser Parameter wird nicht auf der Benutzeroberfläche angezeigt, sondern dient der Sortierung. Optional |
| Kopieren | String (Zeichenfolge) |
Falls ausgefüllt, wird eine Kopierschaltfläche auf dem Suchergebnis angezeigt. Durch Anklicken dieser Schaltfläche wird der angegebene Text (Artikelverknüpfung, Name, ID usw.) kopiert. Wird normalerweise mit dem Link des Artikels ausgefüllt. Optional |
| Vertrauen | Dezimal |
Parameter für die Anzeige der Genauigkeit der Antwort (in Prozent). Falls sie ausgefüllt ist, wird sie auf der Benutzeroberfläche der Suchergebnisse angezeigt. Optional |
| source | String (Zeichenfolge) |
Zeigt die Herkunft der Antwort an (z.B. - Confluence). Das Symbol wird auf der Benutzeroberfläche der Suchergebnisse neben einem Lupensymbol angezeigt. Optional |
| Kategorie | String (Zeichenfolge) |
Parameter, mit dem Ask-AI die Kategorie des Artikels anzeigen kann ("Brotkrümel"). Falls sie ausgefüllt ist, wird sie auf der Benutzeroberfläche der Suchergebnisse über dem Titel angezeigt. Optional |
| PoweredBy | String (Zeichenfolge) |
Falls ausgefüllt, wird eine Notiz auf der Benutzeroberfläche der Suchergebnisse unten rechts angezeigt. Beachten Sie, dass der Name der Integration und das Symbol nicht im Ergebnis angezeigt werden, sofern ausgefüllt. Optional |
| Detail | String (Zeichenfolge) |
Falls ausgefüllt, werden diese Daten Optional |
| relationalTime | Datum Uhrzeit |
Falls ausgefüllt, werden diese Daten auf der Benutzeroberfläche der Suchergebnisse am Ende derselben angezeigt. Zeigt eine Referenzzeit entsprechend dem angegebenen Datum vs. der aktuellen Zeit (z. B. vor 3 Tagen). Optional |
Einschränkungen
Die Länge von Stringfeldern ist auf 255 Zeichen beschränkt.
Parameter für das Design der Benutzeroberfläche
Error Handling (Fehlerbehandlung)
In der Regel führt der Datenfluss zwar zu einer "HTTP 200"-Antwort mit einem Klartext-OK, was bedeutet, dass die Suchergebnisse erfolgreich angezeigt wurden, allerdings müssen wir uns auf Szenarien vorbereiten, in denen die Übermittlung der Suchergebnisse fehlschlägt.
Die in diesem Abschnitt angezeigten Fehler werden auf der Seite der Integrations-API erzeugt und sollten die Fehlerursache so genau wie möglich angeben.
Die API-Reaktion kann Fehler ("HTTP 400") auslösen, wenn sie mangelhaft geformte Anfragen erhält, wenn ungültige Schlüssel verwendet werden oder wenn etwas wirklich Ungewöhnliches verhindert, dass sie in die Suchergebnisse aufgenommen wird.
|
Fehler |
Beschreibung |
| invalid_structure | Zeigt in der Regel an, dass die empfangene Anfrage mangelhaft ist - vielleicht ist das JSON falsch strukturiert oder der Nachrichtentext ist nicht richtig eingebettet. Die Anforderung sollte nicht ohne Berichtigung wiederholt werden. |
| api_key_invalid | Zeigt einen nicht existierenden oder ungültigen API-Schlüssel an, der angesprochen wird. Die Anforderung sollte ohne Änderung des API-Schlüssels nicht wiederholt werden. |
| api_url_invalid | Zeigt an, dass die angesprochene API-URL ungültig ist. Die Anforderung sollte ohne Änderung der API-URL nicht wiederholt werden. |
| title_invalid | Zeigt an, dass der Titel, der ein obligatorischer Wert ist, nicht gesendet wurde oder nicht den Zeichenbeschränkungen entspricht. |
| link_invalid | Zeigt an, dass der Link, der ein obligatorischer Wert ist, nicht gesendet wurde oder nicht in den Zeichenbeschränkungen liegt. |
| mimeType_invalid | Zeigt an, dass der mimeType, der ein obligatorischer Wert ist, nicht gesendet wurde oder nicht in den Zeichenbeschränkungen liegt. |
| id_invalid | Zeigt an, dass die ID, die ein obligatorischer Wert ist, nicht gesendet wurde oder nicht in den Zeichenbeschränkungen liegt. |
Sicherheitsübersicht
Die Enterprise-Suche verwendet Integrationen von Drittanbietern für die Implementierung einer „föderalen Suche“. Suchvorgänge innerhalb von Workstation werden von einer NLP Engine und einer Grafikdatenbank unterstützt, die eine hervorragende Benutzererfahrung bieten.
Workstation Enterprise Search indexiert keine Daten von Drittanbietern in einer unabhängig durchsuchbaren Datenbank.
Das nachfolgende Sequenzdiagramm beschreibt den Suchalgorithmus:
Technische Hinweise
Um sicherzustellen, dass die Integration Workstation-ServiceNow korrekt funktioniert, müssen Kunden die folgenden IP-Adressen auf die Whitelist setzen:
- QA: 54.229.168.224
- PROD: 52.53.115.147
- EUPROD: 3.126.219.141