Requirements
Program Map
See how your projects link to each other, with link counts per pair of projects, and follow one item's chain of links through other projects.
Overview
A program that spans several projects (a system project, subsystem projects, a test project, libraries) is tied together by links to other projects. Each link is stored in the project that makes it, so no single project shows the whole picture. The Program Map does: it draws one box per project you can open and one arrow per pair of projects, labelled with the relation and the number of links.
The page has two views:
- Projects: every project you can open and the links between them, as a graph or a table.
- Item Trace: one item in the middle and the items linked to it in other projects, ring by ring, up to six steps out.
The Program Map is open to everyone signed in. Links themselves are made on the Team plan; links stored in a project whose owner's plan does not include them are drawn grey. The links between the Hybrid Car and Hybrid Car Battery Pack demo projects work on every plan.
Concepts
What the map shows
| Element | Meaning |
|---|---|
| Box | A project you can open: its name, its project type and its number of items; its accessible name adds the links it holds and receives |
| Arrow | Links stored in the project at the tail that point at items in the project at the head |
| Arrow label | relation · links · deleted, for example traced from · 12 · 1 deleted |
| Projects you can't open (N links) | One dashed box that counts every link into a project you cannot open |
| Library release box | A library release you can read, linked to from your projects |
Arrows usually point up: subsystem projects store traced from and satisfies links to the system project, and test projects store verifies links. The map places the projects that hold links below the projects they point at.
Who sees what
The map is built only from the projects you can open: a project where you are a member with any role, not in the Trash, and whose organization's two-step sign-in rule you meet.
- A link into a project you cannot open is counted in Projects you can't open (N links). That box never names the project or item, and it looks the same whether the project exists, is in the Trash, or never existed.
- Links stored in a project you cannot open are not counted anywhere, even when they point at your projects.
- Being an organization admin adds nothing: the map uses project membership.
- Exports (CSV, SVG, PNG) hold exactly what the page shows.
Colours
| Colour | Meaning |
|---|---|
| Blue arrow | Links between projects you can open |
| Amber arrow | Some of the targets are deleted (in the Trash or gone) |
| Grey arrow | Links into projects you can't open, to a library release, or stored in a project whose owner's plan doesn't include links to other projects |
How to use it
See how your projects link
- Click Manage Projects, then Program Map. The Projects view opens with every project that holds or receives links.
- Read the arrows. Point at a box to dim everything not connected to it.
- Click an arrow. The inspector lists its links, 100 at a time: the item that holds each link, the relation and the target item. Click either item to open it in its project, or Show More for the next 100.
- Click Export CSV in the inspector to save that arrow's links, or Export ▾ in the bar to save the whole map as CSV, SVG or PNG.
Start from one project
- Open the project, then Verification → Program Coverage, and click Open Program Map.
- The map shows only that project and the projects linked to it, directly or through others.
- Click Show All Projects to see everything you can open.
You can also click a box and choose Show Linked Projects Only.
Trace one item through the program
- Select the item. In the inspector's Trace section, open Other projects ⋯ and choose Show in Program Map. From an arrow's link list, click Trace This Item instead.
- The Item Trace view shows the item in the middle and the items linked to it in rings: the first ring one step out, the second two steps out. Links are followed in both directions.
- Choose Steps (1 to 6, default 3) to go further or stay closer.
- Items are coloured by project, with a dashed box around each project's items. Clear Group by project to remove the boxes.
- Click an item for Open Item and Trace From Here, which puts it in the middle.
Worked example: the CubeSat EO-1 demo and a payload project
- Create the CubeSat EO-1 demo, then a second project EO-1 Payload with the requirement PL.1 Imager resolution.
- In EO-1 Payload, select PL.1. In Trace → Other projects, click +, choose traced from, the CubeSat project and its imaging requirement, and click Add Link.
- Create a third project EO-1 Test Campaign with the test case TC.4 Resolution test, and link it with verifies to PL.1 in EO-1 Payload.
- Open Manage Projects → Program Map. The map shows EO-1 Test Campaign at the bottom, EO-1 Payload above it and the CubeSat project at the top, with the arrows verifies · 1 and traced from · 1.
- Click PL.1 → Trace ⋯ → Show in Program Map: the test case and the CubeSat requirement sit one step out, on either side.
Worked example: the Hybrid Car and its battery pack
- On Manage Projects, click Project Files ▾ → New Demo Project → Hybrid Car (SysML v2).
- Then create Project Files ▾ → New Demo Project → Hybrid Car Battery Pack (SysML v2). The battery supplier's pack requirements PackCapacity, PackMass and ChargeAcceptance are linked with traced from to the car's requirements VR-3, VR-6 and VR-5 in your newest Hybrid Car demo, whichever of the two you create first; creating the Hybrid Car demo again moves the links to the new one. These demo links work on every plan. Without a Hybrid Car project the pack demo has no links.
- Open Manage Projects → Program Map. The map shows the two SysML v2 projects with the arrow traced from · 3.
Tips and good practice
- Agree on the relations that subprojects use (traced from or satisfies for requirements, verifies for tests) so the arrows read the same everywhere.
- Turn off Group relations to see one arrow per relation, for example to tell requirement links from test links between the same two projects.
- Drag boxes to arrange the map. The positions are kept in this browser for each scope.
- Use the Table view to sort pairs of projects by number of links or deleted targets.
- An amber arrow means links that need repair: open its link list, then fix or remove the links in the item's Trace → Other projects.
Common mistakes
| Problem | Cause | Fix |
|---|---|---|
| A project is missing | You are not a member of it, it is in the Trash, or it has no links | Ask its owner for access; tick Show unlinked projects to list projects without links |
| Everything goes to Projects you can't open | The links point at projects you are not a member of | Ask a project's owner for access |
| Grey arrows in the middle of the map | The project that holds the links has an owner without the Team plan | The owner upgrades in Account Settings → Plan & Billing |
| A new link does not show yet | The map is still reading recent changes | Click Refresh after a minute |
How it connects to other features
- Links to other projects: the map reads them; it adds or changes nothing. Make links in an item's Trace → Other projects (see Links to Other Projects).
- Program Coverage: the per-item view of the links into one project, with gaps (see Program Coverage). Open Program Map there starts the map from that project.
- Libraries: links to an item of a library release appear as arrows to the release's box (see Libraries).
- Spider Diagram: the trace inside a project, with dashed boxes for linked items elsewhere. The Item Trace uses the same ring layout.
- API and MCP: the same map and trace for tools (see API and MCP).
The Program Map page
Bar
| Control | What it does |
|---|---|
| Projects / Item Trace | Switches the view |
| Scope | All my projects, one organization (when you belong to one), or one folder with its subfolders (when you have folders; see Project Folders) |
| Show All Projects | Shown after opening the map from a project; leaves that project's linked set |
| Show unlinked projects | Also shows projects with no links |
| Group relations | One arrow per pair of projects (labels list each relation), or one arrow per relation |
| Steps | Item Trace: 1 to 6 steps out |
| Group by project | Item Trace: dashed boxes around each project's items |
| Graph / Table | The diagram or a sortable table; on a narrow screen the table opens first |
| Refresh | Reads the links again |
| Export ▾ | Export CSV, Export SVG, Export PNG |
Graph
- Click a box to show its project in the inspector: Open Project and Show Linked Projects Only. Double-click a box, or press Shift+Enter on it, to open the project.
- Click an arrow to list its links in the inspector.
- Drag boxes to move them; scroll or pinch to zoom; drag the background to pan.
- Press Tab to reach the map, then the arrow keys to move between boxes and arrows; Enter goes to the inspector. Each box and arrow has a name that a screen reader reads, such as "EO-1 Payload, LML project, 1 link out, 1 in".
Table
| View | Columns |
|---|---|
| Projects | Source project, Relation, Target project, Links, Deleted |
| Item Trace | Project, Number, Name, Class, Steps from the item, State |
Click a column heading to sort.
Inspector
| Selection | Contents |
|---|---|
| Project box | Name, type, number of items, links out and in; Open Project, Show Linked Projects Only |
| Arrow | Source and target project, links per relation, the link list (100 at a time, Show More), Export CSV, Trace This Item per row |
| Item (Item Trace) | Number and name, class, project, steps from the traced item, state; Open Item, Trace From Here |
| Projects you can't open | "Links to projects you can't open. Ask a project's owner for access." |
API and MCP
The REST API and MCP give the same answers with the token's own access and project list. Projects of an organization that turned API access off are left out, like projects you cannot open.
| Call | Returns |
|---|---|
GET /api/v1/program-map | Projects, releases, arrows (from, to, relation, links, deleted, plan) and the hidden count; from, unlinked, org as in the page |
GET /api/v1/projects/<project>/items/<item>/trace | The Item Trace: nodes with project, number, name, class and steps, the links between them, and the hidden count; steps 1–6 (default 3) |
MCP program_map | The same as GET /program-map |
MCP trace_chain | The same as the trace call; items in projects with regulated-data markings answer withheld |
See API and MCP.
Messages
| Message | Meaning |
|---|---|
| No links between your projects. Add one from an item's Trace section. | None of your projects holds or receives a link you can see |
| This project has no links to other projects. Add one from an item's Trace section. | The map was opened from a project without links |
| This item has no links to other projects. Add one from its Trace section. | The traced item has no links |
| Some projects are still being read. Refresh in a minute. | Recent changes in large projects are still being read; the map shows what is ready |
| Showing the first 500 items. Reduce the steps. | The Item Trace reached its limit |
| N links from projects whose owner's plan doesn't include links to other projects are not followed. | The Item Trace skipped links stored under a plan without them |
| The program map could not be read. Reload the page. | The request failed |
Limits
| Limit | Value |
|---|---|
| Item Trace steps | 1 to 6 |
| Items in an Item Trace | 500 |
| Links listed per page in an arrow's list | 100 |
| Links per project | 20,000 (see Links to Other Projects) |