Import and Export

Holarch reads specifications, spreadsheets, requirements-interchange files, UML/SysML models and project files, and writes Word, Excel, CSV, ReqIF, JSON, Markdown, images and web pages. This page lists every import and export, where to find it, its options and its messages. Exports are available to every project member, including viewers; imports change the project and need the Owner or Editor role.

Concepts

Import paths

What every import does

• New IDs. Imported entities always get new IDs in the project. Nothing in the file can overwrite an entity unless you choose to match existing entities.
• One undo step. An Import page import is a single undo step (⌘Z removes it all). Renumber the whole document after import adds a second step.
• Untrusted content is cleaned. Rich text loses scripts, frames and unsafe links; SVG pictures lose scripts, event handlers and external references; XML with DOCTYPE or ENTITY declarations is refused; ZIP files are checked against size and compression limits.

What exports produce

• CSV files are UTF-8, comma-separated, one header row. Text that starts with =, +, -, @, a tab or a carriage return gets a leading apostrophe so spreadsheets show it as text instead of running it as a formula; plain numbers such as -5 stay numbers.
• XLSX files have a bold, shaded header row (or two group rows for matrix reports), wrapped text, column widths fitted to the content (up to 60 characters), frozen header rows where noted, and red fills for gaps.
• DOCX files use Word heading styles, a Calibri 11 pt body and US Letter pages. See Word output.
• File names are cleaned for every operating system: path and reserved characters become _, and names are cut to 120 characters.

How to use it

When and why

Import at the start of a project to bring an existing specification, a stakeholder spreadsheet or another tool's requirements into the model, so that tracing, quality checks and baselines work on them. Use spreadsheets later for bulk attribute updates by people who do not use Holarch. Export at reviews and hand-offs: Word for reading and signing, Excel for matrices and registers, ReqIF for exchange with other requirements tools, JSON for backups and moving projects between servers.

Import a Word specification

1. Open Needs & Requirements → Import and click Word (.docx).
2. Configure: keep Import as: Document and Document label: Requirements Document. Leave Numbering on Auto (numbered headings + shall sentences) when the file uses Word heading styles or Word list numbering. Click Next ›.
3. Select: drop the .docx file on the drop zone or click it to browse. The status reads "Analyzed “file.docx”: N rows, 5 columns, N table(s)." Click Next ›.
4. Customize: check Name of the new Document. Under Word Tables, set each requirements table to Entities (one per row) and map its columns; set other tables to Table in the description. Read the warnings. Click Next ›.
5. Preview: check the counts per class and the rows. Click Save.
6. Without warnings, the new document opens. With warnings, Import Complete lists them with Open Document, Open Database, Spider Diagram, Tree Diagram, Quality Check and Import Another File. The warnings are also written into the document's description, and the original .docx is attached to the document.

Import a spreadsheet

1. Click Excel / CSV (.xlsx, .csv). Use a header row, for example Number,Name,Description,Class, and outline numbers (1, 1.1, 1.2) so the hierarchy can be rebuilt.
2. Configure: choose Import as (Document, or None for entities without a document), the Default class, and for CSV the File encoding and the Date format for DATETIME columns.
3. Select the file. For a workbook with several sheets, pick the Sheet.
4. Customize each column's Maps To and Attribute. Columns whose title matches a field or attribute are mapped automatically.
5. Preview and Save.

Update existing entities from a spreadsheet

1. In the Database, filter to the entities (for example class:Requirement) and click Reports….
2. Choose Basic Tabular Output (CSV), tick the attributes to edit (for example Owner), and under Include tick ID. Click Create.
3. Edit the values in the spreadsheet. Do not change the ID column.
4. In Import, choose Excel / CSV, set Import as: None and Match existing entities by: Global ID.
5. In Customize, make sure the ID column maps to Global ID. Set Description to Ignore unless you edited it (see the tip below), and set the Global ID column, if you exported it, to Ignore.
6. Preview marks each matched row Updated. Click Save. Only the mapped columns are written; labels in a Labels column are added to the existing labels.

Back up or move a project

1. Open Manage Projects, open a project's row menu ⋯ and choose Export this project… (or on Home, Project ▾ → Export Project…).
2. Choose the options and click Export JSON.
3. To restore it, on any Holarch server: Manage Projects → Project Files ▾ → Import Project (.json)…. The import becomes a new project with a new ID; you are its owner.

Worked example: the CubeSat EO-1 demo

Create the demo with Manage Projects → Project Files ▾ → Create Demo Project ("CubeSat EO-1 — Earth Observation Demo").

