InnerWeb
Zum Inhalt springen

Webhook Kartenbuchung: Felder der Meldung aus der Zutrittskontrolle

Der Anbieter eines Zutrittskontrollsystems, der Buchungen an InnerWeb sendet, sollte in jeder Meldung den Zeitpunkt der Buchung, den Buchungsort sowie die Daten von Person und Firma übermitteln. Zwei Felder sind Pflicht, die übrigen entscheiden über die Qualität der Verknüpfung von Karte und Konto. Im Folgenden sieben Empfehlungen für den Integrator, jeweils mit Begründung.

2
Pflichtfelder: Vor- und Nachname sowie Firmenname
3
Merkmale jedes Ereignisses: Zeit am Leser, Richtung, Kennung
Quelle: Spezifikation der Integration

Für wen diese Liste bestimmt ist

Die Liste richtet sich an den Integrator oder Administrator des Zutrittssystems, der den Versand der Buchungen an InnerWeb aufbaut. Sie setzt voraus, dass die Leser unverändert bleiben und sich die Änderung allein auf das bezieht, was das Zutrittssystem nach jeder Kartenbuchung sendet.

InnerWeb stellt keine Leser her und tauscht sie nicht aus, daher hängt die gesamte Qualität der Integration von den Daten in der Meldung ab. Die folgenden Empfehlungen ergeben sich aus den Anforderungen der Spezifikation der Integration, in der InnerWeb die Ereignisse aus dem Zutrittssystem annimmt und verknüpft.

Empfehlung 1: Nummer der aktiven Karte immer übermitteln

Die Nummer der aktiven Karte ist die Kennung, über die InnerWeb die Buchung dem Konto der Person zuordnet. Ohne sie muss sich das System auf Vor- und Nachnamen stützen, was bei Personen mit gleichen Daten das Risiko einer Verwechslung erhöht.

Begründung für Einkauf und IT: Das Feld der Kartennummer ist der Schlüssel, um die Arbeitsschutzschulung zu prüfen, bevor das Tor die Person durchlässt. Zutrittsberechtigung, Qualifikationen und Schulungen sind mit dem Konto der Person verknüpft, und die Kartennummer aus dem Zutrittssystem wird zum Schlüssel für dieses Konto.

Felder der Meldung nach Kategorie

Felder der Meldung nach KategorieAufteilung der Felder der Meldung: 2 Pflichtfelder, 3 zur Identifikation und zum Kontext, 3 für Kontakt und Sprache.Pflicht: 2 Felder (25%)Identifikation und Kontext: 3 Felder (37,5%)Kontakt und Sprache: 3 Felder (37,5%)8FelderPflicht2 Felder (25%)Identifikation und Kontext3 Felder (37,5%)Kontakt und Sprache3 Felder (37,5%)
Quelle: Zeit, Ort, Vor- und Nachname, Firmenname (Pflicht), Kürzel, Kartennummer, Telefon, E-Mail, Sprache

Empfehlung 2: Vor- und Nachname als Pflichtfeld

Vor- und Nachname sind in der Meldung Pflichtfelder. Eine Meldung ohne sie kann weder ein Konto anlegen noch eine Buchung einer neuen Person zuordnen. Der Anbieter sollte sie deshalb in derselben Form senden, in der sie in der Personenstammdatei des Zutrittssystems stehen, ohne Abkürzungen und ohne Zusätze wie den Namen der Zeitarbeitsfirma.

Empfohlen wird außerdem das Feld Kürzel, sofern die Personenstammdatei des Zutrittssystems es führt. Es hilft, Personen mit gleichen Daten auseinanderzuhalten.

Empfehlung 3: Firmenname in einheitlicher Schreibweise

Der Firmenname ist Pflicht, und die Fremdfirma wird anhand des Namens aus der Meldung zugeordnet. Bucht eine Person, die dem System unbekannt ist, legt das System Konto und Firma aus den Meldungsdaten an. Zwei Schreibweisen derselben Firma ergeben daher zwei Firmen.

Empfehlung für den Integrator: Den Firmennamen aus einem Auswahlfeld (Stammdatenliste) des Zutrittssystems senden, nicht aus einem Freitextfeld. Gibt es kein solches Feld, muss mit dem Administrator des Zutrittssystems eine verbindliche Schreibweise festgelegt werden.

