InnerWeb
Zum Inhalt springen

Webhook für Ereignisse aus dem KD-System: Integrationsspezifikation für den Integrator

Ein Zutrittskontrollsystem erfasst jede Kartenbuchung: wer, wo und wann. Der Integrator, der den Webhook für das Freigabesystem beschreibt, legt in der Spezifikation fest, welche Felder das KD-System sendet, wie der Kanal authentifiziert wird und wie der Empfänger Wiederholungen behandelt. Im Folgenden die Anforderungen an Felder, Paarbildung, Duplikate und Warteschlangen.

5
Grundfelder des Ereignisses in der Spezifikation
Quelle: Karte
4
Testfälle vor dem Start der Integration
Quelle: Karte

Was die Spezifikation vom KD-System verlangt

Das KD-System sendet Buchungsereignisse in Echtzeit. Jedes Ereignis enthält die Buchungszeit, die vom Leser erfasst wurde, die Richtung (Eingang oder Ausgang) und eine Ereignis-ID, dazu die Kennung der Karte oder des Kontos und die Kennung des Lesers. Dank der Zeit des Lesers spiegelt die Anwesenheitshistorie den tatsächlichen Moment des Durchgangs wider und nicht den Zeitpunkt der Zustellung der Nachricht.

InnerWeb empfängt die Ereignisse aus dem KD-System über einen authentifizierten Webhook und verknüpft sie mit Qualifikationen, Freigaben, Anwesenheit und Zeiterfassung. Die Regeln für die Paarbildung von Eingängen und Ausgängen sowie für das Verwerfen von Duplikaten legt die Spezifikation gemeinsam mit dem Anbieter des KD-Systems fest, weil sie von der Konfiguration der Leser und Tore im Werk abhängen. Liefert der Leser in einer konkreten KD-Installation keine Richtung, ist das ein technischer Sachverhalt auf Seite des KD-Systems und muss gesondert in der Spezifikation beschrieben werden.

Wie das Ereignis in der Spezifikation zu beschreiben ist

Die Spezifikation für den Integrator sollte kurz und eindeutig sein. Jedes Feld hat einen Namen, einen Typ, ein Format und eine Beschreibung der zulässigen Werte. Sie beschreibt außerdem die Authentifizierung: ein Token mit begrenzter Gültigkeit, das die Integration automatisch erneuert.

  • Kennung des Kontos oder der Karte in einer zwischen den Systemen vereinbarten Form.
  • Kennung des Lesers, die dem im Freigabesystem definierten Ort entspricht.
  • Buchungszeit des Lesers mit Zeitzone in einem festen Format.
  • Richtung: Eingang oder Ausgang, entsprechend der Konfiguration des Lesers im KD-System.
  • Eindeutige Ereignis-ID zum erneuten Senden und zum Entfernen von Wiederholungen.

Warum der Leser im System einen Ort haben muss

Eine Buchung an einem Leser ohne zugeordneten Ort, also ohne Aktionspunkt, löst keinen Schulungsalarm aus. Das Ereignis kommt an, hat aber keine Wirkung. Prüfen Sie vor dem Start der Integration, ob jeder Leser ein Gegenstück im System hat.

Elemente der Spezifikation der KD-Integration

Elemente der Spezifikation der KD-IntegrationBalkendiagramm: 5 Felder des Ereignisses und 4 Testfälle in der Spezifikation der Integration.012345AnzahlFelder des EreignissesFelder des Ereignisses: 5 Anzahl5TestfälleTestfälle: 4 Anzahl4
Quelle: Karte der Komponente: Struktur der Spezifikation und der Tests

Paarbildung von Eingängen und Ausgängen und Duplikate

Bei der Paarbildung von Eingängen und Ausgängen verbindet der Empfänger aufeinanderfolgende Buchungen desselben Kontos zu Paaren, und Ereignisse ohne Paar kennzeichnet er zur Prüfung. Der maximale Abstand zwischen Eingang und Ausgang ist an die Arbeitsorganisation im Werk anzupassen, mit einem Puffer für Überstunden und Pausen. Den konkreten Wert und den Umgang mit nicht gepaarten Ereignissen legt die Spezifikation mit dem Anbieter des KD-Systems fest.

