Traceability

Overview

Traceability is the set of relationships that connect each requirement to where it came from and to what fulfills and verifies it. In Holarch every link is an LML relationship between two entities in the model, so one link made anywhere shows up everywhere: in the inspector, the Traceability Matrix, the Spider and Requirement diagrams, the RVTM, document reports and Model Checks.

The main tools:

Concepts

Relationships and their inverses

A relationship has a source, a type and a target, and reads as a sentence: "1.2 Ground Sample Distance satisfied by F7 Capture Images". Every type has an inverse, and Holarch shows the link from both ends: from F7 it reads "F7 Capture Images satisfies 1.2 Ground Sample Distance". Creating either direction creates the same link.

The schema decides which classes each type may connect. A cell, menu or button that would create a link the schema does not allow is locked or refused. Projects can add their own relationship types; see Schema Extensions.

Trace relationships

decomposed by and source of are structure relationships: they build document outlines and hierarchies. The matrix leaves them out of the "related" columns and of the default column guess.

Coverage

Coverage answers "is every requirement allocated and verified?":

• Allocated: a leaf requirement (one with no child requirements) is satisfied by, or traced to, at least one Action, Asset, Input/Output or Conduit. Model Check Requirement.8 lists the ones that are not.
• Verified: a leaf requirement is verified by at least one Test Case. Model Check Requirement.10 lists the ones that are not. The Quality Checker's Verifiable criterion fails with "No verifying Requirement or Test Case is linked." when a requirement has no verified by link to a Requirement or Test Case.
• Verification status: the RVTM gives each requirement a status (Passed, Failed, Not Run, Planned-only, Unverified) from the results of its test cases and rolls it up the hierarchy. See RVTM statuses.

A gap in the matrix is a row or column with no links of the shown relationship types.

Impact

Impact is the set of entities a change can affect. Two mechanisms show it:

• Impact Analysis in the Spider diagram highlights everything reachable from a selected entity within N links, before you make the change.
• Suspect links flag the downstream links of a requirement automatically after a change to its text or key attributes (see Requirements).

How to use it

When and why

Trace as soon as requirements and functions exist, and keep tracing through design and verification:

1. After requirements are written: decompose and derive (parent requirement derived by child requirement) so each low-level requirement traces to a stakeholder need.
2. During functional analysis and architecture: allocate each leaf requirement with satisfied by to the functions, assets, interfaces and items that fulfill it.
3. During verification planning: link each requirement with verified by to the test cases that prove it.
4. Before each review: check coverage (gaps, RVTM, Model Checks) and export the matrices for the review package.
5. During change control: run an impact analysis before a change, and review suspect links after it.

The matrix answers "what links exist and what is missing?"; the Spider answers "what is connected to this one item?"; the RVTM answers "is it verified, and did the tests pass?".

Link one requirement in the inspector

1. Select the requirement in a document, the Database or any table. The inspector opens on the right.
2. Open the Relationships card. The list at the top chooses which types show: Pinned (your pinned types plus any in use), Active (types with links) or All (every type the schema allows).
3. On the relationship type (for example satisfied by), click Add ▾:
   • Relate Existing Entities… opens a searchable list of allowed targets. Tick one or more and click Relate Selected.
   • Create New… creates a new entity of an allowed class and links it.
4. To remove a link, click × on its row.

Result: the link appears under the type, with a count on the heading. Pin a type you use often with 📌 so it shows in Pinned mode for that class.

Link many requirements in the Traceability Matrix

1. Open Verification → Traceability Matrix.
2. In the left pane, Filter tab, set Left (Y Axis): Rows From = Query, Left Query (Y Axis) = class:Requirement, and press Enter.
3. Set Top (X Axis): Axis Type = Query, Top Query (X Axis) = class:Action.
4. Under Relationship Type, choose satisfied by. The description under the list explains the type.
5. Click an empty cell to create the link. The cell shows the mark (X by default) and the row and column counts go up.
6. Click a marked cell to remove the link. With Confirm before removing a relationship on, confirm in Remove Relationship.

