Schritt 1: Ziel und Verantwortungsgrenzen beschreiben
Beginnen Sie die Spezifikation mit einem Satz zum Ziel: Das KD-System sendet bei jeder Kartenbuchung einen HTTP-POST an InnerWeb, und InnerWeb nutzt ihn zur Prüfung von Schulungen, Erlaubnissen und Zeiterfassung. Halten Sie die Grenze klar fest: InnerWeb liefert für diese Integration keine eigenen Leser und tauscht keine Leser aus, die gesamte Arbeit des KD-Anbieters besteht also in der Konfiguration des Ereignisversands. Die ausführliche Integrationsspezifikation liegt als PDF-Dokument vor, das an den externen Anbieter übergeben wird; dieser Leitfaden beschreibt, wie man sie strukturiert.
Schritt 2: Authentifizierung und Sitzung
Der Aufruf benötigt ein Token, das vom Anmeldeendpunkt der API geholt wird. Das Token hat eine begrenzte Gültigkeit und wird durch die Integration automatisch erneuert. Die Spezifikation muss daher vom Anbieter verlangen, dass er das Token mit Reserve erneuert und sich nach einer abgelehnten Autorisierung erneut anmeldet. Halten Sie außerdem fest, dass ein technisches Konto nur für die Integration vorgesehen ist und Passwörter sowie Token nicht in Protokollen gespeichert werden dürfen.
Zahlen aus der Spezifikation
Schritt 3: Felder der Meldung
Nennen Sie die Felder untereinander und kennzeichnen Sie, welche Pflicht sind. Die Meldung umfasst Ereigniszeit, Ort der Buchung und Personendaten: Vorname und Nachname (Pflicht), Kürzel, Firma (Firmenname Pflicht), Nummer der aktiven Karte, Telefon, E-Mail und Sprache. Die Nummer der aktiven Karte ist die Kennung, die die Buchung mit dem Konto der Person verknüpft, und eine Fremdfirma wird anhand des Firmennamens zugeordnet. Verlangen Sie deshalb eine einheitliche Schreibweise der Firmennamen.
- Pflicht: Vorname und Nachname, Firmenname.
- Zuordnungsschlüssel: Nummer der aktiven Karte.
- Ort: Feld actionPlace, das die Standorte der Leser unterscheidet.
- Optional: Kürzel, Telefon, E-Mail, Sprache.
Schritt 4: Anforderungen an Ereignis und Versand
Zwei Anforderungen müssen eindeutig in die Spezifikation. Erstens sendet das KD-System Ereignisse in Echtzeit, mit der vom Leser erfassten Ereigniszeit; nach einem Ausfall der Leitung behalten die Ereignisse ihre ursprüngliche Zeit. Zweitens trägt jedes Ereignis die Richtung (Eintritt oder Austritt) und eine Ereigniskennung, und InnerWeb nimmt sie über den authentifizierten Webhook entgegen. Die Regeln für die Zuordnung von Ein- und Ausgängen sowie für das Verwerfen von Duplikaten werden mit dem KD-Anbieter in der Spezifikation festgelegt und als vereinbarter Leistungsumfang beschrieben.
Ergänzen Sie die Anforderung an Robustheit gegen Ereignisserien und Wiederholungen: In einem Betrieb mit mehreren Agenturen kann das Aufkommen an einem Werktag 2 000 Buchungen überschreiten.
Schritt 5: Buchungsorte und Vorlagen
Bitten Sie den Anbieter um eine Liste der Leser mit den Namen der Buchungsorte in der Form, in der sie in das Feld actionPlace übernommen werden. Ereignisse von einem Ort ohne Vorlage in InnerWeb landen im Protokoll und lösen keinen Schulungsalarm aus. Die Leserliste muss deshalb mit der Konfiguration auf Seiten von InnerWeb abgestimmt sein, bevor die Tests beginnen. Ein fehlender Leser ist die häufigste Ursache für Buchungen, die im Protokoll sichtbar sind, aber keine Wirkung am Tor haben.
Schritt 6: Abnahmetests
Beschreiben Sie Testszenarien statt einer allgemeinen Formulierung über Tests. Mindestens: Buchung einer bekannten Person, Buchung einer unbekannten Person, wiederholte Buchung in kurzem Abstand, Buchung an jedem Leser der Liste, Ablauf des Tokens während des Versands und eine Ereignisserie. Abschlusskriterium: Jedes Szenario hat ein erwartetes Ergebnis auf Seiten von InnerWeb. Denken Sie daran, dass der Webhook allein ohne Zuordnung zu Ein- und Ausgängen keine Zeiterfassung ergibt, nehmen Sie deshalb einen Test der Sichtbarkeit der Buchung im Eintrittsregister auf.
Checkliste
Videomaterial
Häufig gestellte Fragen
Muss der KD-Anbieter Leser austauschen?
Nein. Die Integration ist die Konfiguration des Versands des Buchungsereignisses, InnerWeb liefert und tauscht keine Leser aus.
Warum verlangt die Spezifikation den Versand in Echtzeit?
Damit die Ereigniszeit des Lesers erhalten bleibt, denn ein verzögerter Versand erschwert die Zuordnung von Ein- und Austritten sowie die Kontrolle der Anwesenheit.
Wer legt die Richtung Eintritt und Austritt fest?
Das KD-System übergibt die Richtung in jedem Ereignis, die Regeln für die Zuordnung von Ein- und Austritten werden mit dem KD-Anbieter in der Spezifikation festgelegt.
Quellen
Wir übergeben die Spezifikation an Ihren KD-Anbieter
Wir haben das Integrationsdokument für KD-Anbieter fertig. Vereinbaren Sie ein Gespräch mit dem Team von InnerWeb und schließen Sie die Einführung in einer Iteration ab.
Sprechen wir