Die Paarbildung ist eine Methode, kein Beweis: Der Bericht sollte zeigen, welche Paare das Ergebnis einer Regel sind und welche direkt vom Leser stammen. So bleibt die Kontrolle von Anwesenheit und Zeiterfassung für die Prüfung nachvollziehbar.

Wiederholte Buchungen

Eine Beschäftigte oder ein Beschäftigter hält die Karte zweimal an den Leser, weil sich das Tor nicht sofort öffnet. Die Spezifikation sollte festlegen, wie kurz aufeinanderfolgende Buchungen derselben Karte am selben Leser behandelt werden, damit die Anzahl der Buchungen in einer Schicht nicht ungerade wird und die Paare nicht auseinanderlaufen. Den Zeitschwellenwert vereinbaren Sie mit dem Anbieter des KD-Systems.

Netz des Werks und die Outbox-Warteschlange

Das Netz des Werks kann so konfiguriert sein, dass der Anwendungsserver keinen Verkehr nach außen senden darf. Ausgehende Webhooks können dann in einer Outbox-Tabelle gespeichert werden, und die Übergabe erfolgt über einen anderen, mit dem Kunden vereinbarten Kanal. Der Integrator beschreibt diesen Kanal in der Spezifikation zusammen mit der maximalen Verzögerung der Zustellung.

Aus Sicht des Integrators ist die Idempotenz wichtig: Dasselbe zweimal gesendete Ereignis darf nicht als zwei Buchungen entstehen. Die eindeutige Ereignis-ID löst dieses Problem.

Sicherheit der Konten beim Verknüpfen der Ereignisse

Das System verbindet oder leitet ein aktives Konto niemals allein aufgrund einer ähnlichen Nachnamensschreibweise um, und Konten mit einer Karte erscheinen in der Liste an erster Stelle. Ereignisse aus dem KD-System gelangen daher über die Kennung zum richtigen Konto, nicht über den Namen.

Vereinbaren Sie mit dem Anbieter des KD-Systems, dass die Kennung im Ereignis dauerhaft ist und sich beim Austausch der Karte nicht ändert. Dann unterbricht die Migration der Karten auf eine neue Technologie die Historie der Buchungen nicht.

Tests vor dem Start

Prüfen Sie vor dem Start vier Fälle. Erstens: Eingang und Ausgang in derselben Schicht bilden ein Paar. Zweitens: eine wiederholte Buchung in kurzem Abstand zählt als eine. Drittens: das zweimalige Senden desselben Ereignisses mit derselben Ereignis-ID erzeugt kein Duplikat. Viertens: eine Buchung an einem Leser ohne Ort im System wird als Konfigurationsfehler gemeldet.

Halten Sie die Testergebnisse im Abnahmeprotokoll der Integration fest. Integrator und Kunde haben dann einen gemeinsamen Nachweis, dass der Webhook der Spezifikation entspricht, und im Streitfall lassen sich die Ereignisse aus dem Protokoll nachvollziehen.

Videomaterial

Häufig gestellte Fragen

Welche Daten sollte ein Ereignis aus dem KD-System enthalten?

Die Buchungszeit des Lesers, die Richtung Eingang oder Ausgang, die Ereignis-ID, die Kennung der Karte oder des Kontos und die Kennung des Lesers.

Wozu dient die eindeutige Ereignis-ID?

Sie erlaubt das erneute Senden ohne das Risiko, zwei Buchungen zu erzeugen. Der Empfänger entfernt Wiederholungen anhand dieser ID.

Was geschieht, wenn der Server keine Verbindung zum externen Netz herstellen kann?

Die Webhooks können in einer Outbox-Tabelle gespeichert werden, und die Übergabe erfolgt über einen anderen, mit dem Kunden vereinbarten Kanal.

Webhook-Spezifikation für Ihren Integrator

Wir erarbeiten mit Ihnen die Beschreibung der Felder, der Paarbildung und der Warteschlangen für Ereignisse aus dem KD-System. Vereinbaren Sie ein Gespräch mit dem Team von InnerWeb.

Sprechen wir