ReqIF: Wenn DOORS-Anhänge nach dem Import verschwinden

Sie exportieren ein Modul aus IBM DOORS oder DOORS Next Generation als ReqIF (.reqifz), importieren es in ein anderes Anforderungsmanagement-Werkzeug, und der Text kommt sauber an — doch die eingebetteten Bilder und Objekte bleiben leer. Das ist ein klassisches Problem des ReqIF-Austauschs, und die Ursache ist subtiler als bloße Werkzeug-Inkompatibilität. Dieser Artikel erklärt die Ursache des Problems und stellt ein einsatzbereites Werkzeug zu seiner Behebung bereit.

Kurz gefasst

Eine .reqifz-Datei ist ein ZIP-Archiv, das Requirements.reqif sowie sämtliche Anhänge enthält. DOORS speichert diese Anhänge ohne Dateierweiterung (ihre Namen sind GUIDs wie _3dcc85d5-...). Das Zielwerkzeug stützt sich auf die Erweiterung, um zu wissen, wie eine Datei dargestellt wird: Fehlt sie, zeigt es nichts an. Das hier vorgestellte Werkzeug — change.bat + change.ps1 — erkennt den echten Typ jedes Anhangs anhand seiner Binärsignatur, stellt die korrekte Erweiterung wieder her, aktualisiert jede Referenz in Requirements.reqif und baut ein reimportierbares .changed.reqifz-Archiv neu auf.

Das Problem

ReqIF (Requirements Interchange Format) ist ein OMG-Standard, der genau dafür konzipiert wurde, Anforderungen zwischen heterogenen Werkzeugen auszutauschen. In der Praxis funktioniert der Austausch des Textes gut; es sind die eingebetteten Anhänge — Screenshots, Diagramme, OLE-Objekte aus Word oder Excel — die beim Hin- und Rückweg DOORS ↔ anderes Werkzeug brechen.

Der Ablauf ist folgender: DOORS erzeugt ein .reqifz-Archiv, das das XML-Dokument Requirements.reqif samt der binären Anhangsdateien enthält. Diese Dateien sind nach einer eindeutigen Kennung (einer GUID) benannt und tragen überhaupt keine Erweiterung. Das importierende Werkzeug ermittelt die Darstellung einer Datei aus ihrer Erweiterung; ohne diese kann es nicht wissen, dass es sich um ein PNG oder ein PDF handelt, und zeigt nichts an.

Warum es bricht

Drei Mechanismen wirken zusammen und führen zu diesem Ergebnis.

Speicherung ohne Erweiterung. Das ist die unmittelbare Ursache. DOORS exportiert Anhänge unter ihrem internen Namen (einer GUID), ohne Typ-Suffix. Ein striktes Zielwerkzeug rät den Typ nicht aus dem Inhalt und verlässt sich allein auf die Erweiterung — die nicht existiert.

Vorschaubilder von OLE-Objekten. Gemäß dem ReqIF-Standard wird ein Objekt, das kein Bild ist (eine Excel-Tabelle, ein Word-Dokument), in ein Vorschaubild eingehüllt. Man findet daher Dateipaare: eine Basisdatei mit der Deklaration type="text/rtf" und ihr _<guid>_alternative_image.png mit der Deklaration type="image/png". Die Referenzen erfolgen im XML über <object data="name" type="mime/type">-Tags. Eine Exportoption von DOORS wandelt zudem manche OLE-Objekte in .rtf um, was die Vielfalt der vorhandenen Typen weiter erhöht.

Der MIME-Typ ist nicht verlässlich. Man könnte versucht sein, sich auf den im XML deklarierten type (MIME) zu stützen, um die Dateien umzubenennen. Das ist eine Falle. Bei einem realen Export von 461 Dateien waren 55 (12 %) tatsächlich PNGs, aber von DOORS als text/rtf etikettiert — bestätigt mit dem Werkzeug file. Diese Dateien nach ihrem MIME-Typ umzubenennen hätte sie in .rtf verwandelt und ihre Darstellung zerstört. Die Binärsignatur (die Magic Bytes) ist die einzige Quelle der Wahrheit; MIME dient nur als Rückfalloption für exotische Typen, die die Signatur nicht abdeckt.

