Migration organisationsspezifisches V-Modell 1.3 nach 1.4

Heute wird es etwas technischer. Wer eine organisationsspezifische Anpassung des V-Modell XT 1.3 vorgenommen hat, kann möglicherweise eine Hilfe für die Migration nach Version 1.4 gebrauchen. Für die Migration der XML-Dateien (Modell und Mustertexte) ist dieser Post gedacht.

Was wird gebraucht?

• Alle Tools, die der Prozessingenieur normalerweise einsetzt (VMXT Editor, OpenOffice/LibreOffice, etc.),
• das v1.3-to-v1.4 Migrationsskript,
• Ein XSL 2.0-fähiger Interpreter (ich habe saxon9-1-0-7j verwendet, aber mit neueren Versionen wird es wohl auch gehen; SAXON auf Sourceforge),
• ein Texteditor (sehr empfohlen: Notepad++),
• Windows (das Skript liegt nur als Batch-Datei für Windows vor),
• oder ein anderes Betriebssystem (dann muss aber das Skript entsprechend angepasst werden),
• sowie das schrittweise Befolgen der unten stehenden Anleitung!

Warum ist eine Migration notwendig?

Mit Release 1.4 wurden einige Metamodellrelevante Änderungen vorgenommen, die eine Migration notwendig machen. Einige Prozessingenieure haben bereits die folgende leidvolle Erfahrung gemacht: das 1.3er Modell lässt sich nicht mit dem 1.4er Metamodell im Editor öffnen.
Welche Änderungen sind nun daran schuld?

• Die schuldigste Änderung ist das Auslagern des XML-Elements "BeispielProduktgestaltung" aus Themen und Produkten hin in die Mustertexte. D.h. diese "Beispielhafte Produktgestaltung" ist nicht mehr Bestandteil der Prozessdokumentation, sondern wird seit Version 1.4 als Mustertexte direkt für die Produktvorlage angeboten.
  Warum? Dort sind diese Beispiele näher am Anwender. Wenn es nun in einem 1.3er Modell noch solche Elemente gibt, dann weigert sich der VMXT Editor, dieses Modell mit dem 1.4er Metamodell zu öffnen, denn dieses kennt diese Elemente nicht mehr. Wer kann es dem Editor verübeln?
• Eine weitere Änderung ist das Hinzukommen des Knotens "Rollenkategorie" als Unterknoten von "Rolle". Dieser Knoten kann die Werte "Organisationsrolle" und "Projektrolle" annehmen. Das ist aber kein Hemmnis für den Editor. Dieser öffnet das Modell einfach und lässt diese nicht vorhandenen Knoten einfach weiterhin weg.
• Externe Kopiervorlagen unterstützen nun für das Attribut "Standardauswahl" nicht mehr nur die Werte "Ja" und "Nein", sondern auch den Wert "Verpflichtend". Der Projektassistent 1.4 gestattet es Ihnen nicht mehr, solche Kopiervorlagen abzuwählen.
  Für die Migration ist das nicht kriegsentscheidend, aber vielleicht hilft diese Information Ihnen ja weiter.
• Last but not least: Durch die Aufteilung aller Rollen in die Kategorien "Projektrolle" und "Organisationsrolle" wurde auch der Rollenindex überarbeitet. Auch dies ist kein Grund für den Editor, die Segel zu streichen, aber wer hier nicht aufpasst, der könnte einen (marginalem, aber merklichen) Datenverlust bekommen. Ein "Kapitel" kann nämlich das Attribut "GenerierterInhalt" in Version 1.3 mit dem Wert "Index:Rollen" belegen. Die Exporttemplates 1.3 interpretieren diesen Wert so, dass in diesem Kapitel eine Auflistung aller Rollen in die Dokumentation generiert werden soll. Mit Aufteilung der Rollenkategorien gibt es diesen Wert nicht mehr. Statt dessen heißt es nun "Index:Projektrollen" (mit dem alle Projektrollen aufgelistet werden) und "Index:Organisationsrollen" (mit dem...). Wer also ein Interesse an einem Rollenindex hat, sollte hier sorgfältig prüfen. (Details unten)

Anleitung

• Migrationsskript herunterladen und entpacken.
• Das zu migrierende Modell (i.d.R. V-Modell-XT.xml) in dasselbe Verzeichnis zum Skript migrate_v1.3-to-v1.4.xsl legen. Dasselbe machen wir mit den Mustertexten (i.d.R. V-Modell-XT-Mustertexte.xml). Nennen Sie Ihre V-Modell-XML V-Modell-XT_v1.3.xml und Ihre Mustertexte-XML V-Modell-XT-Mustertexte_v1.3.xml. Tun Sie das wirklich, das wird Ihnen die folgenden Schritte einfacher machen und Fehlerquellen ausschließen. Sie könnten natürlich auch die Namen der Input-Dateien im Batch-File und im XSL-File anpassen, aber sagen Sie hinterher nicht, ich hätte Sie nicht gewarnt. ;)
• Wegen des Wegfalls von "Index:Rollen": Das Migrationsskript übernimmt hier die Arbeit, aber je nachdem, wie Ihre organisationsspezifische Anpassung aussieht, könnte es sein, dass das Skript den zu migrierenden Knoten nicht finden kann. Öffnen Sie Ihr V-Modell-XML in einem Texteditor und suchen Sie Zeilen mit dem Text "Index:Rollen". Sehr wahrscheinlich ist das nur in dem Kapitel mit der ID 142aafbe855c566 der Fall. Dieses trägt den Namen "Rollenindex". Wenn dies so ist (sehr wahrscheinlich), dann können Sie mit den nächsten Schritt weitermachen. Wenn Sie gar keinen Rollenindex haben, dann können Sie auch weitermachen.
  Wenn die ID aber in Ihrem Fall nicht übereinstimmt, müssen Sie hier ggf. Anpassungen vornehmen. Das Skript sucht nach dem Knoten mit genannter ID und transformiert ihn. Wenn Ihr Rollenindex eine andere ID hat, dann würde ich empfehlen, im Skript migrate_v1.3-to-v1.4.xsl in Zeile 66 die ID anzupassen:
  
  <xsl:template match="Kapitel[@id='142aafbe855c566']" mode="vmxt_xml">
   