Result: the summary at the top right reads, for example, "32 rows × 108 columns · 56 links · 4 rows without links".

Find gaps

1. In the matrix, tick Gaps only. Only rows with no links remain.
2. Tick Hide empty columns to drop columns nothing links to.
3. For each gap row, either create the missing link, or decide that the requirement is not a leaf, is a Statement, or is not needed.
4. Check from other angles:
   • Verification → RVTM: the Unverified and Planned-only cards.
   • Verification → Model Checks: Requirement.8 (not allocated) and Requirement.10 (not verified), each with Fix.
   • The Database query class:Requirement AND NOT relationship:"verified by".

Let AI suggest missing links

1. Set up the axes and choose the relationship type (for example verified by, rows class:Requirement, columns class:"Test Case").
2. Choose ✦ AI ▾ → Traceability Assist (suggest missing links). If no relationship is chosen, pick one in Relationship for Assist and click Run.
3. Suggested cells are tinted green (stronger for higher confidence) and show +. Point at a cell for the confidence and reason.
4. Click a tinted cell to create that one link, or Accept all to create all suggestions in one undo step. Clear removes the tints.

Suspect Assist (flag doubtful links) works the same way on existing links: doubtful cells are tinted red, clicking one removes the link, and Accept all removals (N) opens Remove N links with a checklist (links touching Approved, baselined or locked items start unticked); Remove Ticked removes the ticked links in one undo step.

Run an impact analysis before a change

1. Open the requirement and choose Open ▾ → Spider (or right-click a node in any Spider diagram and choose Open as Spider Root).
2. Click Relationships (N) ▾ and choose a preset: Requirements V&V (traced to, satisfied by, verified by, source of) or Traceability Relationships (decomposed by, performed by, source of, traced to). Click Generate.
3. Choose the depth in the level list (up to 10) and click Generate again if you changed it.
4. Select the requirement and click Impact. Choose Level 1 to Level N in the list next to it.

Result: the entities within that many links stay highlighted and everything else is dimmed. Press Esc or click Impact again to leave impact mode; the diagram cannot be edited while it is on.

Report traceability

• Matrix: Export ▾ → Matrix Report (Excel), Comma Separated (CSV), Detailed CSV (relation names) or Importable Matrix (CSV).
• RVTM: Export ▾ → Excel (.xlsx), CSV or Word (.docx) on the RVTM page.
• From a document: Reports → RVTM Output (XLSX), VCRM Output (XLSX), RVM Output (XLSX) (verified by), RTM Output (XLSX) (traced to), RSM Output (XLSX) (satisfied by) and TVM Output (XLSX) (test case × requirement). See Documents.
• From the Database: the Entity Relationship Matrix (XLSX) export for the selected entities and one relationship. See The Model and the Database.

Worked example: the CubeSat EO-1 demo

The demo project CubeSat EO-1 — Earth Observation Demo has 32 requirements in SRS-001 EO-1 System Requirements Specification, top-level functions F1 to F11 under F0 Perform EO-1 Mission, a physical architecture under 0 EO-1 Mission, and test cases TC-01 to TC-17 in two test suites.

Allocation matrix. Open Verification → Traceability Matrix. Set Rows From = Query with class:Requirement, Axis Type = Query with class:Action, and Relationship Type = satisfied by. The grid shows, for example, 1.2 Ground Sample Distance, 1.3 Swath Width and 1.4 Spectral Bands satisfied by F7 Capture Images, and 3.1 Orbit Average Power satisfied by F3 Generate and Store Power and F3.1 Convert Sunlight to Power. Tick Gaps only: rows such as 2.5 Safe Mode Recovery and 3.5 Battery Thermal Control remain. Those are the weak, unfinished requirements of the demo; allocate 2.5 to F10 Enter Safe Mode by clicking its cell.

Verification matrix. Change the top query to class:"Test Case" and the relationship to verified by. 2.1 Pointing Accuracy and 2.2 Pointing Stability share TC-04 Pointing Accuracy Test; 3.2 Battery Capacity and 3.3 Depth of Discharge share TC-07 Battery Capacity Test.

