Versionierung von Meldungen
Einleitung
Die Meldungen welche mit dem BAZG austauscht werden, können sich über die Zeit verändern. Das führt dazu, dass mehrere Versionen einer Meldung entstehen werden. Während der Migration wird es unvermeidlich sein, dass die betiligten Systeme unterschiedliche Versionen der Meldungen parallel verarbeiten müssen. Um einen geordneten Übergang von einer alten auf die neue Schema Version zu Gewährleisten, sind folgende Punkte zu definieren:
Versionierung der XML Schema
Deklaration der Schema Version auf der Instanz
Migrationsprozess
Lifecycle
Im Rahmen des Entstehungsprozesses einer neuen Version einer Meldung entstehen zeitlich verzögert verschiedene Artefakte. D.h. üblicherweise stehen diese Artefakte pro Version nicht gleichzeitig zur Verfügung!
Artefakt | Beschreibung |
|---|---|
fachliche Spezifikation im Excel | Mehrere Anpassungen einer Meldung werden in einer neuen Version gebündelt. Die Spezifikation erfolgt pro Meldung in einem Excel. Zur besseren Visualisierung der Abhängigkeiten zwischen den Datengruppen wird zudem ein Diagramm erstellt. |
technische Spezifikation im xsd-Format | Auf Basis der fachlichen Spezifikation im Excel erfolgt die technische Spezifikation. Das Ergebnis davon ist eine xsd-Datei. |
reale Umsetzung und Bereitstellung API Testsystem | Anhand der fachlichen und technischen Spezifikation erfolgt die effektive Umsetzung. Das Ergebnis ist die Bereitstellung eines APIs auf dem Testsystem. |
Beispiel-Datei im xml-Format | Um die Einstiegshürde für einen ersten einfachen Test zu senken, stellt das BAZG pro Meldung eine Beispiel-Datei im xml-Format zur Verfügung. Diese ist rein informativ und muss vor dem Test durch das Gegenüber auf dessen Gegebenheiten angepasst werden. |
Versionierung der XML Schema
Das BAZG hält sich an die Best Practice der E-Governement Standards: eCH-0018 XML Best Practices (siehe Kapitel 3.10)
Daher gelten für die Versionierung von XML-Schemas folgende Regeln:
Zwischen der Namespace-Version und der Schema-Version muss eine 1:1 Beziehung bestehen. D.h. der Namespace-Name identifiziert das Schema eindeutig.
Änderungen an der Syntax und redaktionelle Anpassungen, welche die Semantik ändern, führen zu einer neuen Version und damit zu einem neuen Namespacenamen.
Bsp.: (../eCH-0018/1) wird zu (../eCH-0018/2)Rein redaktionelle Anpassungen ohne Konsequenz auf die Semantik (z.B. die Korrektur eines Tippfehlers in einem Kommentar) führen im Namespace zu
keiner neuen Version. Diese werden über das Publikationsdatum und dem ChangeLog, kenntlich gemacht.
Beispiel
<?xml version="1.0" encoding="utf-8"?>
<xs:schema version="1" ... xmlns="http://passar.bazg.admin.ch/NT015/1" targetNamespace="http://passar.bazg.admin.ch/NT015/1" ...
Kein Semantic Versioning
Das Semantic Versioning hat sich in vielen Bereichen der IT durchgesetzt: <Major>.<Minor>.<Patch> (Bsp. 2.4.1).
Die semantische Bedeutung der drei Versionsnummern ist:
Major: Inkompatible Veränderung, Clients müssen angepasst werden
Minor: Rückwärtskompatible Erweiterung der Funktionalität, Anpassung Client nicht zwingend
Patch: Korrektur, kein Impact auf Clients
Da Rückwärtskompatible Erweiterungen mit XML nur schlecht unterstützt sind, hält sich das BAZG auch hier an den E-Governement Standards: eCH-0018 XML Best Practices und verwendet kein Semantic Versioning.
Änderungen an der Syntax oder Sematik der Meldung führen daher immer zu einer neuen Major Version.
Naming Convention für Schema Dateien
Die Version des Schema ist im Namen der Schemadatei erkennbar. Das impliziert, dass pro Schemaversion eine unterschiedliche XSD Datei existiert.
Pattern: <MessageName>_v<version>.xsd
Beispiel: NT015_v1.xsd
Deklaration der Schemaversion auf der Meldungsinstanz
Damit das empfangende System weiss, um welche Version des Meldungstyp es sich handelt, muss jede Meldungsinstanz die verwendete Schemaversion deklarieren.
XML Dokumente müssen ausschliesslich via Namespace-Namen den Bezug zur Schemaversion herstellen.
XML-Dokumente sollen keinen Bezug zum Ausgabedatum des Schemas herstellen.
Beispiel
<?xml version="1.0" encoding="UTF-8"?>
<n1:NT015 xmlns:n1="http://passar.bazg.admin.ch/NT015/1”>
Migrationsprozess
Im Umfeld von B2B Schnittstellen ist ein harter Wechsel auf einen bestimmten Termin in der Regel nicht realisierbar. Gründe dafür sind unter anderem folgende:
Viele Parteien müssten gleichzeitig einen Änderung Produktiv setzten
Langlaufende, alte Prozessinstanzen können potentiell die neue Meldung gar nicht produzieren, weil für die alte Prozessinstanz gar nicht alle erforderlichen Daten für die neue Messageversion existieren
Daher müssen die Systeme während der Migration beide Messageversionen parallel unterstützen. Dazu wird anhand des "Expand and Contract" Pattern vorgegangen, um die nicht Rückwärtskompatiblen Änderungen in einer sicheren Art und Weise in einem Produktiven System einzuführen. Dazu werden die 3 Phasen Expand, Migrate und Contract durchlaufen, welche in nachstehender Tabelle beschreiben sind.
Phase | Voraussetzung für die Phase | Ziel der Phase | Sender | Empfänger |
|---|---|---|---|---|
1) Expand | Die neue Version des Schema ist definiert | Die Empfänger können mit der alten und neuen Schema Version umgehen. | Die Sender versenden die Meldungen mit der alten (bestehenden) Version des Schemas. | Die Empfänger werden erweiteret, damit diese Meldungen mit der alten (bestehenden) Version des Schemas, wie auch Meldungen mit der neuen Version des Schemas verarbeiten werden können. (Unterstützung mehrere Schema Versionen parallel) |
2) Migrate | Alle Empfänger können die alte (bisherige) und die neue Version der Meldung verarbeiten. | Umstellung der Sender auf die neue Version
| Die Sender versenden die Meldungen mit der neuen Version des Schemas. | Die Empfänger verarbeiten weiterhin Meldungen mit der alten und neuen Schema Version (Unterstützung mehrere Schema Versionen parallel) |
3) Contract | Meldungen mit der alten Schema Version werden nicht mehr publiziert.
| Rückbau der alten Schema Version. | Die Sender versenden die Meldungen weiterhin mit der neuen Version des Schemas. | Die Empfänger können nur noch Meldungen mit der neuen Schema Version verarbeiten. |
Hinweise:
Dieses Vorgehen ist unabhängig davon, ob das BAZG Sender oder Empfänger einer Meldung ist
Das BAZG wird jeweils für die verschiedenen Phasen entsprechende Fristen definieren
Q&A