Relations
A relation is the semantic label attached to an external link — it answers the question "what is the nature of this connection?" For example, a test case might Cover a requirement, or a failed result might be linked to a Defect it uncovered. Every relation carries one of three semantic types — General, Defect, or Requirement — and that semantic, not the relation’s name, is what decides whether a link counts as a defect, as coverage, or as neither. Relations are configured workspace-wide and can be scoped to specific projects.
What a relation defines
When a team member adds an external reference to a test object, they choose:
- An Integration Source — which system the external item lives in (e.g., Jira)
- The external key — the identifier of the specific issue (e.g.,
PROJ-123) - A Relation — the label describing the nature of the link (e.g., Relates to, Defect, Blocks)
Relations are independent of sources — the same set of relations is available regardless of which integration source is selected.
Semantic types
Every relation has a semantic type that determines how TestOrchestrator treats links using that relation.
| Semantic type | Behaviour | Example relation names |
|---|---|---|
| General | A standard cross-reference with no special behaviour of its own. On run and cycle surfaces a General link is read as unclassified — it is attached, but nobody has said what it means, so it counts neither as a defect nor as coverage. | Relates to, Verifies, Blocks, Caused by, Duplicate |
| Defect | Treated as a defect-style link. These links are counted and surfaced in defect reports and metrics, helping teams track how many defects are associated with a test run or session. | Defect, Bug |
| Requirement | Treated as coverage: the linked ticket is something the test case exists to verify. Requirement links drive the Requirements views and coverage cards on runs and cycles, and the Requirements verified release-gate check on a cycle. | Covers requirement |
Choose the semantic type carefully — it decides which side of the product the link shows up on. A Defect-semantic link is counted against defect metrics; a Requirement-semantic link is counted as coverage; a General link is counted as neither.
A “Defects” view shows General links too. This surprises people, and it is deliberate. On a stock workspace only the Defect relation carries the Defect semantic — Verifies, Relates to, Blocks, Caused by and Duplicate are all General. If a Defects list showed Defect-semantic links only, it would hide most of the links your team has actually created. So the split that matters in practice is Requirement (coverage) versus everything else, and unclassified links are surfaced rather than silently dropped — see Unclassified links below.
Where you meet this split as a filter. The Test Cases surface exposes it directly: the Issue relation filter in Browsing & Search offers Requirements and Defects, and picking Defects there follows exactly the rule above — every non-Requirement link, General ones included. It is the first place the semantic is something you pick rather than something that happens behind a count.
The built-in Covers requirement relation
Every workspace ships with a system-defined relation called Covers requirement carrying the Requirement semantic. It is what makes a ticket count as covered. Like every system-defined relation it can be renamed, disabled, or scoped to specific projects, but it cannot be deleted.
A single test case can link the same tracker issue under two different relations — for example Verifies and Covers requirement. That is supported on purpose, and it means the two families are memberships, not a partition: such an issue legitimately appears in both the Defects and the Requirements views.
Unclassified links
“Unclassified” is not a fourth semantic type you can choose — it is how run and cycle surfaces describe a General-semantic link. Because General means “nobody said what this link means”, those links cannot count as coverage, and a run whose cases are linked only through General relations will honestly report zero requirements verified.
Rather than hide that, the run surfaces name it: an amber chip reads N unclassified with the hover text Linked, but no relation set — set it to Covers to count as coverage, and the run’s coverage card offers a Classify links action. Reclassifying is a one-step change on the chip itself — see Changing a link’s relation.
Which relation gets picked for you
You can always choose the relation yourself. When you do not, TestOrchestrator preselects one from where you were standing when you created the link, because the same action means different things in different places.
| Where you linked from | Preselected relation | Why |
|---|---|---|
| A test case — the case editor or case detail | Covers requirement | Linking a ticket to the case itself is a statement about what the case is for. That is coverage. |
| A result — the runner, the fail→issue prompt, an exploration finding | The first Defect-semantic relation | Linking from an execution is a statement about what broke while running it. |
| Anywhere else — a run, a cycle, an integration dashboard | Relates to | The context does not imply a meaning, so nothing is assumed. The link lands unclassified, visibly, rather than being given a meaning nobody claimed. |
If your administrator has disabled or unscoped the relation a context would normally pick, the preselection falls back to Relates to, and then to any enabled General relation. That fallback is intentional: an unclassified link is a visible state you can fix, whereas guessing would quietly invent coverage.
Cases created from a ticket are linked as coverage. When AI test-case generation or the MCP
create_test_casetool builds a case from a tracker issue, the resulting link is authored as Covers requirement — a case generated from an issue covers that issue. The MCPlink_to_issuetool is different: it is a general-purpose linking tool with no execution or authoring context to read, so it defaults to Relates to unless you pass a relation explicitly. It will not manufacture coverage nobody asked for.
Changing a link’s relation
A relation is not fixed at creation. On a linked-issue chip, click the relation label to open a small picker and choose a different relation. The change applies immediately and the link moves to the matching view — a link reclassified from Relates to to Covers requirement starts counting as coverage in every open run and cycle without a page reload. If the change cannot be saved, the chip reverts to its previous relation.
Changing a link’s relation needs the Manage external references permission on the project — the same permission as creating or removing a link. It is not an administrator-only action: the default QA Engineer role has it. Editing the relation catalog described below is a separate, workspace-level administrator permission.
Colour follows the semantic, not the name. A relation chip is tinted from its semantic type — green for Requirement, red for Defect, amber for an unclassified General link — so renaming a relation cannot change what it looks like it means. Colour is never the only signal: each chip also carries a distinct glyph and descriptive hover text.
Creating a relation
Navigate to Admin → External References → Relations and click Add Relation.
- Display name — the label project members see when selecting a relation (e.g., Relates to, Defect).
- Semantic type — General, Defect, or Requirement (see above).
- Enabled — controls whether this relation appears as an option in projects.
- Project scope — All projects or Specific projects (see Project assignment).
System-defined relations
System-defined relations are built-in and cannot be deleted. You can still disable them, edit their display name, and change their project scope — but they will always exist in the workspace.
Editing a relation
Click the edit (pencil) icon on any relation row to open the editor. You can change the display name, semantic type, enabled state, and project scope. Changes take effect immediately — existing links that use this relation are not affected by a display name change, but they will inherit the updated semantic type for any future reporting calculations.
Enabling and disabling relations
Use the toggle on each relation row to enable or disable it.
- Enabled — the relation appears as an option when project members add external references.
- Disabled — the relation is hidden from the add-reference flow and cannot be selected for new links. Existing links that use the relation are not removed and continue to display with the relation label.
Project assignment
Use project assignment to control which projects can use a relation.
- All projects — the relation is available in every project, including projects created in the future.
- Specific projects — only the selected projects can use this relation. At least one project must be selected when this option is chosen.
Changing project assignment does not affect existing links — it only controls whether team members can select this relation for new links in the relevant projects.
Deleting a relation
Click the delete (trash) icon on a relation row to begin deletion. What happens next depends on whether any existing external links use this relation.
No existing links
If the relation has never been used to create a link, a simple confirmation dialog appears. Confirm to delete the relation permanently.
Relation in use — replacement required
If this relation has linked references, you must select a replacement relation before deletion can proceed. All existing links that use this relation will be reassigned to the replacement relation automatically. The original relation is then deleted. This prevents orphaned references from losing their semantic label.
When a relation is in use, the deletion dialog shows:
- The number of linked references that will be reassigned.
- A dropdown to choose the replacement relation — all other enabled relations are available as options.
Select the replacement that best represents the existing links and confirm. All links are migrated to the replacement atomically before the original relation is removed.
System-defined relations cannot be deleted even if they have no linked references. Use the toggle to disable them instead.