RVTM. Open Verification → RVTM. The first card reads 11 / 32 Verified (Passed). 2.1 Pointing Accuracy is Failed because TC-04 measured 0.14 degrees on 3 of 20 targets. 1.6 Revisit Time has no test of its own (own status Planned-only, from its Analysis method), but its status rolls up to Not Run from its children: 1.6.1 Ground Track Repeat has Passed and 1.6.2 Off-Nadir Imaging has Not Run. 2.5 Safe Mode Recovery is Unverified: no method and no test.

Impact analysis. Open 3.1 Orbit Average Power, choose Open ▾ → Spider, pick the Requirements V&V preset and click Generate. Select 3.1, click Impact and choose Level 1: the highlighted items are 1.3.1 Solar Arrays, F3 Generate and Store Power, F3.1 Convert Sunlight to Power, the equations EQ-1.1 and EQ-1.4, and TC-06 Solar Array Power Test, the same six items that Suspect Links flags after 3.1 changed from 28 W to 30 W.

Tips and good practice

• Trace leaf requirements. A parent requirement is covered through its children; the RVTM and Model Checks treat it that way.
• Use satisfied by for allocation and verified by for verification, and reserve traced to for references that are neither. Reports and checks look for those specific types.
• Pick one relationship type in the matrix before creating links. With All allowed, a click on a cell with several possible types opens a menu, and Relation to create on click can set a fixed type.
• Save a matrix you review often as an artifact with Export ▾ → Export to a New Artifact…. It reopens with the same axes, and it can go into a review package.
• Use a root hierarchy (Root Entity hierarchy) instead of a class to keep rows in document order with indentation.
• Run Traceability Assist on a filtered range: it is faster and the suggestions are easier to check.

Common mistakes

How it connects to other features

• Feeds from: requirements (Requirements, Documents), functions (Functional Analysis creates satisfied by links when it extracts functions), architecture, interfaces and the Test Center (test cases created there are linked with verified by).
• Feeds into: the RVTM and Test Center coverage, Model Checks, the Quality Checker's Verifiable criterion, suspect-link tracking, document trace reports, Home (verification counts and next actions), and Review Packages.

The Traceability Matrix

The matrix is a grid of entities: rows on the left (Y axis), columns on top (X axis), and a mark in each cell where a relationship of the shown types exists. Open it from Verification → Traceability Matrix, from the Database (Matrix on the query bar, or Matrix on the selection bar for the selected rows), from an entity's Open ▾, from a test suite's ⋯ → Open in Traceability Matrix, or from DoDAF.

With no saved setup, rows are every Requirement and columns are the class most often linked from them.

Top bar

• Import…: the CSV matrix import wizard (see Import a matrix).
• Export ▾: under Files, Matrix Report (Excel), Comma Separated (CSV), Detailed CSV (relation names) and Importable Matrix (CSV); under Artifacts, Export to a New Artifact… and Export to an Existing Artifact… (not shown when the matrix is already an artifact).
• Open Matrix Artifact: shown for a matrix artifact; opens its Entity View.
• ✦ AI ▾: Traceability Assist (suggest missing links), Suspect Assist (flag doubtful links), Accept all suggestions (N) or Accept all removals (N) while an assist is shown, and Clear Assist.

Toolbar

Left pane: Filter tab

Left (Y Axis), Rows From:

Top (X Axis), Axis Type (disabled while there are no rows):

Relationship Type: All allowed (N) (every type the schema allows between the row and column classes) or one type. The text under the list is the type's description, or "Cells show every relationship the schema allows between the row and column entities."

Options:

Show hidden (N) brings back hidden rows and columns; Remove added rows/columns removes everything added with + Row and + Column.

Legend: the mark ("relationship exists — click to remove"), an empty cell ("click an empty cell to relate"), a locked cell ("not allowed by the schema"), a gap ("row / column with no links (gap)"), and "Click a row or column header to select it; double-click opens it; Esc deselects."

