ReqIF2Excel — user guide

1. What the tool does

ReqIF2Excel reads a .reqif or .reqifz file exported from a requirements-management tool and writes an Excel workbook. Its guiding rule is that nothing may be lost: every picture, OLE object and attached file that a requirement refers to is kept, shown, saved and traced back to the requirement that owns it.

2. Converting a file

With the window

1. Start ReqIF2Excel.exe (or run_gui.bat when you work from the source).
2. ReqIF file — pick the .reqif or .reqifz to convert.
3. Excel output — pre-filled next to the input; change it if you like.
4. Set the options (see §4), then press Convert.
5. The log appears in the black panel. When it says Done, use Open workbook and Open attachments folder.

Your choices are remembered for the next session, in .reqif2excel.json in your home folder.

From the command line

python reqif2excel.py INPUT.reqifz [--out OUTPUT.xlsx] [options]
ReqIF2Excel.exe INPUT.reqifz --out OUTPUT.xlsx        (the .exe accepts the same options)

Exit codes: 0 success, 1 a usage or input error (the message starts with ERROR:), 2 only with --strict, when attachments are missing.

When --config is not given, the command line uses reqif2excel_config.json next to the application if that file exists, exactly like the window does, and prints which file it used. The converter refuses to write the workbook over the ReqIF file it is reading.

The Windows .exe has no console, so when you drive it from a script it writes its log to ReqIF2Excel_last_run.log in the output folder and still returns the exit code above.

3. Reading the result

The requirement sheets

One sheet per ReqIF specification (a DOORS module, a Codebeamer document), named after it. Requirements appear in document order.

Attribute columns that hold no value on any row are hidden, not removed: a module often declares far more attributes than its objects use, and those columns would otherwise bury the ones that matter. The Summary sheet lists every hidden column; to see one, select the columns on either side and choose Unhide. Set hide_empty_columns to false to keep them all visible.

How the requirement text is rendered

Rich text is flattened to plain text that keeps its structure:

The other sheets

• Summary — the input file, the source tool, the ReqIF version, the counts (requirements, relations, attachments embedded/extracted/missing), the exact configuration used, then a table of every warning and error. Read this sheet first: it is where a problem shows up.
• Unplaced objects — requirements present in the file but not placed in any specification hierarchy. They would otherwise be invisible.
• Specifications — one row per specification with its own attributes.
• Relations — every link with its type, group, source and target (both ids and the sheet each side lives on).
• Attachments — the trace table, described in §4.
• Extra attributes — appears only if a specification has more attributes than Excel allows columns (16,384). The values that did not fit are listed here, one row each, so they are still in the workbook.
• Overflow — the complete text of any cell that exceeded Excel’s 32,767-character limit. The requirement cell then ends with …[TRUNCATED — full text on the 'Overflow' sheet].

4. Images and attachments — how the trace works

Every embedded item gets a marker inside the requirement text, at the exact place it occupied in the original:

The numbering restarts at 1 for each requirement, and follows reading order.

The same items are listed in the row’s Attachments column and, in full detail, on the Attachments sheet: marker, kind, owning requirement (ReqIF id and foreign id), sheet and row, source attribute, original name, MIME type, size, SHA-256, the saved file (clickable), whether it is shown in the sheet, which attachment it is a preview of, the alternative text, and a note explaining anything unusual.

Files are saved next to the workbook in a folder named after it, for example requirements.xlsx → requirements_files/. Names are deterministic: <foreign id>_<marker number>_<original name>. Two references to identical bytes share one file.

Converting again into the same workbook name rewrites that folder: files that the previous conversion wrote and this one did not are removed, so the folder can never mix two documents. Only files this tool recorded itself are deleted. Anything else you put in the folder is left alone and reported as a warning.

A file that is present in the ReqIF archive but that no requirement points at is extracted too, and listed on the Attachments sheet as unreferenced with a warning. A file that a requirement points at only by name (its path did not resolve) is used, and the warning tells you so, because it might be another requirement’s picture.

Extracted files are written byte for byte as they were stored in the ReqIF archive: the tool never re-encodes, resizes or reshapes a file. The picture placed in the sheet is a scaled view of it that keeps the file’s own proportions; the full-size file is always the one in the folder.

Formats that Excel can show (PNG, JPEG, GIF, BMP, TIFF, WebP) are placed on the row. When an embedded object is itself a picture that also carries a preview image (IBM DOORS exports a BMP together with a PNG preview of it), only the picture is shown, so it does not appear twice; the preview is still saved and listed, with a note saying why it is not shown. Formats it cannot show (SVG, EMF/WMF, OLE containers, PDF, Office documents) are saved and linked from the Images cell instead, and the Attachments sheet says Embedded in sheet? = no. Either way the file is on disk and traceable.

Important — pictures float, they are not cell contents. Excel anchors a picture to a position, not to a row’s data. If you sort or filter the sheet, the pictures stay where they are and no longer line up with their requirements. The authoritative trace is the marker in the text plus the Attachments sheet, which survive any sorting. Sort a copy, or convert with --no-embed when you plan to sort.

The _files folder must travel with the workbook: the links in the workbook are relative to it. Zip the two together when you send them.

5. The options file

reqif2excel_config.json sits next to the application and is created with the defaults on first use. Edit it with any text editor.

An unknown option is ignored with a note; an out-of-range or wrongly typed one stops the run with a clear message.

6. What the warnings mean

7. Limits

• Excel cells hold at most 32,767 characters — longer texts are truncated in place and written in full to the Overflow sheet.
• Row height is capped at 409 points, so a very tall picture is scaled down; the full-size file is always in the _files folder.
• Pictures are anchored, not embedded in cells (see the sorting warning in §4).
• SVG, EMF and WMF cannot be displayed inside a workbook by Excel; they are saved and linked.
• ReqIF TOOL-EXTENSIONS (tool-private data) are not exported; they carry no requirement content.

8. About and where the tool comes from

The window’s About button shows the version, what the converter guarantees, and the project page. The address can be selected and copied there, and Open in browser opens it directly.

Every workbook records the converter version and the project page on its Summary sheet, so a workbook that circulates for months can still be traced back to the build that made it, and whoever receives it knows where the tool lives.