Workstation-Benachrichtigungen API

Last Updated Juni 14, 2023

Kurzübersicht

Mit der Workstation-Benachrichtigungen API können Sie Ereignisse in jedem System (auch wenn es keinen WalkMe-Snippet hat) verwenden, um eine Benachrichtigung in WalkMe auszulösen und Ihre Benutzer automatisch auf dem neuesten Stand zu halten. Auslösen von Workstation-Benachrichtigungen mit einem REST-Aufruf an unseren WalkMe Notification Webhook.

Dieser Artikel enthält die Informationen, die für den REST-Aufruf erforderlich sind, der sowohl ein Authentifizierungs-Token als auch eine JSON-Nutzlast erfordert.

Anwendungsfälle

Anzeigen von Warnungen, wenn ein System ausgefallen ist oder Probleme hat (AWS- oder Slack-Server ausgefallen)
Benachrichtigen einer genehmigenden Person, wenn ein neues ServiceNow-Ticket ihre Überprüfung erfordert
Informieren Sie Benutzer, wenn ihr Okta-Passwort abgelaufen ist
Erinnern Sie Benutzer, die ihr Open Enrollment bereits abgeschlossen haben
und mehr!

Jedes System, das eine REST-API aufrufen kann, kann zum Auslösen von Benachrichtigungen in Workstation verwendet werden.

Bevor Sie beginnen …

Für den Aufruf der API sind einige Berechtigungen und technische Einstellungen erforderlich. Stellen Sie sicher, dass Sie Zugriff haben und Folgendes tun können:

Zugriff auf das Admin Center für Ihr Workstation-System, um das API-Zugriffstoken zu erhalten
- Hinweis: Wenn Ihr Unternehmen über mehr als ein Workstation-System verfügt, müssen Sie für jedes System separate API-Aufrufe tätigen.
Anwendung zum Konfigurieren und Ausführen von Aufrufen (z. B. Zapier oder Postman) an die Benachrichtigungs-API.
- Sie müssen eine Anwendung haben, die authentifizierte ausgehende REST-API-Aufrufe tätigen kann. Wenn Sie sich nicht sicher sind, ob Ihr Unternehmen über eine solche Anwendung verfügt, wenden Sie sich an Ihr IT-Team, um Optionen zu besprechen.

Funktionsweise

Folgendes benötigen Sie von WalkMe, um die API zu aktivieren. Nachfolgend erfahren Sie, wie Sie alles erfassen können.

Authentifizierung und Erstellung eines Zugriffstokens
Identifizierung der Benachrichtigung des Kommunikationszentrums und des Zielpublikums
Erstellen der JSON-Nutzlast
Den Aufruf tätigen

Insbesondere finden Sie hier die notwendigen Informationen, um eine JSON-Benachrichtigung mit den folgenden Informationen zu verwenden:

System-ID
Benachrichtigungsvorlage-ID
Endbenutzer-ID oder Zielgruppen-ID
Benachrichtigungsart: Popup oder Push
Benachrichtigungstitel
Beschreibung
Informationen überschreiben

Authentifizierung und Erstellung eines Zugriffstokens

Was ist ein Zugriffstoken?

Ein Zugriffstoken ist eine Anmeldeinformation, das von einer Anwendung zum Zugriff auf eine API verwendet werden kann. Sie informieren die API, dass der Inhaber des Tokens berechtigt ist, auf eine bestimmte Aktion zuzugreifen.

Das Zugriffstoken authentifiziert den API-Aufruf und gibt der Anwendung die Erlaubnis, Daten von ihrem System an die Workstation zu übergeben.

Erstellen von Zugriffstoken

Gehen Sie zum Admin Center
Navigieren Sie zur Registerkarte „API Keys“: https://admin.walkme.com/account-api-keys
Klicken Sie auf Create new Key (Neuen Schlüssel erstellen).

Im Bedienfeld „Create new key“:

Benennen Sie den Schlüssel
- Tipp: Geben Sie den Zweck des Schlüssels im Namen an, um Ihnen zu helfen, sich später zu erinnern.
Aktivieren Sie Notification API (Benachrichtigungs-API)
Wählen Sie Write (Schreiben) aus dem Dropdown-Menü aus
Klicken Sie auf Create (Erstellen).

Im Bedienfeld „Key Details“:

Kopieren der Client-ID und des Client-Secret

Speichern des Client-Secrets

Sie werden das Secret nicht wieder sehen, also speichern Sie es irgendwo zugänglich, Sie werden es bald wieder brauchen.

Authentifizierungs-Token

Für zusätzlichen Support und um das Authentifizierungs-Token zu erhalten: Seite der Entwickler

ComCenter-Benachrichtigung und Zielgruppen-ID

Erstellen Sie eine Benachrichtigungsvorlage

