Holarch

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.

How to use it →

On this page
  1. Concepts
    1. Import paths
    2. What every import does
    3. What exports produce
  2. How to use it
    1. When and why
    2. Import a Word specification
    3. Import a spreadsheet
    4. Update existing entities from a spreadsheet
    5. Import a PDF specification
    6. Import an Excel workbook as a spreadsheet
    7. Export a spreadsheet to Excel or CSV
    8. Import a UML/SysML model (XMI)
    9. Export a UML/SysML model (XMI)
    10. Round trip with Papyrus
    11. Back up or move a project
    12. Coming from another tool
    13. Worked example: the CubeSat EO-1 demo
    14. Tips and good practice
    15. Common mistakes
    16. How it connects to other features
  3. The Import page
    1. Step 1: File
    2. Step 2: Map
    3. Numbering pattern
    4. Automatic column mapping
    5. Step 3: Review
    6. Step 4: Import
    7. Large imports on the hosted service
  4. Format details
    1. Word (.docx)
    2. Word tables
    3. Excel and CSV
    4. Plain text
    5. ReqIF
    6. UML/SysML (XMI)
    7. Holarch project files (.holarch, .json)
    8. Matching existing entities
    9. Hierarchy
    10. Value conversion
    11. New attributes
  5. Other imports
  6. Exports
    1. Project export
    2. Database reports
    3. Document reports
    4. Diagram exports
    5. Traceability matrix exports
    6. Baselines and versions
    7. Schema export
    8. Whiteboard export
    9. Exports on other pages
  7. Holarch backup format
  8. Project JSON format
  9. Keyboard shortcuts
  10. Messages
    1. Import errors (shown in the File step as "Could not read the file: …")
    2. Import warnings
  11. Limits
  12. 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 haveWhere to import itResult
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 -5 stay numbers.
  • 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-dd dates, . 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 as Fahrzeugprü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

  1. Open Needs & Requirements → Import and Export.
  2. 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).

  3. Click Continue.
  4. Under Word tables, set each requirements table to Entities (one per row) and map its columns.
  5. Set every other table to Table in the description.
  6. Leave Numbering pattern empty. Word heading styles and Word list numbering are used automatically.
  7. Read the warnings, then click Continue.
  8. In Review, keep Create a requirements document from these N requirements ticked, with Document type: Requirements Document, and check the Name.
  9. Check the new items and their descriptions.
  10. 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:

  1. Open Needs & Requirements → Import and Export and drop the file (.xlsx or .csv).
  2. For a workbook with several sheets, pick the Sheet. For a CSV file, check the Delimiter and the Text encoding.
  3. Click Continue.
  4. 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.

  5. Choose the Class for rows without a class, and for a CSV the Date format of date columns.
  6. Click Continue to review.
  7. Tick or untick Create a document from these N items.
  8. 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.

  1. In the Database, filter to the entities (for example class:Requirement).
  2. Click Export… and choose Table (CSV).
  3. Tick the attributes to edit (for example Owner).
  4. Under Include, tick ID.
  5. Click Export.

    The CSV file downloads.

  6. Edit the values in the spreadsheet. Do not change the ID column.
  7. In Import, drop the edited file and click Continue.
  8. In Map, check that the ID column maps to Global ID, and set Match existing entities by to Global ID.
  9. Set Description to Skip, unless you edited it (see the tip below).
  10. If you exported the Global ID column too, set it to Skip.
  11. Click Continue.

    Review counts the matched rows under Updated items and lists each changed field with its old and new value.

  12. 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.

  1. Open Needs & Requirements → Import and Export and click Import PDF Specification…, or drop the .pdf file on the drop zone.
  2. 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).
  3. 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.
  4. 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.

  1. 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.
  2. Choose the .xlsx or .xlsm file. A progress card shows the stages for large workbooks.
  3. 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).

  1. 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.
  2. Open Import and drop the file. Format shows UML/SysML (.xmi, .uml, .mdzip).
  3. 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.
  4. Click Import N items. A single Undo takes back the whole import.

How the model maps to Holarch