1. Send the specification to a supplier as ReqIF. Open Documents → EO-1 System Requirements Specification, click Reports, choose ReqIF Output (.reqif) and click Create. The file holds the six sections and their requirements in the outline order, with numbers such as 2.1 as the foreign ID and the descriptions as XHTML. The demo's satisfies and verified by links point to functions, assets and tests outside the document, so they are not in this file; to include them, export from the Database instead (step 4).
2. Update owners in Excel. In the Database, search class:Requirement, click Reports… → Basic Tabular Output (CSV), tick Owner and ID, and create the file. Change the Owner of 3.1 Orbit Average Power and 3.2 Battery Capacity to "EPS Lead". Import the file as described in Update existing entities. The preview shows every row as Updated; after Save, 3.1 and 3.2 show the new owner and one ⌘Z restores the old values.
3. Review the matrix offline. Open Verification → Traceability Matrix with the specification on the left and Test Cases on top, and choose Export ▾ → Matrix Report (Excel).
4. Exchange the trace web. In the Database, search class:Requirement OR class:Action, click Reports… → ReqIF Output (.reqif). Relationships between the exported requirements and functions (for example F8 satisfies 4.4 Downlink Encryption) become SPEC-RELATIONs.
5. Back up. In Manage Projects, choose Export this project… on the demo, keep every option, and click Export JSON. The file includes the SRR Baseline, comments, history, and the dashboard settings.

Tips and good practice

• Import into a test project first when the file is large or unfamiliar; check the preview and warnings, then import into the real project.
• Number rows in outline form (1, 1.1, 1.1.1). The hierarchy comes from the numbers when there is no Parent column.
• Exported CSV descriptions are plain text. Re-importing them over formatted descriptions removes the formatting; map Description to Ignore in an update, or export with Rich Text ticked.
• Keep the ID column when you plan to re-import. Matching by Name or Number also works but needs the same class and unique values.
• A column titled like a label group (for example Verification Method with values Analysis, Test) is mapped to Labels.

Common mistakes

• Every row came in as New instead of Updated. The match column holds the displayed Global ID (I_…) rather than the entity ID, or Match existing entities by is set to the wrong field. Map the ID column to Global ID.
• Hierarchy is flat. Numbers are not in outline form, or Parent Number was not mapped. Check the warnings "missing parent number…".
• Wrong classes. A Class column with unknown names falls back to the default class with a warning. Use the class names from Settings → Schema.
• Odd characters in a CSV. Choose the right File encoding (for example ISO-8859-1 / Windows-1252 for older Excel CSV files).
• .xls files are refused. Save the workbook as .xlsx or .csv in Excel first.

How it connects to other features

• Imported documents open in Documents, where you restructure, baseline and publish them; their requirements go straight into the quality check and traceability views.
• Imported ReqIF and XMI relationships appear in the matrix, Spider diagrams and the Entity View.
• Exports feed reviews (Word, Excel), other tools (ReqIF, XMI-based tools via ReqIF, MS Project XML from the simulator) and backups (project JSON). Review Packages bundle several outputs.

The Import page

Open Needs & Requirements → Import. The page has one tab per source format and a four-step wizard: Configure → Select → Customize → Preview. ‹ Prev and Next › move between steps; Next › stays disabled until a file has been read. On the (.inno, .json, .xml) project-file tab the wizard skips Customize. Dropping or choosing a file switches to the tab that fits its extension (for example a .docx on the Excel tab switches to Word).

Tabs and accepted files

Step 1: Configure

The note "A file whose rows are all Statements or Requirements (or their subclasses) becomes a requirements document." describes where the import opens afterwards: such imports open the new document; others open the Database.

Outline formats

For plain text and Word, Outline format decides how numbered lines become the hierarchy:

• Auto (numbered headings + shall sentences) (default; for Word, the file's heading styles and list numbering are used).
• Numbered List with Period (1.), Numbered List with Parenthesis (1)), Numbered List (1).
• Uppercase Roman Numerals List with Period (I.), Lowercase Roman Numerals List with Period (i.).
• Uppercase Letter List with Period (A.), Lowercase Letter List with Period (a.), Lowercase Letter List with Parenthesis (a)).
• Multi-Level Numbered List with Period (1. 1.1. 1.1.1.), Multi-Level Numbered List (1 1.1 1.1.1).
• Multi-Level Lowercase List with Periods (1. a. i.), Multi-Level Lowercase List with Parentheses (1) a) i) (1) (a) (i)), Multi-Level Alphanumeric List (I. A. 1. a) (1) (a)), Multi-Level DoD List (1. a. (1) (a) 1. a.).
• Custom Outline Format…: a table of up to six levels, each with Numbering (Decimal, Lowercase Alpha, Number, Roman Numeral, Uppercase Alpha), Delimiter (Space, Period, End Parenthesis, Double Parenthesis) and Start. + Add Level adds one; × removes one.