• Ggf. Pfad zum XSL-Interpreter anpassen. Hierfür müssen Sie ggf. erst einen XSL-Interpreter heranschaffen. Im Skript migrate_v1.3-to-v1.4.bat ist die Voreinstellung (Zeile 4):
  
  SET XSL_INTERPRETER=java -jar %PFAD%\saxon9-1-0-7j\saxon9.jar
  
  Die Variable XSL_INTERPRETER enthält einen Java-Aufruf von SAXON und geht dabei davon aus, dass dieses im Verzeichnis des Aufrufs des Batch-Skriptes im Ordner saxon9-1-0-7j liegt. Klar, dass das angepasst werden muss, falls Sie einen anderen XSL-Interpreter benutzen oder dieser woanders liegt.
  Wichtig ist auch, dass Sie auf die Parametrisierung in den Zeilen 6 und 7 achten, sofern Sie einen anderen Interpreter (ggf. auch eine andere Version!) als SAXON 9.1.0.7j benutzen. SAXON erwartet die Angabe der Output-Datei nach dem Parameter "-o". Bei anderen Interpretern sieht das ggf. anders aus!
• Modellmigration durch Aufruf von migrate-v1.3-to-v1.4.bat ausführen lassen. Was passiert jetzt? Es werden zwei neue Dateien erzeugt, eine für die V-Modell-XML (V-Modell-XT.xml), eine für die Mustertexte-XML (V-Modell-XT-Mustertexte.xml). Aus der V-Modell-XML werden alle Elemente "BeispielProduktgestaltung" gelöscht. In die Mustertexte-XML werden diese Beispieltexte jeweils als Mustertext für das jeweilige Thema ergänzt. Diese Beispieltexte werden in der Mustergruppe "Beispielhafte Produktgestaltungen" abgelegt.
• Beide Erzeugnisse im V-Modell XT Editor öffnen, anschließend direkt speichern (wahrscheinlich müssen Sie zunächst irgendwo eine kleine Änderung vornehmen, die Sie direkt wieder rückgängig machen können). Hierzu können Sie die beiden erzeugten Dateien bequem in den Ordner Metamodell_v1.4 schieben. Falls Sie im Vorfeld meinen Vorschlag zur Dateibenennung nicht beachtet haben, könnte es sein, dass Sie ihre V-Modell-XML nun V-Modell-XT.xml nennen müssen, sonst könnte es sein, dass der Editor meckert, weil der Name der Datei in der Mustertexte-XML fest verdrahtet ist.
• Jetzt sollte sich Ihr Modell im V-Modell XT Editor öffnen lassen. Möglicherweise (wenn Sie mit einem Erweiterungsmodell arbeiten) erhalten Sie folgende Fehlermeldung: "An include failed and there where no fallback element." In diesem Fall könnte es sein, dass in der Erweiterungsmodell-XML der Pfad zum Referenzmodell nicht richtig gesetzt ist. Schauen Sie in der XML-Datei in eine der letzten Zeilen:
  
  <xi:include href="../Modell/V-Modell-XT.xml"/>
  
  Die hier angegebene Datei muss einen gültigen relativen Pfad zur Referenzmodell-XML darstellen.
• Damit die migrierten Rollen auch im Rollenindex angezeigt werden, müssen Sie allen Rollen in Ihrem Modell nun noch eine Rollenkategorie zuteilen. Orientieren können Sie sich am V-Modell XT 1.4, dort sind natürlich alle Rollen in Kategorien getrennt aufgeführt.
• Falls Sie keine Beispieltexte in Ihrem Modell haben, dann können Sie in der Mustertexte-XML die Mustergruppe "Beispielhafte Produktgestaltung" löschen.
• Das war die Pflicht um die XML-Datei herum. Zur Kür gehört jetzt natürlich auch die Anpassung aller anderen Assets des V-Modell XT, d.h. Bilder, Exporttemplates, etc. Hierfür habe ich keine Anleitung parat. Orientieren Sie sich an den Release Notes. Wenn Sie nicht alle Exporttemplates aus Version 1.4 komplett übernehmen sondern sich entscheiden, die Vorlage Kapitel-5_BeispielProduktgestaltung.odt händisch aus Ihren Exporttemplates zu entfernen (wird ja nicht mehr gebraucht), dann behalten Sie bitte im Hinterkopf, dass möglicherweise in anderen Templates darauf verwiesen wird. Diese Verweise müssen Sie natürlich auch entfernen, sonst bricht der Export ab mit der vielsagenden Meldung "Formatvorlage konnte nicht kompiliert werden". In Version 1.3 dürften sie nur in den Dateien Kapitel-5_Produkt.odt und Kapitel-5_Thema.odt gewesen sein (ohne Gewähr auf Vollständigkeit, vor allem da ich Ihre organisationsspezifische Anpassung nicht kenne!).

Disclaimer

Die Migration funktioniert wunderbar mit dem Standardmodell 1.3. Bei organisationsspezifischen Anpassungen kann man nie wissen, was alles geändert worden ist. Insofern kann ich nicht ausschließen, dass die Migration damit Probleme bereitet. 

Viel Erfolg!

Thomas Ternité