Left pane: Comments tab

Comments attach to the axis root entities. With both a Y and an X root, Show X Root Comments / Show Y Root Comments switches between them. Type in Add a comment… and click Post Comment; × deletes a comment. Without a root: "Comments are attached to the axis root entities. Choose a root entity on the Filter tab." A 💬 next to a header means that entity has comments.

The grid

• Headers: each column header is rotated and shows its number and name; each row header shows a class color swatch. Point at a header for its class and label. Gap rows and columns are highlighted. The Links column and row give the count per row and column and the total.
• Empty cell: click to create a link. With one allowed type, it is created at once. With several, a menu lists them, with satisfied by, satisfies, verified by, verifies, traced to, traced from, performs and performed by first. Relation to create on click skips the menu.
• Marked cell: shows the mark, the relationship names or the count. Point at it for "<row> — <relationship> — <column>". Click to remove: one link is removed (after confirmation); with several, a menu Remove which relationship? lists each, plus All of them.
• Locked cell: grey; the schema allows none of the shown types for that pair. Its tooltip reads "Not allowed by the schema: <class> → <class>".
• Diagonal: an entity on both axes; not clickable.

Selecting a row or column

Click a row or column header to select it. The entity shows in the inspector, and a bar above the grid offers:

Double-click a header to open the Entity View.

Matrix artifacts

Export ▾ → Export to a New Artifact… asks for Number, Name and Description ("Enter a name or a number."), creates an Artifact labeled Matrix and saves the axes, relationship and options in it. Export to an Existing Artifact… saves them into an artifact you pick (compilations, test suites, simulation outputs and existing matrices are excluded). The toast reads "Matrix saved to artifact "<name>"" and the matrix reopens from the artifact.

A matrix artifact opens with its saved setup, and changes are saved back to it. The Matrix Artifact box at the top of the left pane shows its name and description; ✎ edits the number, name and description (Done or Cancel; "Name or number is required"). A new matrix artifact with no axes asks for one in Matrix Artifact: "This matrix has no Y axis yet. Pick a Y axis type and value." Choose Root Entity or Query and click Update; Back leaves.

Saved setups

Holarch remembers each matrix setup per row source (root, query or class) in the project, and reopens the last one. The mark, hover style, Hide Roots and confirmation options are kept in this browser. Scroll position is restored.

Exports

Each export asks for a File Name in Download Report.

Import a matrix

Import… reads a CSV matrix and shows Import Matrix — Analysis before changing anything:

• Cell A1 must hold the setup from an Importable Matrix export, or a relationship name (for example satisfied by).
• Row and column headers are matched by ID, by "Number Name" label, or by number.
• A non-blank cell means "linked"; a blank cell means "not linked".

The analysis shows the relationship, the row and column counts, and + N to add, − N to remove, errors and warnings, with expandable sections Add, Remove, Errors: Relationship With Self, Errors: Existing Bad Relationships (will be removed), Errors: New Bad Relationships (skipped) and Warnings: Entities Not Found. Click Import to apply all changes in one undo step. The toast reads "Imported: N added, M removed".

Address options

The matrix can open from a link with these parameters: matrix?root=<id> (rows are its hierarchy, columns the same hierarchy), ?q= or ?rowsq= (row query), ?rows=id,id (selected entities), ?cols=<classId> (column class), ?colsq= (column query), ?rel=<relationId> and ?artifact=<id> (a matrix artifact).

Spider diagram and impact analysis

The Spider Diagram is a radial graph around one root entity over the relationship types you choose. It is the quickest way to see the whole trace web of a requirement.

