a) CR-Prozess für FINE-SSTs

1: I) Änderungsprozess für FINE-SSTs
2: II) Versionierungskonzept FINE-SSTs
3: III) Change-Log-Beispiel

1 - I) Änderungsprozess für FINE-SSTs

1. Präambel

Änderungen an SST‘s werden durch fachliche Prozessanforderungsänderungen getrieben
D.h. um SST-Änderungen herbeizuführen müssen die fachlichen ChangeRequests genehmigt werden
Der FINE-Interface-Owner ist der verantwortliche Ansprechpartner für eine konkrete SST und für die Kommunikation mit allen SST-Partnern

Eine Änderung an einer SST, die bereits veröffentlicht ist, ist immer mit einer neun Version verbunden

2. IT-technische Doku von Change-Prozessen an SST‘s

Interface-Owner erhält die freigegebenen Anforderungen zur Änderung einer SST durch Fachabteilung, Producer, Consumer oder andere (Bsp. Security)
Interface-Owner erstellt eine neue Version der Dokumentation der betroffenen SST
Neue SST-Version wird mit den betroffenen SST-Partnern (Producer/Consumer) abgestimmt
Im Ergebnis der Abstimmung wird die neue Version freigegeben und deren zeitliche Bereitstellung je Umgebungen definiert
Der Interface-Owner dokumentiert den Stand der Umsetzung im Change-Log , dieses ist Bestandteil der FINE-SST-Doku

2.1. Aspekte

Minor-Änderungen an SSTs sind inhaltlich nicht abzustimmen, hier werden nur die Rollout-Termine auf den diversen Umgebungen veröffentlicht
Major-Änderungen
Definition dazu: Link zur FINE-Doku

3. Ablaufdiagramm Änderungsprozess

AG:    Auftraggeber
Owner: FINE Interface Owner
Approver:
   Minor-Changes:
        Fachliche Freigabe:  durch Auftraggeber
        Technische Freigabe: durch IntegrationLayer (ThomasGrusser oder Bernd Ledig)
                             (beinhaltet Prüfung der Abwärtskompatibilität)
   Major-Changes:
        Freigabe erfolgt durch ein Gremium - Zusammensetzung wird durch Auftraggeber bestimmt
                             (vermutlich TN's vom Fachbereich und beteiligten Systemen)
Partner: Producer / Consumer / Business

2 - II) Versionierungskonzept FINE-SSTs

1. Präambel

Jede FINE-Schnittstelle unterliegt einem Versionierungskonzept und unterscheidet dabei zwischen Major und Minor Upgrades. Minor Upgrades sind immer rückwärtskompatibel - Major Upgrades nicht. Dementsprechend gibt es unterschiedliche Regelungen zu beachten, die im folgenden beschrieben sind.

2. Minor Upgrades

Minor Upgrades sind immer rückwärtskompatibel, ohne dass alle SST-Partner ihre Artefakte neu generieren müssen. Ihr Sinn liegt darin, eine leichte Erweiterbarkeit zu gewährleisten ohne aufwändige Abstimmungen mit allen SST-Partnern im Netzwerk durchführen zu müssen. Gleichzeitig müssen unnötige Störungen vermieden werden. Nachrichten mit einer neuen Minor Version können in den vorhandenen Queues/Endpunkten versendet werden, ohne dass ein Empfänger Probleme bekommt (bzw. bekommen darf). Es bewahrt aber niemanden davor, Minor Upgrades gut zu durchdenken und eventuelle Auswirkungen mit anderen SST-Partnern abzusprechen.

Beispiele: optionales Feld hinzufügen, ENUM erweitern

Technische Aspekte: Geschäftsobjekte neuerer Minor Versionen werden in den gleichen Topics bzw. gleichen REST-Endpunkten verteilt wie die vorige Version. Ein Minor Upgrade darf dennoch nicht zu einem Validierungsfehler führen.

Ein SST-Anbieter muss sich für eine Version der Verteilung der JSON-Schema-Versionen entscheiden und diese umsetzen: 1. Kafka: Schema-Registry ist bei Kafka inklusive muss auf “rückwärtskompatibel” gesetzt werden Eine Version ist eine bei 1 beginnende Zahl, die hochgezählt wird Jeder Empfänger benötigt einen API-Key für den Abruf des Schemas Die Info über die Minor-Version steht pro Message im Kafka-Header 2. REST: spezielle URL bietet Abruf des Schemas muss durch Sender bereitgestellt werden

Fachliche Aspekte/Anwendungs-Logik

Grund-Philosophie: “Wer nicht betroffen ist, den darf ein Minor Upgrade nicht stören”. Wenn ein bisher unerwarteter Wert übertragen wird, hat ein empfangendes System folgende Möglichkeiten:

Bei “Durchreichungs-Logik”: einfach weiterleiten
Bei Logik, die Entscheidungen trifft: Fehler in SST zurückmelden (out of scope im Versionierungskonzept, noch nicht geklärt)

Perspektiven Sender vs. Empfänger

Sender bzw. Owner: kann ein Upgrade selbständig planen informiert die Empfänger (s.u. Organisation) muss keine alten Versionen unterstützen
Empfänger bzw. Nicht-Owner: muss mit unerwarteten Minor-Upgrades rechnen muss damit rechnen, dass es nicht jeder Sender zeitgleich das Upgrade durchführt. Das bedeutet, dass es mehrere Minor Versionen des gleichen Geschäftsobjekt im Netzwerk geben kann.

