Skip to content

[.NET SDK] SDK Anpassungen ZSD SSP Routing 2.X

Warum

Als SDK-Team möchten wir sicherstellen, dass wir weiterhin kompatibel mit den Schnittstellen der Teams Zustelldienst (ZSD), Routing und Self-Service Portal (SSP) bleiben. Mit dem geplanten Major Releasewechsel stehen einige signifikante Änderungen. Ohne Anpassungen auf SDK-Seite drohen Integrationsprobleme, inkonsistente Datenverarbeitung und fehlende Unterstützung neuer Features.

Ziel

Als Entwickler:in im SDK-Team möchte ich alle relevanten API-Änderungen aus dem Releasewechsel von ZSD Routing und SSP im SDK nachvollziehen, sodass Anwendungen, die das SDK nutzen, vollständig kompatibel mit den neuen Schnittstellen bleiben, deprecated Felder nicht mehr verwenden und neue Validierungslogiken korrekt abbilden. Soweit möglich / sinnvoll sollte angestrebt werden, in den SDKs möglichst wenige breaking changes einzubauen.

Links, Hinweise, Bemerkungen

relevante Stories

  1. Analyse und Kategorisierung aller Breaking Changes aus dem ZSD/SSP Release (https://git.fitko.de/fit-connect/planning/-/issues/3304, #tbdssp, #tbdrouting)
  2. ZSD https://git.fitko.de/fit-connect/planning/-/issues/3304:
    1. Umsetzung Änderung #3319 – Öffentlicher Zugriff /destinations/{id} + Entfernen polymorpher Payloads (SDK: wenn überhaupt keine Änderungen in den SDKs- Model bleibt gleich)
    2. Anpassung Metadatensatz #3320 – Vorbereitung Modularisierung, Deprecation veralteter Felder (SDK: kleine Änderungen, aber ggf. Breaking Change bei Änderung des Models)
    3. Webhooks #3323 (#573) – Entfernen deprecated Felder, optionales submissionIds
    4. Implementierung #310 – Status FORWARDED entfernen
    5. jwk.use entfernen (#3325)
    6. callback aus PUT/GET entfernen (#3326)
    7. Entfernen replyChannels (#3328)
    8. Umbenennung services/serviceType → publicService(Type) (#499) (SDK: kleine Änderungen, aber ggf. Breaking Change bei Änderung des Models)
    9. Verpflichtend encryptedData validieren (#322)
    10. Optimierung Attachment Handling (#3331)
  3. Routing:
    1. Umstellung auf Routing 2.0 - https://git.fitko.de/fit-connect/planning/-/issues/3293#note_233649
  4. SSP:
    1. Keine SDK-relevante SSP Änderungen

Anmerkung: bei den durchgestrichene Stories bewertet Team SDK, dass hier keine Änderungen notwendig sind

Akzeptanzkriterien

  1. Alle Änderungen aus dem ZSD-Release sind im SDK korrekt nachvollzogen
    1. Submissions ohne Fachdaten link
      • nicht relevant für JAVA, auch wenn Fachdaten als Anhang übermitteln werden wird ein leeres Bytearray übergeben
      • @PEDRO_MARQUES wahrscheinlich gleich in .NET, aber bitte prüfen
    2. Webhooks - auf submissions.submissionId zurückgreifen. link
      • Anpassung der Callback-Objekte notwendig
    3. Das forward-submission-Event link
      • Über die SDKs kann der Nutzer das Event nicht setzen. Daher für uns keine Änderung notwendig. Aus der Liste der zulässigen Events müssen wir es rausnehmen, sobald v1 auch nicht mehr unterstützt wird.
    4. Metadaten link
      • nach dem Update sollte der OD die Möglichkeit behalten abhängig vom Empfänger 1.X oder 2.X zu versenden. Für FV wahrscheinlich nicht notwendig
      • Default sollte immer die neueste Version der Metadaten sein, jedoch müssen wir mit dem Update eine Konfiguration einbauen um mit einer spezifischen bzw. der letzten 1.X Version des Metadatenschemas versenden zu können. Ebenfalls gilt das für den Empfänger, falls ein OD nur 1.X Metadatenschemas versenden kann.
    5. Basis-URLs und Pfade link
    6. Verbot der Verwendung des JWE "zip" Headers link
      • NIMBUS Update
    7. Umbenennung von serviceType und services link
      • auch vereinheitlichen, falls bei uns diese Namen auch unterschiedlich benannt werden
    8. replyChannels auf Wurzelebene link
      • eigentlich bei uns bereits umgesetzt, aber sollten wir noch abschließend prüfen
    9. Status-Codes und Header link
      • speziell die Integrationstests könnten hier in Fehler laufen
    10. Abruf von Destinations über die Submission-API link
    11. Das jwk.use-Feld link
      • speziell im Kontext der JS.SDKs müssen wir das genauer prüfen
    12. Das callback-Feld link
  2. Alle Änderungen aus dem SSP-Release sind im SDK korrekt nachvollzogen
    • keine SDK relevanten Änderungen
  3. Alle Änderungen aus dem Routing-Release sind im SDK korrekt nachvollzogen
    1. Entfernung von destinationParameters aus der Routing-API link
  4. Bereinigung von deprecated Feldern -> entfernen
  5. Breaking Changes der META-SDKs einbauen, bzw. Vorausdenken was noch umgebaut wird
  6. Review & Test aller Änderungen + API-Konformität im Integrationstest verifizieren
  7. Das SDK funktioniert in einer vollständigen E2E-Teststrecke gegen die neuen APIs
  8. Anpassung SDK-Dokumentation, Migrationsanleitung(auch die Migrationsanleitung von 1 auf 2 mit veröffentlichen), Releasevorbereitung
  9. ...
  10. Definition of Done wurde überprüft.

Mögliche Folgeaktivitäten

Offene Fragen

Edited by Wojciech Gdaniec