Wechseln Sie zum Kommunikationszentrum und erstellen Sie eine benutzerdefinierte Vorlage (Erstellen einer Meldung) Bei der Meldung, die Sie für die API erstellen, sind einige Dinge zu beachten:

Die Meldung kann nur über eine Schaltfläche verfügen
Die Schaltflächenaktion kann nur die Link Action verwenden
- Sie können dynamische Links oder WalkMe-Permalinks verwenden.

Sie können die Meldung nicht mehr bearbeiten, nachdem Sie die API konfiguriert haben. Daher müssen Sie überprüfen, ob Sie mit Ihrer Meldung einverstanden sind.

Optional: Ergänzen Sie die Vorlage mit Überschreibungsregeln

Wenn Sie möchten, dass eine Benachrichtigung entweder für den Benutzer oder für das Ereignis personalisiert wird, das ausgelöst wird, können Sie dynamische Werte hinzufügen, die von der API automatisch ausgefüllt werden.

In der Abbildung sehen Sie zwei Beispiele für Werte, die mit dynamischem Text überschrieben werden, der je nach den Werten, die die API auslöst, ersetzt wird.

Die Opportunity ###OPP_NAME_ATTRIBUTE### benötigt zusätzliche Informationen. Klicken Sie auf die Schaltfläche unten, um von WalkMe durch Ihre Aktualisierungen geleitet zu werden. Durch das Klicken auf die Schaltfläche gelangen Sie zu ###URL###

Dies ist ein Beispiel für eine API-Benachrichtigung mit Salesforce, die ausgelöst wird, wenn ein neuer Lead zugewiesen wurde. Der Vertriebsmitarbeiter wird über den Namen der Verkaufschance und den Link zum Lead in Salesforce informiert.

###OPP_NAME_ATTRIBUTE### wird in Salesforce durch den Namen der Verkaufschance ersetzt.
###URL### wird durch eine tatsächliche URL ersetzt, sodass bei jedem Auslösen der API eine benutzerdefinierte Aktion für jeden Benutzer möglich ist.

Hinweis: Der Wertname (Beispiel: OPP_NAME_ATTRIBUTE) muss exakt in den JSON kopiert werden, damit er ersetzt werden kann.

Kopieren Sie die erforderlichen Werte

Die folgenden Schritte verbinden die Benachrichtigung mit der API.

Kopieren Sie die von Ihnen erstellte Benutzerdefinierte Vorlagen-ID

Gehen Sie zu CommCenter
Klicken Sie auf New Notification (Neue Benachrichtigung)
Fahren Sie unter Benutzerdefinierte Vorlagen > mit dem Mauszeiger über die Ecke der Meldung
Klicken Sie auf das Kopieren-Symbol, um die ID in Ihre Zwischenablage zu kopieren.
- Beispiel: 75cfcba6-c320-42cb-938e-4c2bd08a43a3

Kopieren Sie die Zielgruppen ID

Endbenutzer-ID vs. Zielgruppe

Eine Zielgruppe ist effizienter, aber Sie können auch bis zu 100 Benutzer basierend auf ihrer Endbenutzer-ID ansprechen. Wir empfehlen die Erstellung einer Zielgruppe, wenn Sie mehr als 10 Endbenutzer-IDs verwenden möchten.

Gehen Sie zu Audiences (Zielgruppen).
Bewegen Sie den Mauszeiger über die Zielgruppe, klicken >Sie auf das 3-Punkte-Menü auf der rechten Seite und dann auf Copy ID >(ID kopieren).
- Sie können dem JSON mehrere Zielgruppen hinzufügen.
- Beispiel für die ID: cf0bd4c1-86fd-4c79-a46a-c730d6789e63

Hinzufügen von Informationen zur API-Verbindungsapplikation

Zusätzlichen Support erhalten Sie auf der Seite der Entwickler.

Jetzt ist es an der Zeit, einige Informationen über Ihre API einzugeben. Zur Klarstellung: Wir verwenden Zapier zur Erläuterung, aber wir empfehlen diese Anwendung nicht gegenüber anderen. Jede ähnliche App funktioniert.

Die unten verwendeten Informationen sind für alle Anwendungen allgemein notwendig:

URL = https://api.walkme.com/accounts/connect/token
Payload Type = (Content-Type) application/x-www-form-urlencoded
Data = grant_type → client_credentials

Hinzufügen der Basis-Authentifizierung

Bei der Verwendung von Basic Auth ist die ClientID der Benutzername und das Client-Geheimnis wird als Passwort verwendet.

Client-ID | Client-Secret (kopiert vom Admin Center)
- Beispiel
  0o234234234UqD5d7 | JVnD346346346436345asfgasgbPt_4T7h2_

Sobald Sie diese Informationen hinzugefügt haben, erhalten Sie ein Zugriffstoken.

Kopieren Ihres Zugriffstokens