Organisatorische Regelungen/Spielregeln

Der Verursacher eines Minor-Upgrades muss die Information darüber verteilen.

mindestens 1 Tag bei trivialen Änderungen (Voraussetzung: die automatische Verteilung der Versionen ist gelöst, s.o.)
ansonsten Projektkontext beachten
grundsätzlich immer “Flash” beachten!
ein Upgrade anderer Sender wird innerhalb von 3 Monaten erwartet

Problematik: Sender, welche nicht schritthalten senden veraltete Minor-Versionen, ohne dass es auffällt. Maßnahme: zunächst nur organisatorisch regelmäßig prüfen und Sender zu Upgrade “anregen”. Trägt dies langfristig nicht, ist eine andere organisatorische Maßnahme zu verabschieden - z.B. jährliche zwangsweise “Patch-Days” für alle Teilnehmer.

3. Major Upgrades

Major upgrades sind nicht rückwärtskompatible, strukturelle Änderungen, die mindestens eine technische Änderung benötigen. Diese müssen in separaten Queues/Endpunkten bereit gestellt werden.

Beispiele: Feld entfernen, Feld ändert Bedeutung, Feld wird zu Pflichtfeld, Umstrukturierung im JSON-Schema, ENUM verkleinern

Technische Aspekte

Für neue Versionen von Geschäftsobjekten werden vom Sender unterschiedliche Topics bzw. REST-Endpunkten verwendet. Damit ist sowohl die Bereitstellung der vorigen Versionen gewährleistet als auch ein stufenweises Upgrade ermöglicht.

Kafka: Separate Topics pro Major-Version - Name des Topics enthält Major-Version (Übergangsregelung: Topic ohne Nummer entspricht Major-Version 1)
REST: Mit unterschiedlichen URLs arbeiten oder mit HTTP-Header -→ muss mit besprochen werden, da nur LP + LSAS REST-SST anbieten

Fachliche Aspekte

Eine Änderung von Fachlichkeit bzw. Anwendungs-Logik muss vorher vom Anforderer bzw. Upgrade-Verursacher kommuniziert worden sein. Ansonsten darf ein Upgrade nicht durchgeführt werden.

Perspektive Sender vs. Empfänger

Sender bzw. Owner: muss das OK aller Empfänger abholen muss sich auch mit allen andern Sendern des gleichen Objekttyps abstimmen und einen Upgrade-Plan besprechen, damit alte Major-Versionen zeitnah aus dem Netzwerk verschwinden
Empfänger bzw. Nicht-Owner: Muss sich darauf einstellen, anhand des Senders zu unterscheiden, ob jeweils die neue oder alte Version zu verarbeiten ist (“Demultiplexing”)

Organisatorische Regelungen/Spielregeln

Die vorige Version ist weiterhin bereitzustellen und ein Ablösungsverfahren (im Projektkontext) abzustimmen, welches auf eine möglichst schnelle Ablösung zielen muss.

3 - III) Change-Log-Beispiel

Comment: Beispiel eines Change-Logs im Rahmen der FINE-SST-Doku (dient der gemeinsamen Abstimmung dieses Doku-Teils)

1. Kapitel Stakeholder + Business Context + Informationflow

bleiben unverändert

1.1. Direction FINE to WMS

1.1.1. Schema + Change-Log

Table 1. Change-Log FINE-WMS
Version	Status	Releaseplan	Changes	Used by
2.0	upcoming version	Schema-Definition: offen Dev: offen Test: offen Prod: offen	1. Fehlende Händlerattribute 2. Gefahrstoffangaben aufgenommen 3. bli bla blub	FINE: offen K.MOTION: offen KR: offen COBRA: offen WMS/x: offen FLASH: offen
1.01	current version	Schema-Definition: 04.06.22 Dev: 01.07.22 Test: 10.07.22 Prod: 01.08.22	1. new attribute LogisticsProductID	FINE: 12.05.22 K.MOTION: 10.05.22 KR: nicht verwendet COBRA: nicht verwendet WMS/x: nicht verwendet FLASH: 15.06.22
1.00	deprecated version Abschaltung: 02/23	Schema-Definition: 28.03.22 Dev: 20.05.22 Test: 05.06.22 Prod: 01.07.22	1. SST-Abnahme im Rahmen von BAE WEN1-Feinpflichtenheft	FINE: 01.04.22 K.MOTION: 10.04.22 KR: nicht verwendet COBRA: nicht verwendet WMS/x: nicht verwendet FLASH: 29.04.22

Mögliche Status-Ausprägungen:

upcoming version
current version
deprecated version
die nachfolgenden brauchen wir nicht!?
- Neue Anforderung
- IT-Entwurf vorbereitet (draft)
- IT-Entwurf in Abstimmung
- freigegeben
- abgelehnt
- zurückgestellt

2. FAQs

Wie kann ich Warnungen in Tabellen unterbringen (WARNING: / CAUTION: …)?

<antwort>
Gibt es die Möglichkeit einer Check-Box-Darstellung in asciidoc?

<antwort>