Workplace Connector-Webhook-API

  • Freigeben Version: Washingtondc
  • Aktualisiert 1. Februar 2024
  • 4 Minuten Lesedauer

    • Die Workplace Connector-Webhook- API ist eine generische Schnittstelle, die die Speicherung von Daten aus verschiedenen 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 zum Konfigurieren dieser Datensätze finden Sie unter Configure Workplace Connectors.

    Darüber hinaus müssen Sie einen Erweiterungspunkt einrichten, der die Datenkonvertierung/-zuordnung aus der hardware-/sensorbasierten Event-Nutzlast in die Zieltabelle ServiceNow definiert, z. B. die Tabelle „Mitarbeiter-Anwesenheitsdaten“ [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 Event-Daten, die in der Nutzlast des Endpunkts übergeben werden, im Feld Nutzlast dieses Datensatzes.

    Nachdem der Endpunkt die Nutzlast gespeichert hat, wird das Feld Status im Connector-Event-Datensatz auf newfestgelegt, was angibt, dass die Nutzlast nicht verarbeitet wurde.

    Eine regelmäßige Aufgabe sucht nach den neuen Abzeichendatensätzen in der Tabelle „Connector-Ereignisse“, wandelt sie um und schreibt sie in die Tabelle „Mitarbeiter-Anwesenheitsdaten“ [sn_wsd_wc_employee_attendance_data]. Das Feld Status wird dann auf „ Verarbeitet“gesetzt.

    Die Zuordnung der Daten zwischen den Nutzlastdaten im Datensatz „Connector Events“ und dem Datensatz „Employee Attendance Data“ 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 zwei Tage nach dem Erstellungsdatum gelöscht. Datensätze im Fehlerstatus werden nach sieben Tagen ab dem Datum der Erstellung gelöscht. Datensätze im Status „ Neu “ werden nie gelöscht.

    URL-Format

    Versionierte URL: /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 Provider-Konfigurationsdatensatzes, der der Hardware zugeordnet ist, die die Event-Informationen generiert hat. Befindet sich in der Tabelle „Provider-Konfiguration“ [sn_wsd_wc_provider_config].

    Datentyp: Zeichenfolge
    token_name Name des Sicherheitstokens, z. B. ein Benutzername oder ein anderer Wert, der das Sicherheitstoken identifiziert Wird für die Authentifizierung der Anforderung verwendet. Befindet sich in der Tabelle „Provider-Konfiguration“ [sn_wsd_wc_provider_config].

    Datentyp: Zeichenfolge
    token_value Wert, der dem Sicherheitstoken zugeordnet ist, z. B. ein Passwort. Wird für die Authentifizierung der Anforderung verwendet. Befindet sich in der Tabelle „Provider-Konfiguration“ [sn_wsd_wc_provider_config].

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

    Die Namen müssen den Namen entsprechen, die im Erweiterungspunkt „BadgingDataHandler“ identifiziert wurden.

    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 Events innerhalb eines einzelnen Endpunktaufrufs übergeben. Übergeben Sie die Daten jedes Events in ein separates Objekt. Die Daten jedes Ereignisses werden in einem separaten Mitarbeiteranwesenheitsdaten-Datensatz 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
    Fehler.Nachricht Fehlermeldung.

    Datentyp: Zeichenfolge
    status Status der Endpunktverarbeitung.
    Mögliche Werte:
    • failure: Endpunkt fehlgeschlagen. Weitere Details finden Sie im Objekt error.
    • success: Endpunkt erfolgreich abgeschlossen. Datensatz wurde hinzugefügt.

    Datentyp: Zeichenfolge

    cURL-Anforderung

    Das folgende Codebeispiel zeigt, wie dieser Endpunkt aufgerufen wird, um der Tabelle „Connector Events“ mehrere Kartenleserereignisse 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"
}