Wenn Sie Zapier verwenden, können Sie diesen Schritt löschen, nachdem Sie das Token kopiert haben.

Aktualisieren Sie den JSON-Code

Jetzt ist es an der Zeit, die Leerstellen auszufüllen und den JSON-Code zu verwenden, der die Benachrichtigung aufrufen wird.

{

"notification": {

"systemId": "<the workstation system id>", //Erforderlich, wenn Sie über mehr als ein Workstation-System verfügen

"templateId": "<template id>", //Erforderlich

"endUsersIds": ["<end user id 1>","<end user id 2>","<...>"], //Sie benötigen entweder eine Endbenutzer-ID oder eine Zielgruppen-ID (Sie können beide verwenden), entfernen Sie diejenige, die Sie nicht verwenden

"audiencesIds": ["<audience id 1>","<audience id 2>","<...>"], //Sie benötigen entweder eine Endbenutzer-ID oder eine Zielgruppen-ID (Sie können beide verwenden), entfernen Sie diejenige, die Sie nicht verwenden

"notificationType": "<wie die Benachrichtigung angezeigt wird, Push vs. Popup>", //Optional, standardmäßig Push, entfernen, wenn nicht verwendet

"Titel": "<Nachrichtentitel, wie er in der ComCenter-Nachrichtentabelle erscheint>", //Optional, entfernen, wenn nicht verwendet

"runtimeTitle": "<was den Endbenutzern in der Arbeitsplatzliste und in der Push-Benachrichtigung angezeigt wird>", //Optional, entfernen, wenn nicht verwendet

"runtimeDescription": "<was den Endnutzern in der Workstation-Liste und in der Push-Nachricht angezeigt wird>", //Optional, entfernen, wenn nicht verwendet

"startAt": "<start date YYYY-MM-DD hh:mm>", // Optional, standarmäßig ist die Zeitzone UTC eingestellt, Sie können ein Datum ohne Uhrzeit hinzufügen, Standardzeit ist 00:00 UTC, entfernen Sie alles, was Sie nicht verwenden

"endAt": "<end date YYYY-MM-DD hh:mm>", // Optional, Standardwert 30 Tage von jetzt an, Sie können ein Datum und keine Uhrzeit hinzufügen, Standardzeit ist 00:00, alles entfernen, was Sie nicht verwenden

"override": [

{
"key" : "<die Platzhalterzeichenfolge, die in der Benachrichtigungsvorlage ersetzt werden soll>",
"value" : "<der Wert, der anstelle des Platzhalters in die Benachrichtigung aufgenommen werden soll>"
}

// Weitere mit Komma getrennte {key:value}Paare können folgen

// Der Wert könnte zum Beispiel eine URL sein, die von ServiceNow zum Öffnen eines Tickets übermittelt wird

]

}

Entfernen Sie die Zeilen, die Sie nicht verwenden

Wenn optionale Zeilen vorhanden sind, die Sie nicht ausfüllen, entfernen Sie sie aus Ihrem endgültigen Code, um Fehler zu vermeiden

End user and Audience ID

endUsersIds und audiencesIds sind Arrays und müssen mit Klammern geschrieben werden [], und jede Zeichenfolge sollte mit einem Komma getrennt werden ["<id1>","<id2>","<...>"]

Die Standard-Zeitzone ist UTC

Die Standard-Zeitzone ist UTC, aber wenn Sie die Benachrichtigung gemäß einer anderen Zeitzone senden möchten, können Sie diese dazuzählen oder von UTC subtrahieren. Zum Beispiel würde „2023-05-10T11:30:00+03:00“ um UTC+3 gesendet und die entsprechende Zeit in UTC wäre „08:30:00“ (3 Stunden von der angegebenen Zeit subtrahiert).

Hier sehen Sie ein Beispiel eines JSON-Codes mit echten Daten, aus dem einige Zeilen entfernt wurden, um ihn zu vereinfachen.

{
"notification": {
"systemId": "bcf4c7f5682b4aa6875a0fc9bdfa21ca",
"templateId": "1e5afe51-2d2a-4b22-a60a-cf2d6c01d726",
"endUsersIds": ["name@email.com"],
"runtimeTitle": "API Test 3",
"notificationType": "Push",
“override”: [
{“key”: “URL”,
“value”: “www.someurl.com”}
]
}
}

Anruf tätigen

Nun, da wir die nötigen Informationen haben, können wir die Zusammenhänge herstellen. Um den Aufruf zu tätigen (die Systeme zu verbinden, um neue Benachrichtigungen in der Workstation Ihres Unternehmens zu erstellen und zu veröffentlichen), benötigen Sie Ihre JSON sowie:

Methode: POST
URL: https://api.walkme.com/public/v1/notifications/send

War dies hilfreich?

Ja Nein

Nein

Vielen Dank für Ihr Feedback!