Die Lösung

Das Werkzeug besteht aus zwei Dateien, die im selben Ordner liegen müssen: change.bat, der Starter, und change.ps1, das die gesamte Logik enthält. Es arbeitet so: Es entpackt das Archiv, erkennt den echten Typ jedes Anhangs anhand seiner Binärsignatur (mit Rückfall auf MIME, wo nötig), benennt jede Datei mit der korrekten Erweiterung um und aktualisiert all ihre Referenzen in Requirements.reqif in einem einzigen Durchlauf, und baut dann ein <name>.changed.reqifz-Archiv neu auf, das zum Reimport bereit ist. Die Originaldatei wird nie verändert.

Zwei Implementierungsdetails verdienen Beachtung. Die Namensersetzung im XML ist sicher gegenüber verschachtelten Namen: Der Name einer Basisdatei wird nie innerhalb des längeren Namens ihres _alternative_image.png-Vorschaubilds verändert, und die Kodierung der .reqif bleibt durch byteweises Lesen/Schreiben erhalten. Zudem lädt der .bat-Starter den PowerShell-Code in den Speicher, was eine auf Restricted gesetzte ExecutionPolicy umgeht — das Werkzeug läuft also auch auf einer per Gruppenrichtlinie gesperrten Arbeitsstation.

Verwendung

Aus einer Eingabeaufforderung, im Ordner mit der .reqifz:

change.bat "MeineDatei.reqifz"

Das Ergebnis ist eine Datei MeineDatei.changed.reqifz, die neben dem Original erstellt wird. Behalten Sie die Anführungszeichen, wenn der Pfad Leerzeichen enthält.

Unterstützte Dateitypen

Die Erkennung umfasst Bilder (png, jpg, gif, bmp, tif, emf, wmf), Dokumente (pdf, rtf), neueres Office im OOXML-Format (docx, xlsx, pptx) und älteres Office im OLE-Format (doc, xls, ppt). Eine Datei, deren Typ nicht erkannt wird, bleibt unangetastet, statt blind eine Erweiterung zu erhalten. Beim realen Validierungsexport verarbeitete das Werkzeug den gesamten Satz ohne einen unerkannten Typ und ohne eingeführte Inkonsistenz; die Aktualisierung einer 15 MB großen .reqif dauerte etwa 0,3 Sekunden.

Weitere Ansätze

Das Skript ist ein wirksamer Workaround, aber nicht der einzige Weg. Je nach Spielraum kann es besser sein, das Problem weiter stromaufwärts zu beheben.

Eine wichtige Einschränkung: Die Dokumentation von Jama rät ausdrücklich davon ab, die Erweiterungen von Anhängen umzubenennen. Das Skript bekennt sich daher zu seinem Status als Workaround, spezifisch für eine bestimmte Kombination aus DOORS-Export und Zielwerkzeug. Wenn Sie an der Quelle eingreifen oder einen konformen Importeur wählen können, sind diese Optionen nachhaltiger.

Downloads

Die beiden Dateien des Werkzeugs samt seiner Dokumentation:

change.bat — der Starter (auszuführen)
change.ps1 — die Erkennungs- und Wiederaufbaulogik
README.md — vollständige Dokumentation (Voraussetzungen, Fehlerbehebung, technische Hinweise)

Bewahren Sie change.bat und change.ps1 im selben Ordner auf. Voraussetzung: Windows mit PowerShell 5.0 oder höher (standardmäßig auf Windows 10/11 vorhanden).

Quellen

• Why OLE object is not visible after importing ReqIF file into DOORS — jazz.net
• ReqIF roundtrip to DOORS NG — problem with images — reqif.academy
• ReqIF export without images — jazz.net
• Handling OLEs and RTF Files in DX Imports from DOORS to Jama — Jama Software
• ReqIF Import/Export — Polarion
• Import ReqIF — ReqView
• Requirements Interchange Format — Wikipedia