With an explicit format, every line that matches a level becomes an item numbered 1, 1.1, 1.1.1 by its level; a short line (80 characters or fewer, without closing punctuation) becomes the name, a longer line becomes the description and the name is made from it; lines that match no level continue the previous item's description. All items get the default class. For Word, choosing a format other than Auto reads the file as plain text, so heading styles, formatting, pictures and tables are not used.

Step 2: Select

Drop a file on Drag and drop a file here or click it to browse; the accepted extensions are listed under it. Or paste the content into the text box and click Analyze Pasted Text (CSV with a header row, JSON or XML, ReqIF XML, XMI, or document text). For plain text, the loaded file stays editable under Imported content; edit it and click Analyze Again. For a workbook with several sheets, Sheet: lists each sheet with its row count; the first sheet with data is preselected.

The status line reads "Analyzed “name”: N rows, N columns." (plus "N table(s)" for Word, or "N entities, N relationships." for project files), or shows the error.

Step 3: Customize

• Name of the new Document: (with Import as: Document; default the file name).
• Word Tables (Word only): see Word tables.
• The column table: Include (tick to import), Column, Title, Maps To, Attribute and Sample (values from the first two rows; formatted cells show their text plus "[N images]" or "[N tables]").
• The warning list ("N warnings", the first 50 and "…and N more") or "No warnings."

Maps To values:

Automatic column mapping

Step 4: Preview

Statistics lists the entity count per class and the total. With Import as: Document, a line says whether a requirements document or another document will be created. The warning list repeats, then a table of the first 500 rows with Status (New or Updated), Class, Number, Name and Description. Save runs the import; the toast reads "Imported N new, N updated".

Import Complete

Shown when the import produced warnings: "N entities created, N updated, plus the document “name”.", the warnings, and the buttons Open Document, Open Database, Spider Diagram, Tree Diagram, Quality Check and Import Another File. A clean import goes straight to the new document (requirements documents) or the Database.

Format details

Word (.docx)