Empfehlung 4: Buchungsort aus einer festen Auswahlliste

Das Feld für den Buchungsort unterscheidet die Standorte der Leser. Ereignisse von einem Ort, für den in InnerWeb keine Vorlage existiert, landen im Protokoll und lösen keinen Schulungsalarm aus. Der Integrator sollte deshalb alle Ortsbezeichnungen aus dem Zutrittssystem übermitteln, und das Team Arbeitsschutz ordnet ihnen Vorlagen zu.

Die Bezeichnung des Ortes muss stabil bleiben. Wird ein Leser im Zutrittssystem umbenannt, ohne dass InnerWeb informiert wird, landen die Ereignisse wieder an einem Ort ohne Vorlage.

Empfehlung 5: Zeitpunkt der Buchung und Übertragung in Echtzeit

Die Spezifikation der Integration verlangt, dass das Zutrittssystem Ereignisse in Echtzeit sendet, mit dem am Leser erfassten Zeitpunkt der Buchung und nicht dem Zeitpunkt des Versands. So entspricht die Zutrittserfassung dem, was tatsächlich am Tor geschehen ist.

Die Warteschlange der Ereignisse nach einem Leitungsausfall sollte so schnell wie möglich geleert werden, wobei die ursprünglichen Zeitpunkte erhalten bleiben. Der Integrator sollte dokumentieren, welche Verzögerung in seinem System akzeptabel ist.

Bei der Auswahl der Felder lohnt es sich außerdem festzuhalten, welche die Personenstammdatei des Zutrittssystems automatisch füllt und welche der Administrator von Hand ergänzen muss. Diese Übersicht verkürzt das Gespräch mit dem Anbieter und zeigt sofort Felder, die das Zutrittssystem gar nicht führt.

Empfehlung 6: Telefon, E-Mail und Sprache nur wenn sicher

Telefon, E-Mail und Sprache sind in der Meldung zusätzliche Felder. Senden Sie sie nur, wenn die Personenstammdatei des Zutrittssystems sie enthält und sie aktuell sind, da fehlerhafte Kontaktdaten, die bei einem neuen Konto erfasst werden, später nur schwer zu finden sind. Besonders das Sprachfeld lohnt sich bei ausländischen Personen, weil es die Fassung der Schulung bestimmt.

Empfehlung 7: Authentifizierung und Umgang mit abgelaufenem Token

Der Webhook-Aufruf benötigt einen Token aus dem Anmeldeendpunkt der API. Der Token ist zeitlich begrenzt gültig und wird durch die Integration automatisch erneuert. Der Integrator sollte die Anmeldung wiederholen und abgewiesene Meldungen erneut senden, statt sie zu verwerfen.

Die Meldung sollte die Richtung (Eingang oder Ausgang) und die Ereigniskennung enthalten. Die Regeln für das Paaren von Ein- und Ausgängen sowie für das Verwerfen von Dubletten werden zusammen mit dem Anbieter der Zutrittskontrolle in der Spezifikation festgelegt, daher sind doppelte Sendungen unerwünscht.

Videomaterial

Häufig gestellte Fragen

Welche Felder sind in der Buchungsmeldung Pflicht?

Vor- und Nachname sowie der Firmenname. Die übrigen Felder, darunter die Nummer der aktiven Karte, verbessern die Verknüpfung der Buchung mit dem Konto.

Verwendet InnerWeb den Zeitpunkt vom Leser?

Ja, die Spezifikation sieht den am Leser erfassten Zeitpunkt sowie die Übertragung in Echtzeit vor, zusammen mit Richtung und Ereigniskennung.

Was passiert, wenn der Firmenname unterschiedlich geschrieben wird?

Das System legt für jede Schreibweise eine eigene Firma an. Den Namen sollte man am besten aus einer einzigen Stammdatenliste im Zutrittssystem übernehmen.

Sind Sie Integrator der Zutrittskontrolle?

Kontaktieren Sie uns. Wir stellen Ihnen die Spezifikation des Kartenbuchungs-Webhooks zur Verfügung und legen mit Ihnen den Umfang der Felder für Ihr System fest.

Sprechen wir