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
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