Was die Personen-API zurückgibt
Die Personen-API liefert dem Portal drei Arten von Informationen: die Liste der Schulungen mit Status, einen persönlichen Link zur Schulung und den Zutrittsausweis. Jede davon betrifft eine im Werk identifizierte Person, sodass das Portal keine eigene Kopie des Berechtigungsstands führen muss.
Diese Lösung klärt die Verantwortung: Die Quelle der Wahrheit über Schulungen und Zutrittsausweis ist das System des Werks, das Portal ist eine Ansicht. Eine Statusänderung im Werk ist beim nächsten Abruf im Portal sichtbar.
Welche Schulungsstatus werden zurückgegeben?
Vier: todo, done, expiring und expired. Der Status todo bedeutet eine noch auszuführende Schulung, done eine bestandene Schulung, expiring eine bestandene, aber innerhalb von 30 Tagen ablaufende Schulung und expired eine Schulung, deren Gültigkeit abgelaufen ist.
Der Status expiring erlaubt es dem Portal, rechtzeitig eine Warnung anzuzeigen, bevor die Person die Möglichkeit verliert, das Werksgelände zu betreten.
Was ist der persönliche Link zur Schulung?
Es ist eine Adresse, die die API für eine bestimmte Person und eine bestimmte Schulung ausstellt. Das Portal kann sie als Schaltfläche anzeigen, und die Person absolviert die Schulung, ohne sich manuell in ein separates System einzuloggen.
Wie die API abgesichert ist
Alle Aufrufe der Personen-API erfordern ein Maschinen-Token. Das Token wird auf Seiten des Servers des Portals aufbewahrt, und im Panel des Werks gelangen die Schlüssel nicht in den Browser: Die Einstellungen der Integration sind nur lesbar.
Für den Integrator gilt daher eine einfache Regel: Die Aufrufe der API führt das Backend des Portals aus, niemals Code, der im Browser des Benutzers läuft. Ein Token im Code einer Seite wäre ein offengelegtes Token.
Was geschieht, wenn das Token falsch ist?
Der Aufruf wird abgewiesen. In der analogen API für Zugangsanträge liefert ein fehlendes oder falsches Token die Antwort 401. Der Integrator sollte 401 als Hinweis verstehen, die Konfiguration zu prüfen, und nicht in einer Schleife wiederholen.
Darf das Token zu einem gewöhnlichen Konto eines Beschäftigten gehören?
Nein. Das Maschinen-Token ist für die Integration bestimmt, hat einen begrenzten Umfang, und seine Verwendung lässt sich im Austauschprotokoll von menschlichen Handlungen unterscheiden. Empfehlungen für ein technisches Konto beschreiben wir in einem gesonderten Material zu den Berechtigungen.
Antwortcodes bei Zugangsanträgen
Fehler und Randfälle
Ein im System gelöschtes Konto liefert die Antwort 404. Das Portal sollte 404 als Information verstehen, dass die Person im Werk nicht existiert, und die Verknüpfung auf eigener Seite entfernen oder kennzeichnen, anstatt veraltete Daten anzuzeigen.
Im Austauschprotokoll auf Seiten des Werks werden Ereignisse mit Richtung, Ergebnis und HTTP-Code gespeichert, und das Schreiben ins Protokoll unterbricht nie die Bearbeitung einer Anfrage. Bei der Fehlersuche kann der Integrator also seine eigenen Logs mit dem Protokoll des Werks vergleichen.
Wie unterscheide ich eine Person ohne Schulungen von einer gelöschten Person?
Eine Person ohne Schulungen erhält eine korrekte Antwort mit leerer oder kurzer Liste, eine gelöschte Person erhält 404. So verwechselt das Portal fehlende Daten nicht mit einem fehlenden Konto.
Was ist mit Zugangsanträgen, die das Portal stellt?
Ein Zugangsantrag kommt als eigener Aufruf POST mit dem Maschinen-Token. Die Antwort 201 bedeutet einen neuen Antrag, 200 die Wiederholung derselben Anfrage-ID, 400 fehlerhafte Daten und 401 ein fehlendes oder falsches Token. Daten zu Berechtigungen, Schulungen und Untersuchungen werden nur angenommen, wenn der Umfang der Einwilligung der Person sie umfasst.
Rolle des Administrators und des Bedieners
Das Panel der Integration im Modul Berechtigungen zeigt den Verbindungsstatus, die Anzahl aktiver Zutrittsausweise, verknüpfter Konten, offener Anträge und Fehler der letzten 7 Tage sowie das Austauschprotokoll. Das Panel sehen der Administrator und der Mitarbeiter für Arbeitssicherheit.
Annahme, Ablehnung und erneute Zustellung von Entscheidungen bei Zugangsanträgen aus dem Portal ist ausschließlich der Rolle des Dienstadministrators vorbehalten. Diese Trennung soll verhindern, dass eine Person mit Leserechten die Entscheidungen über den Zugang ändert.
Was geschieht mit einer Entscheidung, die nicht zugestellt werden konnte?
Eine nicht zugestellte Entscheidung bleibt in der Zeile mit der Fehlerbeschreibung und kann im Panel erneut gesendet werden. Der Bediener muss den Integrator also nicht um die manuelle Wiederherstellung der Anfrage bitten.
Videomaterial
Häufig gestellte Fragen
Muss das Portal eine Kopie der Schulungen speichern?
Nein. Die Quelle des Stands ist das Werk, das Portal ruft ihn bei einer Anfrage ab. Eine eigene Kopie wird nur für den Zwischenspeicher benötigt.
Wie oft soll die Personen-API abgefragt werden?
Beim Aufruf der Seite des Portals durch die Person, nicht in einer Schleife im Hintergrund. Der Status expiring hat ein Fenster von 30 Tagen, daher reicht eine Aktualisierung pro Besuch.
Was tun, wenn das Portal für eine bekannte Person die Antwort 404 erhält?
Das Konto wurde im Werk gelöscht. Kennzeichnen Sie die Verknüpfung als veraltet und verweisen Sie die Person auf einen erneuten Zugangsantrag.
Gibt die API Daten zurück, in deren Verarbeitung die Person nicht eingewilligt hat?
Daten zu Berechtigungen, Schulungen und Untersuchungen werden in Anträgen nur angenommen, wenn der Umfang der Einwilligung sie umfasst.
Binden Sie das Portal an das Werk an
Wir zeigen die Abfrage der Personen-API an Testdaten und besprechen, wie das Portal für Auftragnehmer die Schulungsstatus anzeigen soll. Vereinbaren Sie ein Gespräch mit InnerWeb.
Sprechen wir