Reference
Import and Export
Every way to bring data into Holarch (Word, Excel, CSV, ReqIF, XMI, text, Holarch backups and project files, schemas, matrices) and every export format, with all options, the .holarch backup format and the project JSON format.
On this page
- Concepts
- How to use it
- When and why
- Import a Word specification
- Import a spreadsheet
- Update existing entities from a spreadsheet
- Import a PDF specification
- Import an Excel workbook as a spreadsheet
- Export a spreadsheet to Excel or CSV
- Import a UML/SysML model (XMI)
- Export a UML/SysML model (XMI)
- Round trip with Papyrus
- Back up or move a project
- Coming from another tool
- Worked example: the CubeSat EO-1 demo
- Tips and good practice
- Common mistakes
- How it connects to other features
- The Import page
- Format details
- Other imports
- Exports
- Holarch backup format
- Project JSON format
- Keyboard shortcuts
- Messages
- Limits
- Related
Use imports to bring existing data into a project, and exports to share or back it up. Holarch reads specifications, spreadsheets, requirements-interchange files, UML/SysML models and project files. It writes Word, Excel, CSV, ReqIF, JSON, Holarch backups (.holarch), Markdown, images and web pages.
This page lists every import and export, where to find it, its options and its messages.
Who can use them:
- Exports: every project member, including viewers.
- Imports: the Owner or Editor role, because imports change the project.
Concepts
Import paths
| What you have | Where to import it | Result |
|---|---|---|
| Word specification (.docx) | Needs & Requirements → Import and Export, Word (.docx) | A numbered document of sections and requirements |
| PDF specification (.pdf) | Import, Import PDF Specification… (AI) | Requirements with their number and the file and page each came from, in a document or a package |
| Spreadsheet (.xlsx, .xlsm, .csv) | Import, Excel / CSV (.xlsx, .csv) | New or updated entities, optionally a document |
| Plain text (.txt or pasted) | Import, Plain Text (.txt) | A numbered document |
| ReqIF (.reqif, .reqifz) | Import, ReqIF (.reqif) | Entities with hierarchy, attributes and relationships |
| UML/SysML model (.xmi, .uml, .xml, .mdzip) | Import, UML/SysML (.xmi, .uml, .mdzip) | Requirements, blocks, parts, interfaces, activities with their flow, state machines, test cases and SysML relationships |
| Holarch backup or project file (.holarch, .json) | Import (format: Holarch project (.holarch, .json)) | Entities merged into the open project |
| Whole project (.holarch, .json) | Manage Projects → Project Files ▾ → Import Project… | A new project |
| Schema (.json) | Settings → Schema (rail) → More ▾ → Import Schema… | Classes, attributes, relations and labels |
| Matrix (.csv) | Traceability Matrix → Import… | Relationships added or removed |
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.
- A single Undo takes it all back. ⌘Z / Ctrl+Z removes an import from the Import page completely. Renumber the whole document after import needs a second Undo.
- 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.
- Progress. An import or export that takes more than about a second shows a progress bar at the bottom of the window. It names the current step and shows the count when it is known. The page stays usable meanwhile.
What exports produce
- CSV files are UTF-8 with a byte-order mark (so Excel shows accented, Cyrillic and CJK text correctly), comma-separated, with one header row.
- Text that starts with
=,+,-,@, a tab or a carriage return gets a leading apostrophe. Spreadsheets then show it as text instead of running it as a formula. - Plain numbers such as
-5stay numbers.
- Text that starts with
- XLSX files have:
- A bold, shaded header row (or two group rows for matrix reports).
- Wrapped text, and 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.
- Text in any language (names, descriptions and values with accents, Cyrillic, Chinese, Japanese or Korean characters) is written unchanged to CSV, XLSX, DOCX, ReqIF, JSON and project files, and imports back the same.
- Dates and counts that Holarch formats (export dates, created and modified times) follow your browser language. In CSV, ReqIF and JSON files, attribute values keep their stored form (
yyyy-MM-dddates,.decimals), so files import back unchanged. In XLSX tables, Number and Percent attributes are number cells and dates are date cells, which Excel shows in your own region's format and which import back as the same values. - File names are cleaned for every operating system. Path and reserved characters become
_, and names are cut to 120 characters. Letters of every language stay (a project named "Fahrzeugprüfung 車両" exports asFahrzeugprüfung_車両…).
How to use it
When and why
Import at the start of a project. Bring in an existing specification, a stakeholder spreadsheet or another tool's requirements. Tracing, quality checks and baselines then work on them.
Later, use spreadsheets 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.
- Holarch backup (.holarch) for backups and for moving projects between servers.
- JSON for scripts and other tools that read project data.
Import a Word specification
- Open Needs & Requirements → Import and Export.
- Drop the .docx file on the drop zone, or click the drop zone to choose it.
The status reads "Analyzed “file.docx”: N rows, 5 columns, N table(s)." and Format shows Word (.docx).
- Click Continue.
- Under Word tables, set each requirements table to Entities (one per row) and map its columns.
- Set every other table to Table in the description.
- Leave Numbering pattern empty. Word heading styles and Word list numbering are used automatically.
- Read the warnings, then click Continue.
- In Review, keep Create a requirements document from these N requirements ticked, with Document type: Requirements Document, and check the Name.
- Check the new items and their descriptions.
- Click Import N items.
Without warnings, the new document opens. With warnings, Import Complete lists them.
The original .docx is attached to the new document. Any warnings are also written into the document's description.
Import Complete offers Open Document, Open Database, Spider Diagram, Tree Diagram, Check Quality and Start Another Import.
Import a spreadsheet
Prepare the file first:
- Use a header row, for example
Number,Name,Description,Class. - Use outline numbers (1, 1.1, 1.2) so Holarch can rebuild the hierarchy.
Then import it:
- Open Needs & Requirements → Import and Export and drop the file (.xlsx or .csv).
- For a workbook with several sheets, pick the Sheet. For a CSV file, check the Delimiter and the Text encoding.
- Click Continue.
- Check each column's Holarch field.
Columns whose title matches a field or attribute are already mapped and marked auto. To have AI propose fields, choose ✦ AI ▾ → Suggest mapping and tick the changes to keep.
- Choose the Class for rows without a class, and for a CSV the Date format of date columns.
- Click Continue to review.
- Tick or untick Create a document from these N items.
- Click Import N items.
Update existing entities from a spreadsheet
Export the entities with their IDs, edit the file, and import it back. Holarch matches each row to its entity by ID.
- In the Database, filter to the entities (for example
class:Requirement). - Click Export… and choose Table (CSV).
- Tick the attributes to edit (for example Owner).
- Under Include, tick ID.
- Click Export.
The CSV file downloads.
- Edit the values in the spreadsheet. Do not change the ID column.
- In Import, drop the edited file and click Continue.
- In Map, check that the ID column maps to Global ID, and set Match existing entities by to Global ID.
- Set Description to Skip, unless you edited it (see the tip below).
- If you exported the Global ID column too, set it to Skip.
- Click Continue.
Review counts the matched rows under Updated items and lists each changed field with its old and new value.
- Untick Create a document…, then click Import N items.
Only the mapped columns are written. Labels in a Labels column are added to the existing labels.
Import a PDF specification
AI (Claude Sonnet) reads the requirement statements of a PDF specification (for example a NASA procedural requirement or an FAA advisory circular), and you review them before they are added. It needs AI: the included AI on the hosted service, or your own Anthropic key. On the local app, choose Anthropic API in AI Settings…; other providers cannot read PDF files. The file must have text: a scanned PDF without text finds nothing.
- Open Needs & Requirements → Import and Export and click Import PDF Specification…, or drop the .pdf file on the drop zone.
- Holarch uploads the file and reads it 5 pages at a time, with a progress card (Reading the specification… 3 of 12; Cancel stops it and adds nothing). On the included AI it first asks to confirm the requests it uses: one per 5 pages for a file of up to about 30 pages, more for longer files, because each 5-page part reads the whole file again (100 pages: 30 requests; 200 pages: 90).
- Import PDF Specification lists every statement found: Number (the requirement's identifier, such as SWE-033, or its paragraph number), Statement (the text as written) and Page (the page of the PDF file it starts on, counted from 1, not the printed page label). A statement repeated later in the file, such as in a compliance matrix, is listed once. Edit numbers and statements, clear the rows to leave out (All selects or clears every row), and choose Add the requirements to: a new document Requirements from <file name>, an existing document, or a package of the model.
- Click Add Requirements. Holarch adds them and opens the document; a single Undo takes it all back. Each requirement's name is the first words of its statement.
Each requirement keeps its source: the Definition section shows From NPR 7150.2D.pdf, page 31, and its history names the source document.
Limits and messages:
- At most 10 MB and 200 pages: "The PDF is larger than 10 MB. Split it into smaller files, then import each one." and "The PDF has 240 pages; at most 200 can be imported at once. Split it into parts, then import each part."
- "The PDF is password-protected. Remove the password, then import it again."
- "PDF specification import needs Claude through the Anthropic API or Amazon Bedrock. Choose one of them in AI Settings, then import again." (local app with another provider).
- A page range that fails is named above the list, for example "Pages 6–10 were not read: …". The other pages are listed; import the file again to read the missing ones.
- Requirements are found by their wording: "shall" and "must" statements and numbered requirements. Recommendations ("should"), permissions ("may"), notes and headings are left out. Check the list before adding it.
Import an Excel workbook as a spreadsheet
Use this when the workbook's formulas, formats and charts matter. The rows become a Spreadsheet, not items.
- Open Needs & Requirements → Import and Export and click Import as a Spreadsheet…, or press ⌘K / Ctrl+K and choose Import Excel Workbook as a Spreadsheet…. If an .xlsx file is already loaded on the Import page, the button reads Import This Workbook as a Spreadsheet and uses that file.
- Choose the .xlsx or .xlsm file. A progress card shows the stages for large workbooks.
- Read the Import Summary, then click Close. The Spreadsheet opens.
What comes in: every sheet (hidden sheets stay hidden), values, formulas (shared, array and dynamic-array formulas), Excel's last values, number formats, fonts, fills, borders, alignment, column widths and row heights, hidden rows and columns, merged cells, frozen panes, defined names, tables, notes, the date system and calculation settings, and charts of the kinds Holarch draws (column, bar, line, pie, doughnut, scatter). The sheet's filter becomes a shared view named Imported filter, so the sheet itself shows every row. A single Undo removes the whole import.
An import never fails because of content Holarch cannot calculate yet:
- A formula with a function Holarch does not support yet keeps Excel's last value and its text. Its corner marker says, for example, "Calculated in Excel: XLOOKUP isn't supported yet. The value is Excel's last result." Formulas that use the value calculate normally. When a later version adds the function, the cell calculates again by itself.
- A formula that uses another workbook keeps its value: "Value from another workbook (Rates.xlsx). Not updated here." Holarch never opens linked files.
- What-If data tables keep their values.
- Macros (VBA) are removed and never run. Pivot tables, data connections, Power Query tables, slicers, timelines, form controls, images, shapes, sparklines, data bars and icon sets are not imported; the cells they filled keep their values, and the summary lists them.
The Import Summary shows:
- the counts of sheets, cells, formulas and charts;
- the Recalculation check: Holarch calculates every formula and compares it with Excel's value at 15 significant digits, for example "3,861 of 3,872 formula cells match Excel (99.7 %)". Cells that keep Excel's value are not counted;
- Not supported yet: each function with its number of cells. Show Cells selects them; F8 and Shift+F8 step through them;
- Kept as Excel's values and Not imported;
- the differences from Excel, with both values. Export Recalculation Report… saves them as a CSV file (cell, formula, Excel's value, Holarch's value; no other cell content), which you can attach to a support request.
The summary stays with the spreadsheet: ⌘K / Ctrl+K → Show Import Summary on the spreadsheet opens it again.
Limits and messages:
- At most 50 MB on the hosted service and 100 MB in the desktop app, and 500,000 filled cells: "The workbook is larger than 50 MB. Remove unused sheets or split the workbook, then import it again." The spreadsheet limits apply as well (Storage limits).
- At most 2,097,152 rows and columns over all sheets (each sheet counts up to its last used, formatted or merged row and column): "The workbook needs more than 2,097,152 rows and columns in all, usually because formatting or merged cells reach the last row or column. Clear the unused rows and columns or split the workbook, then import it again."
- "Old Excel files (.xls) cannot be read. Save the workbook as .xlsx, then import it."
- "The workbook is password-protected. Remove the password in Excel, save it, then import it again."
- "The file is not a valid Excel workbook. Open it in Excel, save it as .xlsx, then import it again."
Export a spreadsheet to Excel or CSV
On a spreadsheet, press ⌘K / Ctrl+K and choose:
- Export Spreadsheet to Excel: every sheet as an .xlsx workbook with formulas, Holarch's calculated values, formats, widths, merged cells, frozen panes, names, tables, notes and charts. The filter and sort of the view you are looking at are written as the sheet's filter; other views are not. Cells that keep Excel's value are written back with their original formula, so Excel → Holarch → Excel keeps every formula. A project or document marking is written as the page header and footer.
- Export Sheet as CSV or Export Sheet as TSV: the values of the current sheet, without formulas. Text that starts with
=,+,-or@is written so that Excel shows it as text.
Import a UML/SysML model (XMI)
Bring a SysML model from Cameo Systems Modeler or MagicDraw, Enterprise Architect, IBM Rhapsody or Papyrus into Holarch. Holarch reads XMI 2.x with UML 2.5 and the SysML 1.x profile (1.3 to 1.7).
- Export the model from your tool:
- Cameo / MagicDraw: File → Export To → Eclipse UML2 (v5.x) XMI File, or import the .mdzip project file directly.
- Enterprise Architect: select the package, then Publish → Export XML, type XMI 2.1. Project files (.eapx, .qea) cannot be read directly.
- Rhapsody: export with the XMI toolkit (XMI 2.x).
- Papyrus: import the model's .uml file.
- Open Import and drop the file. Format shows UML/SysML (.xmi, .uml, .mdzip).
- Click Continue twice, then check Review: the relationships, which activities get an action diagram, a list of what is not imported, and the new items.
- Click Import N items. A single Undo takes back the whole import.
How the model maps to Holarch
| UML / SysML | Holarch |
|---|---|
| «requirement» (and functional, performance and interface requirements) | Requirement: id → Number, text → Description, nested requirements → decomposition; the requirement kind becomes a label |
| «block», class, component, node, actor | Asset (blocks labelled Block) |
| Part property (composition) | Asset decomposed by the part's block |
| Generalization | the general block extended by the specific one |
| Shared (aggregation) property | Asset related to the referenced block |
| Value property | Characteristic that specifies the block: default value → Value, the value type's unit → Units |
| «constraintBlock», constraint property, binding connector | Equation (constraint → Value), equation of the block, has variable for each bound value property; unbound parameters become Characteristics |
| Port («proxyPort», «fullPort», «flowPort») | Port decomposing its block and instantiating its type; Direction from the flow port or the flow properties of its type, Conjugated |
| Connector | Conduit (labelled Interface) connecting the ports (or blocks) at its ends |
| Item flow, signal | Input/Output transferred by the connector's Conduit |
| Activity, action, use case | Action; the actions of an activity are its steps (decomposition) |
| Control flow (sequence, fork/join, decision/merge, simple loops) | The activity's action diagram flow (SEQUENCE, AND, OR, LOOP) |
| Object flow between actions | Input/Output generated by one action and received by the next |
| «testCase» | Test Case |
| State, initial and final state, transition (trigger, guard) | Characteristic labelled State / Initial State / Final State, Transition (pushes / fetches), Guard attribute; top-level states specify the block |
| Choice, junction, fork, join, entry and exit points | One Transition per path through them (guards joined with and); a fork's transition fetches every target state, a join's is pushed by every source state |
| State with several regions; entry, do and exit behaviors; transition effects | Parallel State with one Region State per region; Actions labelled Entry/Do/Exit Action that the state specifies; the effect decomposes the Transition |
| Interaction (sequence diagram) | Action with one step per message, performed by the receiving lifeline's Asset, and an Input/Output from the sender; alt/opt → OR, par → AND, loop → LOOP; it gets a Sequence Diagram |
| «satisfy», «verify», «deriveReqt», «refine», «trace», «copy» | satisfies, verifies, derives, refines, traced to, copies |
| «allocate» (behavior → structure) | the block performs the action |
| Documentation, comments, «rationale» | Description |
| Packages | The Package attribute (path, e.g. Drone::Structure) |
| Tagged values | Attributes (new attributes are added to the class) |
| Stereotypes from other profiles | Labels in the Stereotypes label group; their tagged values become attributes of the item's class, shown in the inspector under «Stereotype» (profile) |
| Diagrams | Not imported as layouts. Block, internal block, state machine and action diagrams are drawn from the imported model |
Limits
- Diagram layouts and operations are not imported; Review lists what is left out.
- An activity's flow is drawn only when it is well structured (every fork meets one join, every decision one merge, loops formed by a merge and a decision back to it) and its action names are unique. Otherwise its actions are imported without a flow, and Review says why.
- Each imported item keeps its XMI id. Match existing entities by defaults to XMI ID for XMI files, so importing a later export of the same model updates those items instead of adding copies. Relationships already present are not added twice.
- Exports from Cameo/MagicDraw, Enterprise Architect and Papyrus were checked against their documented formats, not against files from each tool version. If an export does not import as expected, send it through Contact Us… (account menu or ⌘K / Ctrl+K).
Export a UML/SysML model (XMI)
Send the model to Cameo Systems Modeler or MagicDraw, Enterprise Architect, IBM Rhapsody or Papyrus.
- Open Import and Export and click Export UML/SysML (XMI)… on the Export card.
- Pick the Format:
- OMG XMI 2.5.1 (.xmi): SysML 1.6 in XMI 2.5.1 with UML 2.5.1, for Cameo/MagicDraw, Enterprise Architect and Rhapsody.
- Papyrus (Eclipse UML) (.uml): the same model as an Eclipse UML2 model file with the Papyrus SysML 1.6 profile, for Eclipse Papyrus 7 with the SysML 1.6 add-on. Papyrus does not read OMG XMI 2.5.1 files.
- Leave Holarch attributes and labels on to keep the LML data that SysML has no place for (classes such as Statement, numbers, labels, attributes such as Priority and Status). Holarch reads it back without loss, including relationship attributes such as Trigger on receives or Amount on consumes (one «HolarchElement» on the model lists them). In the .xmi file it is a «HolarchElement» stereotype; in the .uml file it is an annotation on each element, which Papyrus keeps when it saves. Turn it off for a plain SysML file.
- Check the File name (default: the project name) and click Export. The file is
<file name>.xmior<file name>.uml. - In the other tool, import the file (Cameo/MagicDraw: File → Import From → Eclipse UML2 (v5.x) XMI File; Enterprise Architect: Publish → Import XML). For Papyrus, see Round trip with Papyrus.
What is written
| Holarch | UML / SysML |
|---|---|
| Requirement, Statement | «requirement»: Number → Id, description → Text, decomposition → nested requirements, Rationale → «rationale» comment |
| Asset | «block» (or «interfaceBlock» with the Interface Block label); parts from decomposed by, shared properties from related to, generalizations from extended by |
| Port | proxy port typed by what it instantiates, conjugated when Conjugated is set; flow properties on its type from the items it carries and its Direction |
| Characteristic or Measure that specifies an Asset | value property typed by a «valueType» for its Units, Value as the default value |
| Equation | «constraintBlock» with its Value as the constraint, a parameter per variable, bound to the block's value properties |
| Input/Output | Signal; on a Conduit, an «itemFlow» on the connector |
| Conduit | Connector in the block that contains both ends (nested ends when deeper) |
| Action | Activity with its action-diagram flow (call actions, fork/join, decision/merge, loops), parameters for what it receives and generates; Use Case label → use case with include and extend |
| Test Case | «testCase» activity |
| States and Transitions | State machine of the block, with regions, entry/do/exit behaviors, triggers, guards and effects; a transition from several states or to several states gets a join or a fork |
| satisfies, verifies, derives, refines, traced to, copies | «satisfy», «verify», «deriveReqt», «refine», «trace», «copy» |
| performs, allocated to | «allocate» |
| Labels in the Stereotypes group | Stereotype applications of their profile, with tagged values (Papyrus format: an annotation per stereotype, because Papyrus has no definition of the profile) |
Artifacts, Tasks, Risks, Issues, Decisions, Time and Cost items and their links stay in Holarch; the toast after the export counts what was left out.
Round trips: items imported from XMI keep their original ids, and the export writes them back, so Cameo → Holarch → Cameo updates the same elements. Items made in Holarch get ids of the form HL_<project>.<item>; importing the file into the same project updates them.
Round trip with Papyrus
- Export with Format set to Papyrus (Eclipse UML) (.uml) and Holarch attributes and labels on.
- In Papyrus (with the SysML 1.6 add-on): create a project (File → New → Project… → General → Project), copy the .uml file into it, select the file, then File → New → Other… → Papyrus → Papyrus Model to add the diagram files. Or open the .uml file in the UML model editor.
- Edit the model and save it.
- In the same Holarch project, import the saved .uml file with Match existing entities by set to XMI ID. Elements that came from Holarch update their items in place, with their numbers, labels and attributes; elements added in Papyrus become new items.
Diagrams made in Papyrus stay in Papyrus (Holarch does not read the .notation file), and an import never deletes items: delete what you removed in Papyrus by hand.
Back up or move a project
- Open Manage Projects.
- Open the project's row menu ⋯ and choose Export this project….
Or, on Home, choose Home ▾ → Export Project….
- Keep Format at Holarch backup (.holarch), choose the options and click Export.
The
.holarchfile downloads. It holds the whole project and its attached files.
To restore it on any Holarch server:
- Open Manage Projects → Project Files ▾ → Import Project….
- Choose the
.holarchfile.Holarch checks every part of the file first. The import becomes a new project with a new ID, and you are its owner.
Coming from another tool
Holarch does not read other tools' own project files. Export the data from the other tool in an exchange format and import that:
- Excel or CSV for items, attributes and relationships in tables (see Import a spreadsheet).
- ReqIF for requirements with their hierarchy, attributes and links (see ReqIF).
- UML/SysML XMI for SysML 1.x models (see Import a UML/SysML model (XMI)).
Worked example: the CubeSat EO-1 demo
Create the demo with Manage Projects → Project Files ▾ → New 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 Deliver ▾ → Requirements (ReqIF)… and click Export.
The file holds the six sections and their requirements, in outline order. Numbers such as 2.1 become the foreign ID, and descriptions become XHTML.
The demo's satisfies and verified by links point to functions, assets and tests outside the document. They are not in this file. To include them, export from the Database instead (example 4).
2. Update owners in Excel.
- In the Database, search
class:Requirement. - Click Export… → Table (CSV), tick Owner and ID, and click Export.
- In the file, change the Owner of 3.1 Orbit Average Power and 3.2 Battery Capacity to "EPS Lead".
- Import the file as in Update existing entities.
Review shows both rows under Updated items, with the Owner change.
- Click Import N items.
3.1 and 3.2 show the new owner. One ⌘Z / Ctrl+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.
- Choose Export… → Matrix (Excel).
4. Exchange the trace web.
- In the Database, search
class:Requirement OR class:Action. - Click Export… → Requirements (ReqIF).
Relationships between the exported requirements and functions become SPEC-RELATIONs. An example is F8 satisfies 4.4 Downlink Encryption.
5. Back up.
- In Manage Projects, choose Export this project… on the demo.
- Keep Holarch backup (.holarch) and every option, and click Export.
The file includes the SRR Baseline, comments, history and the Home panels.
Tips and good practice
- Import a large or unfamiliar file into a test project first. Check the preview and warnings, then import into the real project.
- Number rows in outline form (1, 1.1, 1.1.1). Without a Parent column, the hierarchy comes from the numbers.
- Exported CSV descriptions are plain text. Re-importing them over formatted descriptions removes the formatting. In an update, map Description to Skip, 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 is mapped to Labels. An example is Verification Method, with values Analysis and Test.
Common mistakes
- Every row came in as New instead of Updated. The match column holds something other than the entity ID (files exported before this release could hold an
I_…value in their Global ID column). Or Match existing entities by is set to the wrong field. Map the ID column to Global ID. - The hierarchy is flat. The numbers are not in outline form, or Parent Number was not mapped. Look for 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 the Schema editor.
- Odd characters in a CSV. Choose the right Text encoding. Older Excel CSV files often need ISO-8859-1 / Windows-1252.
- Everything is in one column. The delimiter was not detected. Choose it under Delimiter.
- .xls files are refused. In Excel, save the workbook as .xlsx or .csv first.
How it connects to other features
- Imported documents open in Documents. There 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 Item View.
- Exports feed:
- Reviews: Word and Excel. Reviews bundle several outputs.
- Other tools: ReqIF, XMI from UML/SysML tools (Cameo/MagicDraw, Enterprise Architect, Rhapsody, Papyrus), and MS Project XML from the simulator.
- Backups: project JSON.
The Import page
Use the Import page to bring files into the open project. Open Needs & Requirements → Import and Export.
The page has one drop zone for every format and four steps: File → Map → Review → Import.
Below the File step, the Export card has Export Project…, which writes the whole project as a Holarch backup (.holarch) or project data (.json) that the Import page and Manage Projects read back, and Export UML/SysML (XMI)… (see Export a UML/SysML model (XMI)). Tables, diagrams, documents and matrices export from their own page with Export….
- Back and Continue move between steps. Continue stays disabled until a file or pasted text has been read.
- Import N items on the Review step runs the import, and a single Undo takes it all back.
Step 1: File
Drop a file on Drop a file here, or click it to choose one. Holarch detects the format from the file name and, where that is not enough (.xml, pasted text), from the content.
| Format | Files |
|---|---|
| Word (.docx) | .docx |
| Holarch project (.holarch, .json) | .holarch, .json |
| Excel / CSV (.xlsx, .csv) | .xlsx, .xlsm, .csv |
| Plain Text (.txt) | .txt, or pasted text |
| UML/SysML (.xmi, .uml, .mdzip) | .xmi, .uml, .xml, .mdzip |
| ReqIF (.reqif) | .reqif, .reqifz, .xml |
After reading:
- Format shows the detected format. Choose another to read the same content another way (for example text that was taken for CSV).
- Delimiter (CSV files and pasted CSV): Automatic (it names the delimiter it found, for example Automatic: Semicolon (;)), Comma (,), Semicolon (;), Tab, Pipe (|). Automatic detection compares the delimiters on the first 50 rows and ignores delimiters inside quoted fields. Changing it re-reads the rows.
- Text encoding (CSV and text files): Automatic, UTF-8, ISO-8859-1 / Windows-1252, Shift_JIS, Big5, UTF-16. Automatic detection reads byte-order marks, then UTF-8, then Shift_JIS or Big5 when the text contains Japanese or Chinese characters, then Windows-1252. Changing it re-reads the file.
- Sheet (workbooks with several sheets): each sheet with its row count. The first sheet with data is preselected.
- Paste: paste content into the text box and click Analyze Text. It accepts CSV with a header row, JSON or XML, ReqIF XML, XMI, or document text; the format is detected the same way.
- Plain text: the loaded file stays editable under Text from the file. Edit it and click Re-run Analysis.
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 with the fix.
Step 2: Map
- Word tables (Word only): see Word tables.
- Columns: one row per file column: File column (its title and position), Sample values (the first three rows; formatted cells show their text plus "[N images]" or "[N tables]") and Holarch field. auto marks a field matched from the column title (see Automatic column mapping).
- ✦ AI ▾ → Suggest mapping asks the AI for a field per column. Suggested Mapping lists each change ("Column: current → suggested" with the reason), ticked; Apply Ticked changes the ticked columns. Nothing is imported until the last step.
- Classes and matching, Numbering and the warning list ("N warnings", the first 50 and "…and N more") or "No warnings."
Holarch field values:
| Group | Field | Meaning |
|---|---|---|
| Skip | Not imported. | |
| Item | Name, Number, Description | The item's own fields. |
| Item | Class | The class name (matched ignoring case, spaces and punctuation). |
| Item | Labels | Label names separated by ;, ,, a vertical bar or line breaks. |
| Item | Parent number | The number of the row's parent. |
| Item | Global ID | The ID used to match existing entities. |
| Attributes | an attribute of the class for rows without a class | Quality, file and computed attributes cannot be imported. |
| Relationships | a relationship | Values are target names, numbers or IDs separated by ; or line breaks. A value written as <number> <name> (as Holarch's own CSV and Excel exports write related items) also finds its target. |
| Structure | Row ID | An ID used inside the file (ReqIF, XMI). |
| Structure | Parent row ID | The Row ID of the parent. |
| Structure | New attribute (added to the schema) | Creates an attribute named after the column on each imported class (see New attributes). |
Classes and matching:
| Option | Values and effect |
|---|---|
| Class for rows without a class | Any creatable class; default Requirement. Used when no Class column sets the class and no class rule applies. |
| Class rules | Description contains a word or phrase → a class; + Rule adds one, × removes one. Used only for rows whose class is not set by a Class column; the first matching rule wins; matching ignores case. |
| Match existing entities by | Global ID (default), Name or Number. See Matching existing entities. |
| Match related entities by | Global ID, Name or Number (default): how values in relationship columns find their targets. |
| Date format of date columns (CSV) | Automatic, yyyy-MM-dd HH:mm:ss, dd/MM/yyyy, MM/dd/yyyy, yyyyMMdd, Custom… (tokens yyyy, MM, dd, HH, mm, ss, for example dd.MM.yyyy HH:mm). |
For project files, Map shows Import options instead: Include Comments (on), Include History (off), Include Diagrams (on), Add schema items from the file that this project lacks (classes, attributes, relations, labels) (on), Schema without entities (off), and Class for items without a known class. Imported entities get new IDs in this project.
Numbering pattern
For plain text and Word, the Numbering pattern decides how numbered lines become the hierarchy. Write one marker per level, separated by spaces, or one path number:
| Pattern | Reads |
|---|---|
| empty | Automatic: numbered headings and "shall" statements (for Word, the file's heading styles and list numbering). |
1. | 1. 2. 3. |
1. a) (i) | 1. at the top, a) under it, (i) under that. |
I. A. 1. a) | Roman, letter, number and letter levels. |
1.1 or 1.1. | Outline numbers 1, 1.1, 1.1.1 (with or without a final period). |
1.1.a, A.1 | Path numbers whose parts change type by level; deeper levels repeat the last type. |
Markers are a number (1), a letter (a, A), or a Roman numeral (i, I), followed by a period, a closing parenthesis, or nothing, or written in parentheses ((1)). Up to 6 levels.
For plain text, Holarch detects the pattern from the markers at the start of the lines (lettered, Roman and parenthesized schemes; plain and outline numbers are read by the automatic mode) and fills the field: "Detected from the numbering in the text: …". Change it if it is wrong; clear it for automatic.
With a pattern, Holarch reads each line like this:
- A 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 item's name.
- A longer line becomes the description, and the name is made from it.
- A line that matches no level continues the previous item's description.
All items get the class for rows without a class.
Number children under their parent (1 → 1.1): on, generated child numbers include the parent's number (3.1); off, they count from 1 within the parent.
Note: For Word, a pattern reads the file as plain text. Heading styles, formatting, pictures and tables are then not used. Clear the pattern to use them again.
Automatic column mapping
| Column title (any case; spaces and punctuation ignored where noted) | Maps to |
|---|---|
| Number, No, Num, #, ID Number, Req Number, Requirement Number; Object Number, ReqIF.ChapterName, ReqIF.ForeignID | Number |
| Name, Title, Short Name, Requirement Name; Object Heading, ReqIF.Name, Long Name | Name |
| Description, Text, Requirement, Requirement Text, Statement, Desc; Object Text, ReqIF.Text, ReqIF.Description | Description |
| Class, Type, Entity Class, ClassName; ReqIF.Category | Class (only one column: in a CSV or Excel file with a Class column, a Type column maps to the Type attribute) |
| Labels, Label, Tags; the name of a label group such as Verification Method (also "Method", "Verification", "Verification Methods") | Labels |
| Global ID, ID, GUID, UUID; Object Identifier, Origin ID | Global ID |
| Parent, Parent Number | Parent number |
| ReqIF ID, XMI ID, Row ID | Row ID |
| Parent ID | Parent row ID |
| The name of an attribute of the class for rows without a class, or of any class | That attribute |
| The name of a relationship (for example "satisfied by") | That relationship |
| Anything else | Skip (ReqIF and XMI: New attribute) |
Step 3: Review
Check what will change before anything changes. Review uses the same compare view as Baselines & Versions (see Baselines and version comparison):
- The first line names the file, the format and the item count per class.
- Create a requirements document from these N requirements (when every item is a Statement or Requirement, or a subclass; ticked by default), or Create a document from these N items (unticked by default). Ticked, it shows Document type (the Artifact labels ending in "Document", default Requirements Document), Name (default: the file name) and Renumber the whole document after import (off). The document becomes the source of the top-level items.
- For UML/SysML, the model report (relationships, action diagrams, what is not imported).
- The warning list.
- Tiles: New items, Updated items, Matched, unchanged and Relationships from the file.
- The change table: each new item (New) with its description, and each changed field of an updated item (Updated) with a word diff of the old and new value. It shows the first 500 changes.
Import N items runs the import. The toast reads "Imported N new, N updated".
Step 4: Import
The result screen, Import Complete, appears only when the import produced warnings. It shows "N entities created, N updated, plus the document “name”." and the warnings.
Its buttons: Open Document, Open Database, Spider Diagram, Tree Diagram, Check Quality and Start Another Import.
A clean import skips this screen. It goes straight to the new document (for requirements documents) or to the Database.
Large imports on the hosted service
On the hosted service, an import of 5,000 items or more (rows of a spreadsheet, text or Word file, ReqIF, XMI or a Holarch project file) is written by the server in one step instead of being sent item by item from your browser.
- Go through File, Map and Review as for any import.
- Click Import N items.
Your browser maps, numbers and matches the items exactly as for a small import, then uploads the changes once. The page shows Import Sent to the Server with the counts and the warnings.
- Follow the progress card at the bottom of the window: it shows the stage (uploading the changes, waiting for the server, checking the changes, applying the import, updating the project index), the count while the changes are checked and applied (for example "40,000 of 99,990"), and the time left.
Until the import is applied, the project shows its state before the import. You can leave the page or close the tab: the import continues on the server. Every open copy of the project reloads when it is applied.
- Other members see "Name is importing file…" in the same card and on the Import and Export page.
- Waiting for room: a very large import needs a lot of server memory while it is applied. When the servers are busy, the card shows Waiting for free server memory… or Making room on the server… and the import starts as soon as there is room. It keeps waiting if you close the tab or sign out.
- When it ends: if you are using Holarch (on any page), a message tells you the import finished. If you closed the tab, or Holarch has been in the background with no activity for about 10 minutes, you get an email instead. You get one or the other, never both.
- No room: if no server has room for the import within about 30 minutes, it does not run and nothing is changed. The message says so and the Holarch team is notified. Try again later, or import fewer items at once.
- One import at a time: one server import runs per project, and one per person.
- Cancel Import (the person who started it, or an owner) stops the import before it is applied, also while the card reads "Applying the import…". Nothing is changed.
- Undo Import: ⌘Z / Ctrl+Z in the browser does not take back a server import. Click Undo Import on the Import and Export page to return the project to its state before the latest import. The state before the undo is kept in History, so edits made after the import can be recovered from there.
- Project Activity and History list the import as one entry by the person who started it.
- The local app and smaller imports apply the import in your browser, and a single Undo takes it all back.
Format details
Word (.docx)
- Headings become Statements, nested by level. Headings are Word's Heading 1 to Heading 9 styles, styles based on them, and paragraphs with an outline level. They are numbered with the file's list numbering, or with generated numbers. The Title style is skipped.
- Requirements: two kinds of paragraph become a child item of the current heading. One contains "shall", "must", "will" or "should". The other is a numbered (not bulleted) list item.
- With one of those verbs, the item is a Requirement. Otherwise it is 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. Pictures above the per-file limit are skipped too.
- 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 Skip.
- Columns titled ID, Req ID, Requirement ID, Req No, Req Number, Identifier, Ref, Reference, Paragraph or Para map to Number.
- Columns titled 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.
Holarch proposes Entities (one per row) for a table that has all of these:
- At least two columns, and data rows.
- A Name or Description column.
- 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: Holarch reads shared and inline strings, numbers, booleans (TRUE/FALSE) and dates. Dates follow the cell's number format and are read as
yyyy-MM-ddoryyyy-MM-ddTHH:mm. Multi-line cells keep their line breaks. Leading and trailing empty rows are dropped. - CSV: comma-, semicolon-, tab- or pipe-separated (detected, or chosen under Delimiter), with double quotes around fields that contain the delimiter, quotes or line breaks. A byte-order mark at the start is ignored.
- Several columns with the same title (Holarch's Table (CSV) export writes one Status, Value or Units column per class that has the attribute) map to the same field. Each row takes the value from the column that has one: an empty cell never clears a value that another column of the same row set.
- A file exported by Holarch imports back with its classes (including Port), attribute values, labels and relationships.
- Decimal commas: in a semicolon-separated file (the CSV format of Excel in German, French, Dutch, Italian and other locales), numbers such as
1,5or1.234,5in Number, Percent, Quality Score and Duration attributes are read as 1.5 and 1234.5. In comma-, tab- or pipe-separated files the comma is not a decimal mark. - The other CSV imports (Import CSV… on an XY chart, Import Review Comments, matrix Import…) detect the delimiter and encoding the same way; the XY chart also reads decimal commas from semicolon files.
- Encodings: UTF-8 (with or without a byte-order mark), UTF-16, Windows-1252 / ISO-8859-1, Shift_JIS and Big5, detected or chosen under Text encoding.
- Excel 97-2003 (.xls) is not supported, also when renamed to .csv. In Excel, save the file as .xlsx or .csv, then import it again.
Plain text
With Auto, Holarch reads each line like this:
- Leading
-,*or•bullets are removed. - A leading number such as
3.2,3.2.orSYS-3.2is 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,.2added. - Unnumbered requirements are numbered under the current heading.
ReqIF
ReqIF (Requirements Interchange Format) is the standard exchange format of requirements tools such as DOORS, Polarion and Codebeamer. Export a specification from the other tool as .reqif or .reqifz and import it here; Export… → Requirements (ReqIF) (Database reports) goes the other way. In a Holarch to ReqIF to Holarch round trip of the CubeSat EO-1 demo, all 407 items and 979 attribute values came back unchanged (round trips).
- Every SPEC-OBJECT becomes a row with these columns:
- ReqIF ID (mapped to Row ID).
- Parent ID (mapped to Parent Row ID, from the SPECIFICATION hierarchy).
- Type (mapped to Class, from the SPEC-OBJECT-TYPE name).
- Long Name, when no attribute looks like a name or title.
- One column per attribute definition: string, XHTML, Boolean, date, enumeration, integer and real.
- XHTML values become rich text. Enumeration values are joined with "; ".
- A Labels attribute (Holarch's export writes one) maps to Labels. In a file exported by Holarch, labels the project does not have yet are added to it.
- A class name from the file is matched to any Holarch class, including Port.
- Columns that do not match an attribute default to New attribute (added to the schema) instead of Skip.
- SPEC-RELATIONs become relationships named by their relation type (its long name). The SPEC-RELATION's source is the link's source.
- The SysML names map like this: satisfy → satisfies, verify → verifies, deriveReqt → traced from, and trace, refine, copy, Dependency and Abstraction → traced to.
- Any other name is matched to a Holarch relationship name, with
_and-read as spaces (for examplesatisfied_by). - When the name is unknown, or the schema does not allow it between the two classes, traced to is used.
- When traced to is not allowed either, the relationship is skipped with a warning.
- Attribute values on a SPEC-RELATION set the relationship's attributes of the same name (for example Trigger on receives, Amount on consumes).
- .reqifz archives are unpacked and their .reqif file is read.
- Each item keeps its SPEC-OBJECT identifier. Both ReqIF exports (Export… → Requirements (ReqIF) and the document's Deliver ▾ → Requirements (ReqIF)…) write it back as the SPEC-OBJECT identifier; items without one are written under their own ID. Two items that share an identifier (a copy) write it once; the other gets its own ID.
- Re-importing a newer file from the same tool updates the items with those identifiers, whatever Match existing entities by says, so a round trip with another requirements tool updates instead of adding copies. The Map step notes this under the matching choice.
- A ReqIF file exported by Holarch and imported into the same project updates the items it came from.
- In a SysML v2 project, ReqIF files import on Model → Import and Export and become SysML v2 requirements, packages and relationships; see Import and export ReqIF requirements.
UML/SysML (XMI)
The UML/SysML (.xmi, .uml, .mdzip) format reads OMG XMI 2.x files with UML 2.5 and the SysML 1.x profile, from tools such as Cameo/MagicDraw, Enterprise Architect, Rhapsody and Papyrus, and Eclipse UML2 .uml files with the Papyrus SysML 1.6 profile. For a .mdzip file, Holarch reads the largest UML model inside the archive.
Elements map by type and stereotype. The full table is in Import a UML/SysML model (XMI). In short:
| Element | Class |
|---|---|
| «requirement» and its SysML kinds | Requirement (its Id becomes the number and its Text the description) |
| «testCase» | Test Case |
| Class, «block», Component, Node, Device, Execution Environment, Actor | Asset |
| Activity, action, opaque behavior, use case | Action |
| Signal | Input/Output |
| State, final state, initial and history pseudostates | Characteristic labelled State |
| Transition | Transition |
| Value property | Characteristic |
Packages and models are not imported as items: they fill the Package attribute. Ports become Port items on the blocks that own them, and connectors connect them. Nesting of the same class becomes the hierarchy. Comments, documentation and «rationale» join the description.
Dependencies. Each Dependency, Abstraction, Realization or Usage becomes a link from its client (source) to its supplier (target). The stereotype decides the type:
| Stereotype | Holarch relationship (client → supplier) |
|---|---|
| «satisfy» | satisfies |
| «verify» | verifies |
| «deriveReqt» | derives (the client requirement is derived from the supplier) |
| «refine» | refines |
| «copy» | copies |
| «trace» | traced to |
| «allocate» | performs when it allocates an Action to an Asset (the Asset performs the Action; allocated to in files Holarch wrote for that relationship); otherwise traced to |
| No stereotype | refines for a Realization; traced to for a Dependency, Abstraction or Usage |
Enterprise Architect connectors that carry the stereotype only in their extension data map the same way, except that «allocate» always becomes traced to.
When the schema does not allow the mapped type between the two classes, traced to is used instead. When traced to is not allowed either, the link is skipped with a warning. traced to starts only at a Statement or Requirement, so a «refine» or «trace» from a block or use case to a requirement is skipped. The Relationship reference lists which classes each type connects.
Holarch project files (.holarch, .json)
The Holarch project (.holarch, .json) format merges entities from a Holarch file into the open project:
- Holarch backups and packages (.holarch), from Export Project… or the Project package (.holarch) export. Holarch checks the file before anything changes (see Holarch backup format); attached files in it are put back on their items.
- Holarch project exports, Database JSON exports and document exports (Document data (JSON)).
When the file's schema differs from the project's, classes, attributes, labels and relationships are matched by name.
- Add schema items from the file that this project lacks… (on) adds missing classes, relations, attributes and labels first: "Schema: added N class(es), relation(s), attribute(s) or label(s) from the file."
- Schema without entities imports only the schema.
- Comments, history and diagram layouts come along when their options are on. Project-level views in the file (Home, Charts, the program dashboard, settings) are added only where the open project has none of that kind; the project's own are kept.
- Simulation scripts in the file are marked as imported. The simulator asks before running them.
Note: To restore a whole project as a separate project, use Manage Projects → Project Files ▾ → Import Project… instead. The Import page merges into the open project. A backup of a SysML v2 project is imported only there.
Matching existing entities
Use matching to update entities instead of creating new ones. A ReqIF import first matches items by their ReqIF identifier (see ReqIF). Match existing entities by has three values:
- Global ID compares the column mapped to Global ID with the entity's ID. The ID is shown in the inspector's Details and written by the ID and Global ID options of the reports. An
I_…value from a file exported before this release does not match. Without a Class column, a matched entity keeps its class. - Name matches an existing entity of the same class with that name.
- Number matches an existing entity of the same class with that number.
A matched row updates only the mapped fields:
- Unmapped Name, Number or Description keep their values.
- Mapped attributes are written.
- Labels are added to the existing labels.
- The class changes only when the file has a Class column.
Hierarchy
Holarch finds each row's parent from the first of these that is set:
- Its Parent Row ID.
- Its Parent Number.
- Its own number. The parent of
1.2.3is1.2. If1.2is not in the file, it is the nearest existing ancestor, such as1.
Rows without a parent become top-level items of the new document. Parents are linked with decomposed by.
Value conversion
| Attribute type | Accepted values |
|---|---|
| Number | A number (a trailing % is ignored) or a distribution such as normal(10, 2) |
| Percent | A number, with or without % |
| Date and time | Per Date format of date columns |
| Duration | A number and a unit (5 days, 90 min; Seconds to Years; default Hours) or a distribution |
| Boolean | true, yes, y, 1 or x for true; anything else is false |
| Enumeration | One of the choices (ignoring case); other text is kept as typed |
| Multi-select | Values separated by ;, ,, a vertical bar or line breaks, matched to the choices |
| Geo point | latitude, longitude |
| Text and rich text | As is |
Values that cannot be converted are left out with a warning.
New attributes
A New Attribute column becomes an attribute named after the column. It is added to each class that receives a value. An existing attribute of the same name is reused.
The type is chosen from the data, first match wins:
- Rich text for ReqIF XHTML.
- Number when every value is numeric.
- Enumeration, with the values as choices, for ReqIF enumerations. Also for up to 12 short distinct values used by fewer than half the rows.
- Long text when a value exceeds 120 characters.
- Otherwise text.
Other imports
| Import | Where | Details |
|---|---|---|
| Import Project… | Manage Projects → Project Files ▾ | A Holarch backup (.holarch) or project export (.json) becomes a new project with a new ID, owned by you; its folder in Manage Projects is restored. A backup is checked first (see Holarch backup format). "Import failed: Not a project export" when the file has no entities. |
| Import Schema… | Settings → Schema in the rail (top bar) | A schema export or a project export. Shows the counts of classes, relations, attributes and labels; Mode: Merge (add the classes, attributes, relations and labels this project lacks, matched by name) or Replace this project's schema. Errors: "Not a JSON file." and "This file is not a schema: it needs classes, relations, attributes and labels." See Schema extensions. |
| Import… (matrix) | Verification → Traceability Matrix | A Matrix (Excel) workbook edited in a spreadsheet, or an earlier matrix CSV: Import Matrix lists the links to add, the links to remove and the skipped cells with their reason before Import. See Traceability. |
| Pictures and files | Rich text + → Image… / File…, entity images, file attributes, whiteboard Insert Image…, slide images | Images over 4,000 px on the longest side are reduced; files over the per-file limit are refused. |
| Graphics for DoDAF products | Frameworks → DoDAF | PNG, JPEG or SVG graphics for a product. |
| Java source | SysML block diagrams | Import Java… → Choose .java File… reads classes into blocks. |
| AI reference files | AI Settings… (account menu), Project reference files for AI | .txt, .md, .csv, .json, .xml, .html, .docx and .reqif; text only, up to 200,000 characters per file. |
Exports
Project export
Use a project export for backups and for moving a project to another server. Open Export Project from Export this project… (Manage Projects row menu) or Home ▾ → Export Project… (Home).
- File name: the default is the project name with spaces as
_. - Export Options (all on):
- Include Baselines.
- Include Comments.
- Include History: also includes deleted entities that can be restored.
- Include Project Preferences (Home panels, charts, slides).
- Format:
- Holarch backup (.holarch) (default): the project and its attached files in one file, checked for damage when it is imported. See Holarch backup format.
- Project data (.json): the project JSON for scripts and other tools. Attachments and pictures are embedded in the file as text.
- To export only the schema, use Export Schema in the Schema editor.
- Export downloads
name.holarchorname.json. Both are self-contained and work for SysML v2 projects too.
When saving fails and the browser cannot keep a copy, the save banner offers Download a copy. It downloads the full project as project data (.json).
Database reports
Use Database reports to export any set of entities. Open them from:
- Export… on the Database page header. It exports the selected rows, or on every entity of the current query when nothing is selected.
- More ▾ → Export… on the bulk bar, for the selection.
- Export… in the Item View, for the one entity.
The Export dialog shows the entity count, Export as (the choices grouped by output: Word, Excel, CSV, Exchange, Print), the options and File name. Export downloads the file.
| Export as | Output | Options |
|---|---|---|
| Table (CSV) | Number, Name, Description, Class, the chosen attributes, one column per relationship type, the chosen extras | Include attributes (each attribute of the listed classes); Include: Comments, Created On, Entity URL, Global ID, ID, Labels (on), Modified On, Relationships, Rich Text (descriptions as HTML instead of plain text), Locked; Sort By: Number, Class, ID, Name, Hierarchical; Marking as the first line when the project has a marking |
| Table (Excel) | The Database's current columns, with a Level column | Freeze header row (on), Hierarchy (children under their parents), Unmerge cells, Rollup (sum number and duration columns up the hierarchy) |
| Definitions (Excel) | Entity, Field, Value: class, number, name, description, labels, every attribute and every relationship type per entity | Freeze header row (on), Global IDs, Id, Unmerge cells |
| Relationship matrix (Excel) | Entities × related entities for one relationship; empty cells are left out of the file. A matrix wider than 16,384 columns or longer than 1,048,576 rows (Excel's limits) is not exported: the dialog says so and points to Relationships (CSV) | Relationship, Show in cells (X (no attribute) or a relationship attribute), Freeze header row (on), Shade cells (on), Global ID |
| Relationships (CSV) | One row per relationship: Source Number, Source Name, Source Class, Relationship, Target Number, Target Name, Target Class, Attributes | Relationship (one or All relationships), Marking as the first line (when a marking is set) |
| History (Excel) | One row per recorded change: Date, ID, Global ID, Entity, Version, Change, Field, From, To | Freeze header row (on), Global ID, ID (on), Version Number (on) |
| Comments (Excel) | Class, Name, Number, Description, Comment, Author, Date, Resolved | none; offered when the entities have comments |
| Breakdown (Word) | One entity's decomposition as headings, with descriptions and diagram pictures and a contents table | Diagrams (diagram types; Hierarchy on); offered for a single entity |
| Project data (JSON) | A holarch-project file with the entities and their relationships | Include Related Items, Include Comments (on), Include History, Include Diagrams (on), Include Schema, Schema without entities |
| Project package (.holarch) | A Holarch package of the chosen entities with their relationships, diagrams, comments and the schema, and every attached file and picture. Import reads it back into any project. A package of every item in the project also holds the project-level views: Home, Charts, the program dashboard, and the Intelligence, preference, budget and architecture settings | none |
| Requirements (ReqIF) | ReqIF 1.2: one type per class with Number, Name, Description (XHTML), Labels and every attribute (enumerations as ReqIF enumerations), relationships other than decomposed by as SPEC-RELATIONs with their attribute values (Trigger, Amount, Origin …), the decomposition as the hierarchy | none |
| Table (Print) | The browser's print dialog | none |
Errors during an export show "Export failed: … Check the options, then export again."
Document reports
A document's Deliver ▾ → All Exports… offers:
- Document (Word) and Outline (Word).
- Table (CSV), Comments (Excel) and Quality findings (Excel).
- RVTM, VCRM, RVM, RTM, RSM and TVM (Excel), and Traceability matrix (Excel, Word, CSV or HTML).
- Requirements (ReqIF).
- Changes (Excel), from a baseline to a later baseline or the current version.
- Document (Markdown), Document data (JSON) and Document (Print or PDF).
Documents → Reports describes each one with its options.
Diagram exports
Every diagram editor's Export… opens the Export dialog with:
| Item | Output |
|---|---|
| Diagram (PNG) | The diagram at the chosen Scale (default 2×) on a white background; Transparent background leaves it out ("name (transparent).png") |
| Diagram (SVG) | Scalable vector image |
| Diagram (HTML) | A page with the title, description and the diagram image |
| Diagram (Word) | A Word file with the diagram, a caption and the description |
| Type-specific items | For example Network metrics (CSV) on Asset diagrams |
| Diagram (Print) | The browser's print dialog |
To report on many diagrams at once, click Diagram Report… on the Diagrams page. Diagrams Report covers every diagram in the current filter and sort.
- Fields: Name, Number, Description and Diagram Type are on; Created On and Modified On are off. The image is always included.
- File name: up to 100 characters.
- Format: Word (DOCX) or Web Page (HTML).
Run Report builds it ("Creating the report…", then "Downloaded the report"). Messages: "Enter a file name.", "The file name is longer than 100 characters. Shorten it.", "No diagrams to report."
Traceability matrix exports
Export… in the matrix opens the Export matrix dialog:
- Matrix (Excel): an .xlsx workbook. The Matrix sheet shows the grid with a fill per link state; the Holarch matrix sheet holds the view (relationship, setup, row and column IDs), so the edited file can be imported back with Import….
- Matrix (CSV): X marks, or the relationship names when the cells show them.
Save view… saves the matrix settings as an Artifact labeled Matrix.
Each file export takes its File name in the dialog.
Baselines and versions
In Control & Reviews → Baselines & Versions:
- Each baseline row has Export. It downloads a
holarch-baselineJSON file with the name, date, document, approvals and snapshot. - Compare shows the changes between two versions. Export CSV and Export XLSX write the columns Number, Name, Class, Change Type, Field, Old Value and New Value. In projects of more than 5,000 items the comparison runs when the page opens or you pick other versions, with the progress card; after an edit it says "The project changed after this comparison." with Refresh.
Schema export
Export Schema in the Schema editor downloads "<Project_name>_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, or frames. Several images (one per board or frame) download together as one ZIP file.
- Scale (PNG, JPG): 0.5× to 4×.
- Quality (10–100) (JPG).
- Resolution (PDF): Standard (96 dpi) or Print (300 dpi). The PDF has one page per board or frame, as images.
- Transparent background (PNG, SVG).
The dialog notes "SVG keeps shapes and text editable in vector tools." (SVG) or "Several boards or frames are saved together as one ZIP file." (PNG, JPG). The settings are remembered in this browser. With nothing to export: "Nothing to export. Add elements or choose another area."
Exports on other pages
| Page | Control | Formats |
|---|---|---|
| Requirements Quality | Export ▾ | Excel (.xlsx), CSV; the results dialog has Export CSV and Export XLSX |
| TBD/TBR | Export XLSX | Number, Name, Document, Type, Source, Owner, Due Date, Opened, Age (days), Overdue, Description |
| RVTM | Export ▾ | RVTM (CSV), RVTM (Excel), RVTM (Word) |
| Test Center suite menu | Test Cases (Word)…, Export CSV, Export JSON | Test cases with set-up, expected and actual results, status and verified requirements |
| Interface Register | Export | CSV of interfaces, endpoints, status, owner, items and requirements; ICD per interface (Word) |
| Interface (physical) diagrams | ICD outputs | ICD document (Word) and ICD table (CSV); interface register (CSV) |
| N² and I² matrices | Export | CSV |
| Budgets & TPMs | Export XLSX | Budget workbook; TPM report with Status, Planned Profile and History sheets |
| Functional Analysis | CSV, XLSX, Copy on each table; report | Tables as CSV, XLSX or Word; Copy puts the table on the clipboard for Word or Excel; FFBD as PNG; full report as DOCX |
| Risk Register | Export | Excel (XLSX), CSV |
| Trade Studies | Export ▾ | Excel Workbook (.xlsx), Word Summary (.docx) |
| Simulator | Panel ⋯ → Download image… and ⋯ → Download data… | The image as PNG (with Transparent background and Scale) or SVG, named "<root> <panel>"; the panel's data, such as Timeline (CSV), Event log (CSV), Console (CSV), Runs (CSV) and Schedule (MS Project XML) |
| Charts | Dashboard chart ⋯ → Export… | Chart (PNG) (with Transparent background and Scale), Chart (SVG), Data (CSV), saved under the chart's title; chart editors have Export… with Chart (PNG) (with Transparent background), Chart (SVG), Chart (Word), Chart (HTML) and Data (CSV) |
| Presentations | Export… | Current slide (PNG) (with Transparent background and Scale), Current slide (SVG), Presentation (HTML), Presentation (PowerPoint), Presentation (Word) |
| DoDAF | Export menu | Architecture Package (Word), DoDAF Products (JSON), DM2 PES Subset (XML, not schema-validated); resource flows and rules as CSV or XLSX; AV-2 dictionary as CSV or XLSX |
| Home panels | Panel ⋯ → Export… | Saved view Table (CSV), Breakdown Chart (SVG) and Chart (PNG), Pinned item Picture (PNG) |
| Gallery cards | Card ⋯ → Export ▸ | Picture (PNG); diagrams also Vector picture (SVG); presentation cards offer Web page (HTML) and Presentation (PowerPoint) |
Holarch backup format
A .holarch file (a Holarch backup from Export Project…, or a package from Project package (.holarch)) is a ZIP archive:
| Entry | Content |
|---|---|
manifest.json | "format": "holarch-package", "formatVersion": 1, the Holarch version that wrote it, "scope" (project for a whole project, items for a package of chosen items), "language" (lml or sysml2), the project's id and name, counts (entities, relationships, model elements, diagrams, comments, baselines, history records, attachments), and the size and SHA-256 checksum of every other entry |
project.json | The project JSON. Attached files and pictures of 1 KB or more are replaced by holarch-file:<name>?<type> references |
files/<name> | The attached files; <name> is the start of the file's SHA-256 checksum and an extension |
On import, Holarch checks the manifest, the format version and every checksum before anything changes, then puts the attached files back. A version of Holarch reads every earlier format version.
| Message | Fix |
|---|---|
| "This backup was made by a newer version of Holarch (package format N). Update Holarch, then import it again." | Import it into a newer Holarch. |
| "The backup is damaged: … does not match its checksum." / "… is missing." | The file was changed or cut short. Use another copy, or export the project again. |
| "This file is not a Holarch backup: …" | The file is another ZIP file or has no valid manifest. Choose a .holarch file. |
Project JSON format
A project export is one JSON object:
{
"format": "holarch-project",
"version": 1,
"schemaIds": 2,
"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).
relIdreads 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. schemais present when the project's schema differs from the default.schemaIds: 2marks the current numbering of built-in schema ids. Built-in classes are numbered from 1100001, relations from 1200001 (a relation and its inverse take consecutive ids), attributes from 1300001 and labels from 1400001. Classes, relations, attributes and labels you add get ids below 1000000. Files without the marker use the earlier numbering; Holarch converts them when it opens or imports them.- In scripts and other tools, look up schema items by name, not by number.
- Project preferences such as the Home panels and charts are stored under
diagrams(__home,__charts; a dashboard from an earlier version stays under__dashboard).
Related formats:
- The Database JSON export uses the same format, with only the chosen entities.
- A document export uses
"format": "holarch-document", withdocId,entities,relationships,docStateand the optionalcomments,baselinesandhistory. - 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 / Ctrl+Z undoes a whole import. See Keyboard shortcuts.
Messages
Import errors (shown in the File step as "Could not read the file: …")
| Message | Fix |
|---|---|
| "No data rows were found." | The file or sheet has only a header, or the wrong sheet is chosen. |
| "Excel 97-2003 (.xls) files are not supported. In Excel, save the file as .xlsx or .csv, then import it again" | Save as .xlsx or .csv. |
| "XML with a DOCTYPE or ENTITY declaration is not accepted. Save the file without it and import it again" | Remove the declaration. |
| "invalid XML" | The file is not well-formed XML. |
| "the XML is larger than 100 MB" / "the XML has more than 3,000,000 elements" | Split the file. |
| "the file is not a ZIP archive" / "the archive is damaged" | The .docx, .xlsx or .reqifz file is broken. |
| "the archive has more than 10000 files" | Too many entries in the ZIP. |
| "name is larger than 300 MB when unpacked" / "the archive is larger than 600 MB when unpacked" | The archive is too large. |
| "name is compressed more than 400:1, which is typical of a zip bomb" / "name unpacks to more data than allowed (zip bomb protection)" | The archive was refused for safety. |
| "the file has no Word document part (word/document.xml)" / "xl/workbook.xml not found" / "the workbook has no worksheets" | The file is not a valid Word or Excel file. |
| "the file holds no project data" | The file is not a Holarch project file. |
| "Import failed: …" (toast) | The import stopped; nothing was changed. |
Import warnings
| Warning | Meaning |
|---|---|
| "No column maps to Name or Number. Map one of them." | Map at least one of them. |
| "Row N: unknown label "X" ignored." | The label does not exist in the schema. |
| "Row N: unknown class "X", using C." | The class name is unknown or abstract; the default class is used. |
| "Row N: "A" does not apply to class C." | The attribute belongs to another class; the value is skipped. |
| "Row N: "v" is not a valid type for "A"." | The value could not be converted. |
| "Row N: Name is longer than 255 characters and was shortened." / "…Number is longer than 255 characters…" | The text was cut to 255 characters. |
| "Duplicate number X (rows a and b)." | Two rows share a number; the hierarchy may attach to the first. |
| "Row N: parent X not found." / "Row N: parent number X not found." | The Parent Row ID or Parent Number does not exist in the file. |
| "Row N: missing parent number X for Y; attached to Z." / "…; imported at top level." | The number's direct parent is missing. |
| "Row N: "rel" target "t" not found." | No entity matches the relationship value. |
| "Row N: "rel" from A to B is not allowed by the schema (created anyway)." | The link was created although the schema does not list it. |
| "Relationship "type" between A and B is not allowed by the schema; skipped." | A ReqIF or XMI link could not be created. |
| "Image name: .ext images are not supported and were skipped. Save the picture as PNG or JPEG in Word to keep it." | Unsupported picture format in Word. |
| "Image name is missing from the file and was skipped." / "Image name (size) exceeds the limit attachment limit and was skipped." | The picture is missing or too large. |
| "name: N attribute value(s) had no matching attribute in C." | Project file values without a matching attribute. |
| "Skipped a relationship whose ends or relation were not found ("rel")." | A project file relationship has an unknown end or type. |
| "Schema: added N class(es), relation(s), attribute(s) or label(s) from the file." | Information: the file's schema was merged. |
Limits
Limit: Attached files and images are limited by the server's per-file limit (10 MB on the Free plan, 25 MB on Individual, 100 MB on Team) and the project's storage limit (100 MB on the Free plan). Images over 4,000 px on the longest side are reduced. Your server administrator may set other values.
Limit: XML imports are limited to 100 MB and 3,000,000 elements.
ZIP-based files (including .holarch backups) are limited to 10,000 entries, 300 MB per entry, 600 MB unpacked in total and a 400:1 compression ratio.
Limit: Imported names and numbers are cut to 255 characters. The import preview shows the first 500 rows and the first 50 warnings; all rows are imported.
Limit: XLSX cells hold up to 32,000 characters and sheet names up to 31; longer text is cut.
Limit: Excel 97-2003 .xls files and semicolon-separated CSV files are not read. Word pictures in EMF, WMF or other formats are skipped.
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.