Webhook-API des Arbeitsplatz-Connectors

  • Freigeben Version: Xanadu
  • Aktualisiert 1. August 2024
  • 4 Minuten Lesedauer

    • Die Workplace Connector-Webhook- API ist eine generische Schnittstelle, die die Speicherung von Daten verschiedener Arten von Arbeitsplatzhardware oder -sensoren (z. B. Abzeichensystemen oder Belegungssensoren) in Workplace Service Delivery-Tabellen ermöglicht.

    Diese API wird im Namespace sn_wsd_wc ausgeführt. Für den Zugriff auf diese API muss das Plugin „Workplace Connectors“ (com.sn_wsd_wc) aktiviert sein.

    Bevor Sie diese API aufrufen, müssen Sie Datensätze in den Tabellen „Connector-Konfiguration“ [sn_wsd_wc_connector_config] und „Provider-Konfiguration“ [sn_wsd_wc_provider_config] konfigurieren. Informationen zur Konfiguration dieser Datensätze finden Sie unter Configure Workplace Connectors.

    Darüber hinaus müssen Sie einen Erweiterungspunkt einrichten, der die Datenkonvertierung/-zuordnung von der hardware-/sensorbasierten Ereignisnutzlast an die Zieltabelle ServiceNow definiert, z. B. die Tabelle mit Anwesenheitsdaten für Mitarbeiter [sn_wsd_wc_employee_attendance_data].

    Weitere Informationen zu Arbeitsplatz-Connector-Webhooks finden Sie unter Workplace Connectors.

    Workplace Connector-Webhook – POST /workplace_connector_webhook/event

    Erstellt einen Datensatz in der Tabelle „Connector-Ereignisse“ [sn_wsd_wc_connector_events] und speichert dann die hardware-/sensorbasierten Ereignisdaten, die in der Nutzlast des Endpunkts übergeben werden, im Feld „Nutzlast“ dieses Datensatzes.

    Nachdem der Endpunkt die Nutzlast gespeichert hat, legt er das Feld Status im Datensatz „Connector Events“ auf neufest, um anzugeben, dass die Nutzlast nicht verarbeitet wurde.

    Eine regelmäßige Aufgabe sucht die neuen Abzeichendatensätze in der Tabelle „Connector Events“, wandelt sie um und schreibt sie in die Tabelle „Anwesenheitsdaten für Mitarbeiter“ [sn_wsd_wc_employee_attendance_data]. Das Feld Status wird dann auf verarbeitetgesetzt.

    Die Zuordnung der Daten zwischen den Nutzlastdaten im Datensatz „Connector Events“ und dem Datensatz „Anwesenheitsdaten für Mitarbeiter“ wird in einem Erweiterungspunkt definiert. Dieser Erweiterungspunkt wird im Feld Erweiterungspunktdefinition in der zugehörigen Connector-Konfigurationstabelle [sn_wsd_wc_connector_config] identifiziert. Für diesen Endpunkt ist dies der Erweiterungspunkt „BadgingDataHandler“.

    Hinweis:
    Datensätze in der Tabelle „Connector-Ereignisse“ im Status „ Verarbeitet “ werden nach zwei Tagen ab dem Erstellungsdatum gelöscht. Datensätze im Fehlerstatus werden nach sieben Tagen ab dem Datum der Erstellung gelöscht. Datensätze im neuen Status werden nie gelöscht.

    URL-Format

    URL mit Versionsnummer: /api/sn_wsd_wc/v1/workplace_connector_webhook/event

    Standard-URL: /api/sn_wsd_wc/workplace_connector_webhook/event

    Unterstützte Anforderungsparameter

    Tabelle : 1. Pfadparameter
    Name Beschreibung
    api_version Optional. Version des Endpunkts, auf den zugegriffen werden soll. Zum Beispiel v1 oder v2. Geben Sie diesen Wert nur an, um eine andere Endpunktversion als die neueste zu verwenden.

    Datentyp: Zeichenfolge
    Tabelle : 2. Abfrageparameter
    Name Beschreibung
    ni.nolog.id Erforderlich. Sys_id des Anbieterkonfigurationsdatensatzes, der der Hardware zugeordnet ist, von der die Ereignisinformationen generiert wurden. Befindet sich in der Tabelle „Anbieterkonfiguration“ [sn_wsd_wc_provider_config].

    Datentyp: Zeichenfolge
    token_name Name des Sicherheitstokens, z. B. ein Anwendername oder ein anderer Wert, der das Sicherheitstoken identifiziert. Wird zur Authentifizierung der Anforderung verwendet. Befindet sich in der Konfigurationstabelle „Anbieter“ [sn_wsd_wc_provider_config].

    Datentyp: Zeichenfolge
    token_value Wert, der dem Sicherheitstoken zugeordnet ist, z. B. ein Passwort. Wird zur Authentifizierung der Anforderung verwendet. Befindet sich in der Konfigurationstabelle „Anbieter“ [sn_wsd_wc_provider_config].

    Datentyp: Zeichenfolge
    Tabelle : 3. Anforderungstextparameter (XML oder JSON)
    Name Beschreibung
    <payload> Name-Wert-Paare der hardware-/sensorbasierten Ereignisdaten.

    Die Namen müssen den im Erweiterungspunkt „BadgingDataHandler“ angegebenen Namen entsprechen.

    Beispiel:

    {
  "Time zone": "(UTC-08:00) Pacific Time (US & Canada)",
  "Event": "Access granted",
  "Door": "L_SJC005_B1.101_ELEVATOR 2 INT",
  "Side": "Reader - In",
  "Cardholder": "ninat.salem",
  "First name": "Nina T",
  "Last name": "Salem",
  "Credential": " ninat.salem's credential",
  "Employee ID (Cardholder)": "10097",
  "Event timestamp": "11/07/2022 00:56:57"
}

    Sie können die Daten mehrerer Ereignisse innerhalb eines einzelnen Endpunktaufrufs übergeben. Übergeben Sie die Daten jedes Ereignisses in einem separaten Objekt. Die Daten jedes Ereignisses werden in einem separaten Mitarbeiter-Anwesenheitsdatensatz gespeichert.

    Hinweis:
    Stellen Sie sicher, dass alle bereitgestellten Zeitstempel der ISO 8601-Formatierung entsprechen, um Probleme bei der Datumsanalyse zu vermeiden.

    Datentyp: JSON-Objekt

    Header

    Die folgenden Anforderungs- und Antwortkopfzeilen gelten nur für diese HTTP-Aktion oder für diese Aktion auf eine bestimmte Weise. Eine Liste der allgemeinen Header, die in der REST API verwendet werden, finden Sie unter Unterstützte REST API-Header.

    Tabelle : 4. Anforderungskopfzeilen
    Kopfzeile Beschreibung
    Akzeptieren Datenformat des Antworttexts. Unterstützt nur application/json.
    Content-Type Datenformat des Anforderungstexts. Unterstützt nur application/json.
    Tabelle : 5. Antwortkopfzeilen
    Kopfzeile Beschreibung
    Keine

    Statuscodes

    Die folgenden Statuscodes gelten für diese HTTP-Aktion. Eine Liste der möglichen Statuscodes, die in der REST API verwendet werden, finden Sie unter HTTP-Antwortcodesder REST-API.

    Tabelle : 6. Statuscodes
    Statuscode Beschreibung
    200 Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet.
    400 Fehlerhafte Anforderung. Ein fehlerhafter Anforderungstyp oder eine falsch formatierte Anforderung wurde erkannt.
    401 Nicht autorisiert. Die Anmeldeinformationen sind falsch oder wurden nicht übergeben.
    404 Nicht gefunden. Das angeforderte Element wurde nicht gefunden.
    500 Interner Serverfehler. Beim Verarbeiten der Anforderung ist ein unerwarteter Fehler aufgetreten. Der Antworttext enthält Informationen zum Fehler.

    Parameter des Antwort-Haupttexts

    Name Beschreibung
    Fehler Beschreibung eines Fehlers, der während der Verarbeitung der Daten aufgetreten ist.

    Datentyp: Objekt

    "error": {
  "detail": "String",
  "message": "String"
"status": "String"
}
    Fehler.detail Informationen, die Details zum Fehler bereitstellen.

    Datentyp: Zeichenfolge
    Fehlernachricht Fehlermeldung.

    Datentyp: Zeichenfolge
    status Status der Endpunktverarbeitung.
    Mögliche Werte:
    • Fehler: Endpunkt fehlgeschlagen. Weitere Informationen finden Sie unter dem Objekt error.
    • erfolgreich: Endpunkt abgeschlossen. Datensatz wurde hinzugefügt.

    Datentyp: Zeichenfolge

    cURL-Anforderung

    Das folgende Codebeispiel zeigt, wie dieser Endpunkt aufgerufen wird, um der Tabelle Connector-Ereignisse mehrere Kartenleser-Ereignisse hinzuzufügen. Vor der Verarbeitung der Anforderung wird die Anforderung authentifiziert.

    curl http://instance.servicenow.com/api/sn_wsd_wc/v1/workplace_connector_webhook/event?token_name=token&ni.nolog.id=8e666cb0a3053110bc6e146546fcdad1&token_value=babugosha  \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data --data "{
  \"Time zone\": \"(UTC+02:00) Jerusalem\",
  \"Event\": \"Access granted\",
  \"Door\": \"L_TLV001_A3.07_KITCHEN AREA INT\",
  \"Side\": \"Reader - In\",
  \"Cardholder\": \" ninat.alem\",
  \"First name\": \" Nina T\",
  \"Last name\": \" Salem\",
  \"Credential\": \" ninat.salem's credential\",
  \"Employee ID (Cardholder)\": 10097,
  \"Event timestamp\": \"11/07/2022 10:57:24\"
}
{
  \"Time zone\": \"(UTC+02:00) Jerusalem\",
  \"Event\": \"Access granted\",
  \"Door\": \"L_TLV003_A4.07_FRONT ENT\",
  \"Side\": \"Reader - In\",
  \"Cardholder\": \" joe.blue\",
  \"First name\": \" Joe\",
  \"Last name\": \" Blue\",
  \"Credential\": \" joe.blue's credential\",
  \"Employee ID (Cardholder)\": 24098,
  \"Event timestamp\": \"11/07/2022 10:59:33\"
}"

    Antwort:

    // Successful response
{
  "staus": "success"
}

// Error response
{
  "error": {
    "message": "Events request is invalid. Events query parms incomplete, some fields are missing",
    "detail": "Missing fields: token_name, token_value"
  }
  "status": "failure"
}