• Headings (Word's Heading 1 to Heading 9 styles, styles based on them, and paragraphs with an outline level) become Statements, nested by level, numbered with the file's list numbering or with generated numbers. The Title style is skipped.
• Requirements: a paragraph containing "shall", "must", "will" or "should", or a numbered (not bulleted) list item, becomes a child item of the current heading: a Requirement when it has one of those verbs, otherwise a Statement. Its name is the first five words after the verb, in title case.
• Body text, bullet items, pictures and unmapped tables join the description of the item they follow. Bold, italic, underline, line breaks and bullet lists are kept as rich text.
• Pictures: PNG, JPEG, GIF, WebP and SVG are kept. Other formats (for example EMF or WMF) are skipped with a warning; so are pictures above the per-file limit.
• Tracked changes: inserted text is imported; deleted text is not.
• Original file: the .docx is attached to the new document.

Word tables

Tables with the same header row are grouped ("Tables 3+ (4 with this header)"). Each group shows its data-row count and header and a choice:

• Entities (one per row): each data row becomes an item under the current heading. Map each column to Number, Name, Description, Class, Labels, Attribute (then pick it), New Attribute or Ignore. Columns titled ID, Req ID, Requirement ID, Req No, Req Number, Identifier, Ref, Reference, Paragraph or Para map to Number; Shall, Shall Statement, Requirement Statement, Requirement Text, Statement or Text map to Description.
• Table in the description: the table is kept as a table in the description of the item before it.

A table is proposed as entities when it has at least two columns, data rows, a Name or Description column, and either a Number column or a cell with "shall", "must", "will" or "should".

Excel and CSV

• The first row is the header; empty rows are skipped.
• XLSX: shared and inline strings, numbers, booleans (TRUE/FALSE) and dates (by the cell's number format, as yyyy-MM-dd or yyyy-MM-ddTHH:mm) are read; multi-line cells keep their line breaks; leading and trailing empty rows are dropped.
• CSV: comma-separated, with double quotes around fields that contain commas, quotes or line breaks. Semicolon-separated files are not split; save them with commas.
• Excel 97-2003 (.xls) is not supported.

Plain text

With Auto, each line is read as follows: leading -, * or • bullets are removed; a leading number such as 3.2, 3.2. or SYS-3.2 is kept as the item number. A line without "shall", "must", "will" or "should" becomes a Statement heading when it is numbered or short (under 80 characters without closing punctuation); otherwise it is added to the previous item's description. Each sentence with one of those verbs becomes a Requirement: the first takes the line's number, further ones get .1, .2 added; unnumbered requirements are numbered under the current heading.

ReqIF

• Every SPEC-OBJECT becomes a row with ReqIF ID (Row ID), Parent ID (Parent Row ID, from the SPECIFICATION hierarchy), Type (Class, from the SPEC-OBJECT-TYPE name), Long Name (when no attribute looks like a name or title) and one column per attribute definition (string, XHTML, Boolean, date, enumeration, integer and real).
• XHTML values become rich text; enumeration values are joined with "; ".
• Columns that do not match an attribute default to New Attribute instead of Ignore.
• SPEC-RELATIONs become relationships named by their relation type. When the name is unknown or the schema does not allow it between the two classes, traced to is used; when that is not allowed either, the relationship is skipped with a warning.
• .reqifz archives are unpacked and their .reqif file is read.

UML/SysML (XMI)

XMI files from tools such as MagicDraw, Enterprise Architect and Rational Software Architect are read by element type:

Nesting becomes the hierarchy, owned comments become descriptions, and dependencies become relationships: satisfy → satisfies, verify → verifies, deriveReqt → traced from, trace, refine, copy and plain dependencies or abstractions → traced to.

Holarch and other tool files (.json, .inno, .xml)

The (.inno, .json, .xml) project-file tab merges entities from a file into the open project:

• Holarch project exports, Database JSON exports and document exports (Document Export (Holarch JSON)).
• .inno ZIP archives with a .json or .xml data file; attached files inside the archive are re-embedded.
• XML files with <entity> elements (attributes, labels and relationships as child elements).

Classes, attributes, labels and relationships are matched by name when the file's schema differs from the project's. With Merge the file's schema… on, missing classes, relations, attributes and labels are added first ("Schema: added N class(es), relation(s), attribute(s) or label(s) from the file."). Schema Only imports only the schema. Comments, history and diagram layouts come along when their options are on. Simulation scripts in the file are marked as imported, and the simulator asks before running them.

Matching existing entities

• Global ID matches the value of the column mapped to Global ID against the entity's ID (shown as ID in the inspector's metadata and written by the ID option of the CSV report). The displayed Global ID of the form I_… does not match. Without a Class column, a matched entity keeps its class.
• Name and Number match an existing entity of the same class with that name or number.
• A matched row updates only the mapped fields: unmapped Name, Number or Description keep their values, mapped attributes are written, labels are added, and the class changes only when the file has a Class column.

Hierarchy

Each row's parent is found from, in order: its Parent Row ID; its Parent Number; its own number (the parent of 1.2.3 is 1.2; if 1.2 is not in the file, the nearest existing ancestor such as 1). Rows without a parent become top-level items of the new document. Parents are linked with decomposed by.

Value conversion

Values that cannot be converted are left out with a warning.

New attributes

New Attribute columns become attributes named after the column on each class that receives a value. The type is chosen from the data: rich text for ReqIF XHTML, Number when every value is numeric, Enumeration (with the values as choices) for ReqIF enumerations or for up to 12 short distinct values used by fewer than half the rows, long text when a value exceeds 120 characters, otherwise text. An existing attribute of the same name is reused.

Other imports

Exports

Project export

Export this project… (Manage Projects row menu) or Project ▾ → Export Project… (Home) opens Export Project:

• File name (default the project name with spaces as _).
• Export Options: Include Baselines, Include Comments, Include History (also includes deleted entities that can be restored), Include Project Preferences (dashboard, charts, presentation settings), all on.
• Schema Only (custom labels and preferences, no entities): exports the schema (and, with preferences on, the dashboard and charts) without entities; it turns the first three options off.
• Export JSON downloads name.json.

Attachments and pictures are embedded in the file, so a project export is self-contained. When saving fails and the browser cannot keep a copy, the save banner offers Download a copy, which downloads the full project the same way.

Database reports

In the Database, Reports… (top bar) reports on the selected rows, or on every entity of the current query when nothing is selected. The bulk bar's More ▾ → Reports… and the Entity View's Reports… work on the selection or the one entity. Download Report shows the entity count, Report Type, the options and File Name; Create downloads. "Select a report type." appears when none is chosen.

Errors during a report show "Report failed: …".

Document reports

A document's Reports button offers Basic Document Output (DOCX), Document Outline Report (DOCX), Basic Tabular Output (CSV), Comment Report, Quality Checker Report, RVTM, VCRM, RVM, RTM, RSM and TVM (XLSX), ReqIF Output, Post-Baseline and Baseline to Baseline Change Reports (XLSX), Markdown (.md), Document Export (Holarch JSON) and Print / PDF. Each is described with its options in Documents → Reports.

Diagram exports

Every diagram editor's Export ▾ offers:

On the Diagrams page, Report… opens Diagrams Report for every diagram in the current filter and sort: Fields (Name, Number, Description, Diagram Type on; Created On, Modified On off), File name (up to 100 characters) and Format (Microsoft Word (DOCX) or Web Page (HTML)). Run Report builds it ("Building report…", then "Report downloaded"); the image is always included. Messages: "Enter a file name.", "File name must be 100 characters or fewer.", "No diagrams to report."

Traceability matrix exports

Export ▾ in the matrix: Matrix Report (Excel) (an Excel 2003 XML workbook saved as .xls, with rotated column headers), Comma Separated (CSV) (X marks), Detailed CSV (relation names), Importable Matrix (CSV) (cell A1 holds the matrix settings; rows and columns carry entity IDs; re-import with Import…), and under Artifacts Export to a New Artifact… and Export to an Existing Artifact… (saves the matrix settings to an Artifact labeled Matrix). Each download asks for the File Name.

Baselines and versions

In Plan & Deliver → Baselines & Versions, each baseline row has Export (a holarch-baseline JSON file with the name, date, document, approvals and snapshot). Compare shows the changes between two versions with Export CSV and Export XLSX (Number, Name, Class, Change Type, Field, Old Value, New Value).

Schema export

Settings → Schema → Export Schema downloads "project schema.json" (format: holarch-schema) with the classes, relations, attributes and labels.

Whiteboard export

Export… in a whiteboard opens Export Whiteboard:

• Format: PNG, JPG, SVG or PDF.
• Area: This board, Selected elements (with a selection), Current view, All boards (one file per board), or a frame.
• Scale (PNG, JPG): 0.5× to 4×. Quality (10–100) (JPG). Resolution (PDF): Standard (96 dpi) or Print (300 dpi); one page per board or frame, as images. Transparent background (PNG, SVG).
• "SVG keeps shapes and text editable in vector tools." The settings are remembered in this browser. With nothing to export: "Nothing to export. Add elements or choose another area."

Exports on other pages

Project JSON format

A project export is one JSON object:

{
  "format": "holarch-project",
  "version": 1,
  "id": "p…", "name": "…", "description": "…",
  "created": 1760000000000, "modified": 1760000000000,
  "nextNum": 412,
  "entities": { "<id>": { "id", "classId", "name", "number", "description", "labels": [labelId], "props": { "<attributeId>": value }, "created", "modified", "locked"? } },
  "relationships": { "<id>": { "id", "source", "relId", "target", "props": { … } } },
  "diagrams": { "<entityId>": { "<diagramType>": { …layout and settings… } } },
  "diagramMod": { "<entityId>": time },
  "baselines": [ { "id", "name", "created", "docId"?, "approvals"?, "snapshot": { "entities", "relationships", … } } ],
  "comments": { "<entityId>": [ { "id", "t", "text", "by"?, "resolved"? } ] },
  "history": [ { "t", "op", "id", … } ],
  "trash": [ … ],
  "savedQueries": [ … ],
  "schema": { "classes", "relations", "properties", "labels" }
}

• Times are milliseconds since 1970 (UTC).
• relId reads from the source's point of view; the inverse relationship is implied and not stored.
• Descriptions are plain text or sanitized HTML; pictures and attached files are data: URLs.
• schema is present when the project's schema differs from the default.
• Project preferences such as the dashboard and charts are stored under diagrams (__dashboard, __charts).

The Database JSON export uses the same format with only the chosen entities. A document export uses "format": "holarch-document" with docId, entities, relationships, docState and the optional comments, baselines and history. A schema export uses "format": "holarch-schema"; a baseline export uses "format": "holarch-baseline".

Keyboard shortcuts

The Import page has no shortcuts of its own. ⌘Z undoes a whole import. See Keyboard shortcuts.

Messages

Import errors (shown in the Select step as "Could not read the file: …")

Import warnings

Limits

Related

• Documents: document reports and the Word output.
• Requirements: importing requirements step by step.
• Model and Database: queries and selections that drive the Database reports.
• Traceability: the matrix import and exports.
• Schema extensions: custom attributes created by imports.
• Help: Import, Import Requirements from Word, Excel, CSV or ReqIF, Manage Projects, Data and Security.