UML / SysMLHolarch
«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, actorAsset (blocks labelled Block)
Part property (composition)Asset decomposed by the part's block
Generalizationthe general block extended by the specific one
Shared (aggregation) propertyAsset related to the referenced block
Value propertyCharacteristic that specifies the block: default value → Value, the value type's unit → Units
«constraintBlock», constraint property, binding connectorEquation (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
ConnectorConduit (labelled Interface) connecting the ports (or blocks) at its ends
Item flow, signalInput/Output transferred by the connector's Conduit
Activity, action, use caseAction; 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 actionsInput/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 pointsOne 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 effectsParallel 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
PackagesThe Package attribute (path, e.g. Drone::Structure)
Tagged valuesAttributes (new attributes are added to the class)
Stereotypes from other profilesLabels in the Stereotypes label group; their tagged values become attributes of the item's class, shown in the inspector under «Stereotype» (profile)
DiagramsNot 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.

  1. Open Import and Export and click Export UML/SysML (XMI)… on the Export card.
  2. 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.
  3. 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.
  4. Check the File name (default: the project name) and click Export. The file is <file name>.xmi or <file name>.uml.
  5. 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

HolarchUML / 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
Portproxy 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 Assetvalue 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/OutputSignal; on a Conduit, an «itemFlow» on the connector
ConduitConnector in the block that contains both ends (nested ends when deeper)
ActionActivity 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 TransitionsState 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 groupStereotype 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

  1. Export with Format set to Papyrus (Eclipse UML) (.uml) and Holarch attributes and labels on.
  2. 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.
  3. Edit the model and save it.
  4. 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

  1. Open Manage Projects.
  2. Open the project's row menu ⋯ and choose Export this project….

    Or, on Home, choose Home ▾ → Export Project….

  3. Keep Format at Holarch backup (.holarch), choose the options and click Export.

    The .holarch file downloads. It holds the whole project and its attached files.

To restore it on any Holarch server:

  1. Open Manage Projects → Project Files ▾ → Import Project….
  2. Choose the .holarch file.

    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:

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.

  1. Open Documents → EO-1 System Requirements Specification.
  2. 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.

  1. In the Database, search class:Requirement.
  2. Click Export… → Table (CSV), tick Owner and ID, and click Export.
  3. In the file, change the Owner of 3.1 Orbit Average Power and 3.2 Battery Capacity to "EPS Lead".
  4. Import the file as in Update existing entities.

    Review shows both rows under Updated items, with the Owner change.

  5. 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.

  1. Open Verification → Traceability Matrix, with the specification on the left and Test Cases on top.
  2. Choose Export… → Matrix (Excel).

4. Exchange the trace web.

  1. In the Database, search class:Requirement OR class:Action.
  2. 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.

  1. In Manage Projects, choose Export this project… on the demo.
  2. 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.

FormatFiles
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:

GroupFieldMeaning
SkipNot imported.
ItemName, Number, DescriptionThe item's own fields.
ItemClassThe class name (matched ignoring case, spaces and punctuation).
ItemLabelsLabel names separated by ;, ,, a vertical bar or line breaks.
ItemParent numberThe number of the row's parent.
ItemGlobal IDThe ID used to match existing entities.
Attributesan attribute of the class for rows without a classQuality, file and computed attributes cannot be imported.
Relationshipsa relationshipValues 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.
StructureRow IDAn ID used inside the file (ReqIF, XMI).
StructureParent row IDThe Row ID of the parent.
StructureNew attribute (added to the schema)Creates an attribute named after the column on each imported class (see New attributes).

Classes and matching:

OptionValues and effect
Class for rows without a classAny creatable class; default Requirement. Used when no Class column sets the class and no class rule applies.
Class rulesDescription 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 byGlobal ID (default), Name or Number. See Matching existing entities.
Match related entities byGlobal 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:

PatternReads
emptyAutomatic: 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.1Path 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.ForeignIDNumber
Name, Title, Short Name, Requirement Name; Object Heading, ReqIF.Name, Long NameName
Description, Text, Requirement, Requirement Text, Statement, Desc; Object Text, ReqIF.Text, ReqIF.DescriptionDescription
Class, Type, Entity Class, ClassName; ReqIF.CategoryClass (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 IDGlobal ID
Parent, Parent NumberParent number
ReqIF ID, XMI ID, Row IDRow ID
Parent IDParent row ID
The name of an attribute of the class for rows without a class, or of any classThat attribute
The name of a relationship (for example "satisfied by")That relationship
Anything elseSkip (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.

  1. Go through File, Map and Review as for any import.
  2. 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.

  3. 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-dd or yyyy-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,5 or 1.234,5 in 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. 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

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 example satisfied_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:

ElementClass
«requirement» and its SysML kindsRequirement (its Id becomes the number and its Text the description)
«testCase»Test Case
Class, «block», Component, Node, Device, Execution Environment, ActorAsset
Activity, action, opaque behavior, use caseAction
SignalInput/Output
State, final state, initial and history pseudostatesCharacteristic labelled State
TransitionTransition
Value propertyCharacteristic

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:

StereotypeHolarch 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 stereotyperefines 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:

  1. Its Parent Row ID.
  2. Its Parent Number.
  3. Its own number. The parent of 1.2.3 is 1.2. If 1.2 is not in the file, it is 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

Attribute typeAccepted values
NumberA number (a trailing % is ignored) or a distribution such as normal(10, 2)
PercentA number, with or without %
Date and timePer Date format of date columns
DurationA number and a unit (5 days, 90 min; Seconds to Years; default Hours) or a distribution
Booleantrue, yes, y, 1 or x for true; anything else is false
EnumerationOne of the choices (ignoring case); other text is kept as typed
Multi-selectValues separated by ;, ,, a vertical bar or line breaks, matched to the choices
Geo pointlatitude, longitude
Text and rich textAs 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

ImportWhereDetails
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 MatrixA 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 filesRich text + → Image… / File…, entity images, file attributes, whiteboard Insert Image…, slide imagesImages over 4,000 px on the longest side are reduced; files over the per-file limit are refused.
Graphics for DoDAF productsFrameworks → DoDAFPNG, JPEG or SVG graphics for a product.
Java sourceSysML block diagramsImport Java… → Choose .java File… reads classes into blocks.
AI reference filesAI 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.holarch or name.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 asOutputOptions
Table (CSV)Number, Name, Description, Class, the chosen attributes, one column per relationship type, the chosen extrasInclude 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 columnFreeze 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 entityFreeze 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, AttributesRelationship (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, ToFreeze header row (on), Global ID, ID (on), Version Number (on)
Comments (Excel)Class, Name, Number, Description, Comment, Author, Date, Resolvednone; offered when the entities have comments
Breakdown (Word)One entity's decomposition as headings, with descriptions and diagram pictures and a contents tableDiagrams (diagram types; Hierarchy on); offered for a single entity
Project data (JSON)A holarch-project file with the entities and their relationshipsInclude 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 settingsnone
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 hierarchynone
Table (Print)The browser's print dialognone

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:

ItemOutput
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 itemsFor 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-baseline JSON 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

PageControlFormats
Requirements QualityExport ▾Excel (.xlsx), CSV; the results dialog has Export CSV and Export XLSX
TBD/TBRExport XLSXNumber, Name, Document, Type, Source, Owner, Due Date, Opened, Age (days), Overdue, Description
RVTMExport ▾RVTM (CSV), RVTM (Excel), RVTM (Word)
Test Center suite menuTest Cases (Word)…, Export CSV, Export JSONTest cases with set-up, expected and actual results, status and verified requirements
Interface RegisterExportCSV of interfaces, endpoints, status, owner, items and requirements; ICD per interface (Word)
Interface (physical) diagramsICD outputsICD document (Word) and ICD table (CSV); interface register (CSV)
N² and I² matricesExportCSV
Budgets & TPMsExport XLSXBudget workbook; TPM report with Status, Planned Profile and History sheets
Functional AnalysisCSV, XLSX, Copy on each table; reportTables as CSV, XLSX or Word; Copy puts the table on the clipboard for Word or Excel; FFBD as PNG; full report as DOCX
Risk RegisterExportExcel (XLSX), CSV
Trade StudiesExport ▾Excel Workbook (.xlsx), Word Summary (.docx)
SimulatorPanel ⋯ → 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)
ChartsDashboard 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)
PresentationsExport…Current slide (PNG) (with Transparent background and Scale), Current slide (SVG), Presentation (HTML), Presentation (PowerPoint), Presentation (Word)
DoDAFExport menuArchitecture 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 panelsPanel ⋯ → Export…Saved view Table (CSV), Breakdown Chart (SVG) and Chart (PNG), Pinned item Picture (PNG)
Gallery cardsCard ⋯ → 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:

EntryContent
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.jsonThe 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.

MessageFix
"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).
  • 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.
  • schemaIds: 2 marks 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", 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 / Ctrl+Z undoes a whole import. See Keyboard shortcuts.

Messages

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

MessageFix
"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

WarningMeaning
"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.