• Relationships (N) ▾: Default Presets (All Relationships, Traceability Relationships, Decomposition, Requirements V&V, None), Custom Presets (Save as Preset… saves the current choice for the project; Remove Presets…), and the list of relationship types in the project with their counts and colors. Changes apply with Generate.
• Level list: how many links out from the root (up to 10). Generate applies the level and relationship changes; it is highlighted while changes are pending.
• Layout resets node positions. + Add Related… relates a new or existing entity to the selected node ("Related: <a> <relationship> <b>"). Hide removes selected nodes from the diagram; Show Hidden brings them back.
• Impact and its level list: with one entity selected, highlights everything within the chosen number of links and dims the rest. Without a selection: "Select one entity to run an impact analysis." Editing is blocked while it is on ("Turn off Impact Analysis to edit the diagram."); Esc turns it off.
• Drag from a node's connection handle to another node to create a relationship. Select a link and press Delete to remove it ("Relationship removed (⌘Z to undo)").
• Right-click a node: Expand (show more related entities), Add Related Entity…, Open Entity View, Open as Spider Root, Remove from Diagram, Delete from Database.

For the full diagram editor, see Diagram Editor Basics and Spider Diagram.

Requirement diagram

The SysML Requirement Diagram draws requirements as blocks with their containment and dashed trace arrows: «satisfy», «verify», «deriveReqt», «refine», «copy» and «trace». When you connect two blocks, the default stereotype is «verify» from a Test Case, «satisfy» from an Asset or Action, and «trace» otherwise. The toolbar's attribute menu shows or hides Id, Text and each requirement attribute on the blocks. See Requirement Diagram.

Trace indicators in documents

In a document, each row shows small S, T and V indicators when the item has satisfied by, traced to or verified by links. Turn them off with ⚙ View ▾ → Display Options… → Disable gap analysis indicators (S/T/V). Add relationship columns to the document with Display Options… to see the linked items in the table. See Documents.

RVTM and verification coverage

Verification → RVTM (Requirements Verification Traceability Matrix) lists each requirement with its Method, Level, the test cases that verify it (Verified by, or "No test"), its Own status and its rolled-up Status.

• Cards: Verified (Passed) ("<passed> / <total>" with a progress bar), then Failed, Not Run, Planned-only and Unverified. Click a card to show only those requirements; the chip Status: <status> × shows all again.
• Filter by number or name narrows the rows.
• Click a row (or press Enter) to show the requirement in the inspector; Esc deselects.
• Top bar: Export ▾ (Excel (.xlsx), CSV, Word (.docx)) and Test Center.

RVTM statuses

A requirement's own status comes from the test cases linked to it with verified by:

The Status column rolls the own status up through decomposed by:

• A failure anywhere below makes the parent Failed.
• The parent is Passed when its own test passed, or when every child requirement is Passed.
• Otherwise the parent shows the further-along of its own status and its least-covered child (Unverified < Planned-only < Not Run < Passed).

"Verified" means Passed. The RVTM exports have the columns Requirement Number, Requirement, Verification Method, Verification Level, Success Criteria, Verified By (with each test's result), Own Status and Status (rolled up).

When the filter matches nothing: "No requirement matches this filter. Clear the filter to show every requirement." With no requirements: "This project has no requirements. Write or import requirements, then link test cases with “verified by”." See RVTM and Test Center for test runs and results.

Model Checks for traceability

Verification → Model Checks runs rules over the whole model. The traceability rules:

See Model Checks.

Queries for coverage

Use any of them as a matrix axis query or in the Database. See Search Query Syntax.

Shortcuts

See Keyboard Shortcuts for the full list.

Messages

Limits

• Axis queries return at most 100,000 entities.
• Hierarchy axes go 10 levels deep.
• + Column and + Row list up to 300 matching entities; search to narrow the list.
• Traceability Assist and Suspect Assist work on up to 20,000 visible cells, sending 40 rows per AI request.
• The Spider diagram expands up to 10 levels; the impact level goes up to the diagram's level.
• The import analysis lists up to 300 items per section.

Related

• Requirements: attributes, quality, approvals, suspect links and baselines.
• Documents: S/T/V indicators, relationship columns and trace reports.
• The Model and the Database: queries, the inspector and the relationship matrix export.
• Schema Extensions: custom relationship types.
• Help: Traceability Matrix, Trace Requirements and Find Gaps, RVTM, Test Center, Model Checks, Spider Diagram, LML Primer.