Ziel der Integration und Aufteilung der Verantwortung
Der Betrieb hat ein Zutrittskontrollsystem mit Lesegeräten und Karten sowie ein System zur Zeiterfassung. InnerWeb ist ein unabhängiges ergänzendes System: Es nimmt die Buchungsereignisse entgegen, verknüpft sie mit Qualifikationen, Berechtigungen, Anwesenheit und Erfassung der Arbeitszeit und ersetzt weder das KD-System noch die RCP oder die Personalabteilung.
InnerWeb fertigt und tauscht keine Lesegeräte. Die Integrationsspezifikation ist für den KD-Anbieter bestimmt: Er konfiguriert das Senden der Ereignisse. Aufgabe des Betriebs ist es sicherzustellen, dass der Anbieter die Spezifikation und Zugang zur Testumgebung erhält.
Felder des Ereignisses: was der KD-Anbieter senden soll
Das Ereignis einer Kartenbuchung enthält unter anderem Zeitpunkt, Ort, Vorname, Nachname, Firma, Nummer der aktiven Karte, Telefon, E-Mail und Sprache der Person. Nicht alle Felder müssen im KD-System verfügbar sein, deshalb wird die Spezifikation auf der Ebene der Pflicht- und optionalen Felder abgestimmt.
Das praktische Minimum ist der Zeitpunkt der Buchung, der Ort (Tor oder Lesegerät) und die Kennung der Person: die Nummer der aktiven Karte. Die übrigen Felder erleichtern die Zuordnung der Person zu einem Konto, personenbezogene Daten sind jedoch nur im notwendigen Umfang und auf der Rechtsgrundlage des Betriebs zu übermitteln.
- Zeitpunkt der Buchung mit Angabe der Zeitzone
- Ort: Kennung des Tors oder Lesegeräts
- Nummer der aktiven Karte
- Vor- und Nachname sowie Firma, sofern das KD-System sie speichert
- Sprache der Person, sofern sie für Mitteilungen dient
Beispielhafter Zeitplan der Integration des Webhooks (Annahme)
Authentifizierung: Token mit begrenzter Gültigkeit
InnerWeb nimmt das Ereignis einer Kartenbuchung über einen Webhook entgegen, der mit einem Token mit begrenzter Gültigkeit von 12 Stunden authentifiziert ist. Der KD-Anbieter muss daher die Erneuerung des Tokens vor dessen Ablauf planen und nicht erst nach der Zurückweisung eines Ereignisses.
In der Spezifikation sollte festgehalten werden, wer das Token wie erneuert, was mit Ereignissen geschieht, die nach Ablauf gesendet werden, und wie der Anbieter von einem Fehler erfährt. Gute Praxis ist eine Warteschlange auf Seite des KD-Systems, die das Senden wiederholt, solange der Empfang nicht bestätigt wurde.
Das Token darf nicht in einer offenen Konfigurationsdatei oder im Text einer Serviceanfrage gespeichert werden. Die Übergabe erfolgt über einen Kanal, der von den IT-Abteilungen beider Seiten vereinbart wurde.
Reihenfolge der Arbeiten: vom Test bis zur Produktion
Etappe eins: Der KD-Anbieter erhält die Spezifikation und die Daten der Testumgebung. Etappe zwei: Senden von Testereignissen von einem Tor, Prüfung der Felder und der Zeit. Etappe drei: Senden von allen Toren einer Halle. Etappe vier: Einschalten des ganzen Betriebs und Vergleich der Zahl der Buchungen auf beiden Seiten.
Der Vergleich der Anzahl der Buchungen ist der entscheidende Test: Die Zahl der von der KD gesendeten und von InnerWeb angenommenen Ereignisse im selben Zeitfenster muss übereinstimmen. Abweichungen werden nach Tor und Uhrzeit analysiert, denn sie weisen oft auf ein bestimmtes Lesegerät oder den Zeitpunkt des Ablaufs des Tokens hin.
Fallstricke: Zeit, Duplikate und Buchungen ohne Person
Der erste Fallstrick ist die Zeitzone: Wird die Buchungszeit in Ortszeit ohne Angabe der Zeitzone übermittelt, entsteht in der Zeit der Umstellung von Sommer- auf Winterzeit ein Fehler von einer Stunde, der in der Zeiterfassung wie Überstunden aussieht. Die Zeit ist daher mit Angabe der Zeitzone zu übermitteln.
Der zweite Fallstrick sind Duplikate: Dieselbe Karte wird innerhalb weniger Sekunden zweimal gebucht, weil das Lesegerät sie beim Eintritt und beim Austritt liest. Die Regeln für die Filterung legt man mit dem Sicherheitsdienst fest, nicht im Code der Integration.
Der dritte Fallstrick sind Buchungen ohne Person: eine Kartennummer ohne zugeordnetes Konto oder mit einem Konto, das doppelt vorhanden ist. Solche Ereignisse landen in der Liste der Ausnahmen, und die Kontrolle der doppelten Konten nach dem Import der Karten begrenzt ihre Zahl.
Abnahme und Betrieb
Die Abnahme endet mit einem Protokoll: Liste der Tore, Ergebnis des Vergleichs der Anzahl der Buchungen, Test des Ablaufs und der Erneuerung des Tokens, Test eines Ausfalls der Verbindung. Der Betrieb umfasst einen Alarm für das Fehlen von Ereignissen eines Tores zu den Zeiten, in denen üblicherweise gebucht wird, denn Stille an einem Tor ist oft das erste Anzeichen einer Störung.
Der Betrieb sollte eine Person benennen, die die Alarme entgegennimmt, und den KD-Anbieter, der sie auf Seite seines Systems behebt. Ohne das funktioniert die Integration, bis das erste Problem auftritt.
Bei der Erweiterung des Betriebs um eine neue Halle oder ein neues Tor ergänzt der KD-Anbieter die neuen Lesegeräte in der Übertragung, und der Betrieb aktualisiert die Liste der Orte, damit Ereignisse vom neuen Tor nicht als Buchungen ohne Ort ankommen. Die Änderung der Liste der Tore sollte ein Schritt des Änderungsverfahrens sein, ebenso verbindlich wie die Bestellung eines Lesegeräts.
Videomaterial
Häufig gestellte Fragen
Wechselt InnerWeb die Lesegeräte?
Nein. InnerWeb integriert sich mit dem bestehenden KD-System, und die Spezifikation ist für dessen Anbieter bestimmt.
Wie lange ist das Token des Webhooks gültig?
12 Stunden, daher muss der KD-Anbieter die Erneuerung planen.
Welche Daten enthält das Ereignis einer Buchung?
Unter anderem Zeitpunkt, Ort, Vorname, Nachname, Firma, Nummer der aktiven Karte, Telefon, E-Mail und Sprache der Person, im mit dem Betrieb vereinbarten Umfang.
Wie prüft man, dass die Integration funktioniert?
Man vergleicht die Zahl der von der KD gesendeten und von InnerWeb angenommenen Buchungen im selben Zeitfenster, getrennt nach Tor.
Quellen
Geben Sie die Spezifikation an den KD-Anbieter weiter
Wir bereiten die Spezifikation der Felder und der Authentifizierung für Ihren KD-Anbieter sowie den Testplan mit einem Tor vor.
Sprechen wir