Payload von SETs ausdefinieren und den Umgang damit

Warum machen wir das?

Aktuell fehlt es Entwicklern und Verfahrensbetreibern an konkreten Vorgaben, wie mit bestimmten Events umgegangen wird. Zudem ist für kein Event aktuell eine Payload als Schema definiert. Dies trifft insbesondere auf das Reject Event zu. Das führt im n:n Kontext von FIT-Connect zu großen Unklarheiten und Verunsicherung bei Entwicklern und Verfahrensbetreibern, da unklar ist, wie bspw. mit einem Reject Event umgegangen wird oder man sich in der eigenen Software im Umgang damit darauf vorbereitet.

Relevante Links und Bemerkungen

Real World Beispiele für SETs mit konkreten Events und Payloads zur Inspiration:

• https://developers.login.gov/security-events/
• https://openid.net/specs/openid-risc-profile-1_0-ID1.html
• https://openbankinguk.github.io/read-write-api-site2/standards/v3.1.3/resources-and-data-models/event-notifications/event-notifications/

Hinweis: In der Diskussion bei #207 (closed) wurde festgestellt, dass für ein zusätzliches Event bei einen technischen Fehler für den Callback ("nicht erreichbar") sinnvoll sein kann. --> Dieser Bedarf ist in der aktuellen Storyschätzung nicht enthalten.

Akzeptanzkriterien

1. Es sind Payloads für das Submitted, Notify und Reject Event definiert.
2. Die Payload-Schemas sind in Schema.fitko hinterlegt.
3. Event Payloads für Events des Zustelldienstes sind auch im Zustelldienst implementiert.
4. Es existieren technische Beispiele für die Generierung, das Auslesen und die Validierung von Payloads.
5. Es ist erläutert, wie man auf ein Reject Event mit definierten Payload reagiert (Sender) bzw. welche Payload man bei Problemen in der Submission generiert.
6. Für das vom Zustelldienst erstellte "submit"-SET ist Variante 7 aus Integritätssicherung Einreichung umgesetzt.
7. Für das vom Subscriber erstellte "accept"-SET ist Variante 8 aus Integritätssicherung Einreichung umgesetzt.
8. Es ist eine Versionierung von Payloads geklärt.
9. Es gibt eine Liste, wie der Zustelldienst den Payload von Events prüft -> #297 (closed)

Durchführungsplan

• Materialsammlung/Brainstorming im Wiki: https://wiki.fit-connect.fitko.dev/de/Konzeption/event-payload
• Erstellung eines JSON Schemas für die Event Payloads: Repo | Schema
• Dokumentation der Event Payloads: docs!110 (merged) | Branch | Preview
• Die Seite Ereignisprotokoll in mehrere Seiten zerlegen -> https://docs.fitko.de/preview/fit-connect/event-payload/docs/getting-started/event-log/overview
• Implementierung der Event Payloads im Zustelldienst: zustelldienst!56
  • $schema in allen SETs
  • authenticationTags in submit-submission
  • notifyType in notify-submission
• Erstellung von Java Code, der Events schreibt, liest und prüft
• Doku zu Event Payloads erweitern
• Neuen Fehler content-invalid dokumentieren
• Validierungs-Liste abstimmen
• Doku für Subscriber basierend auf der Validierungs-Liste erstellen
• Doku für Sender basierend auf der Validierungs-Liste erstellen
• Test schreiben, der prüft, dass die Entschlüsselung den Authentication-Tag prüft: zustelldienst!59

Ergebnis des PO Review 2022-01-28

• SET-payload-Schema am v0.1.0 versionieren
  • Im Zustelldienst als gültiges Schema registrieren
  • Doku: Events ohne Payload sind weiterhin erlaubt, dafür muss das $schema weggelassen werden
  • Doku: Version 0.1.0 ist aktuell, die Version 1.0.0 wird dann die Rückkanal-Events enthalten
• Empfangsbestätigung oder Zurückweisung
  • Empfehlung: Kommunikation an den Nutzer: Auf dem Versandweg, eingegangen, unzustellbar. Keine technischen Details.
  • Bei Reject: Entscheidungsbau mit Neuversand, neu verschlüsseln und neu ausfüllen
• Einreichung überprüfen
  • Einträge "Abbruch empfohlen? ja" entfernen
  • Einträge "Abbruch empfohlen? nein, ..." in einen Satz oberhalb umwandeln
  • Fehler als Code-Snippets wie in der anderen Seite
• Das Problem decryption-failed in encryption-issue umbenennen
  • ... und dokumentieren, dass damit auch ein falscher oder abgelaufener Schlüssel bemängelt werden kann.
• Fehlercode für Automatischer Reject durch Zustelldienst (timeout) ergänzen