---
title: "Link types"
description: "Define the semantic labels for external links in TestOrchestrator — create General cross-references or Defect-type relations that appear in defect reporting."
source: "https://testorchestrator.com/docs/integrations/relations"
---

# Link types

A link type (called a _relation_ in earlier versions and in the API) 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](https://testorchestrator.com/docs/integrations/relations#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:

1. A **tracker** — which system the external item lives in (e.g., Jira)
2. The **external key** — the identifier of the specific issue (e.g., `PROJ-123`)
3. A **Relation** — the label describing the nature of the link (e.g., _Relates to_, _Defect_, _Blocks_)

Link types are independent of trackers — the same set of link types is available whichever tracker 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](https://testorchestrator.com/docs/integrations/relations#unclassified) below.

> **Where you meet this split as a filter.** The Test Cases surface exposes it directly: the **Issue relation** filter in [Browsing & Search](https://testorchestrator.com/docs/test-cases/browsing-and-search#filters) 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 counts them. Reclassifying is a one-step change on the chip itself — see [Changing a link’s relation](https://testorchestrator.com/docs/integrations/relations#changing-a-links-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](https://testorchestrator.com/docs/ai-test-generation) or the [MCP](https://testorchestrator.com/docs/mcp/tools) `create_test_case` tool 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 MCP `link_to_issue` tool 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.

## The Link types tab

Open **Admin → Integrations → Link types**. Every link type is listed with what it **Counts as**, where it is available and whether it is enabled. In the admin page the semantic type is called **Counts as**: _Reference_ is the General type and _Defect_ is the Defect type; the built-in _Covers requirement_ shows _Requirement_. Row actions are in each row's … menu.

## Creating a link type

Click **New link type**.

- **Name** — the label project members see when they link an issue (e.g., _Covers requirement_, _Regression_).
- **Counts as** — _Reference_ (related work, not a defect) or _Defect_ (counted as a defect found by testing).
- **Enabled** — whether it is offered in the link picker.
- **Available in** — _All projects_ or _Selected projects_ (see [Project assignment](https://testorchestrator.com/docs/integrations/relations#project-assignment)).

## Built-in link types

> **Built-in link types** carry a **Built-in** chip and cannot be deleted. They are always listed, even in a new workspace. You can rename them (their key stays the same), change where they are available, and disable them.

## Editing a link type

Choose **Edit link type…** in the row's … menu. You can change the name, what it counts as, whether it is enabled and where it is available. Existing links keep the link type; a change to what it counts as applies to them in reporting from then on.

## Enabling and disabling link types

Choose **Disable** or **Enable** in the row's … menu. The change is immediate, and the confirming message has an **Undo**.

- **Enabled** — offered when project members link an issue.
- **Disabled** — hidden from the link picker. Existing links that use it keep it and continue to show its name.

## Project assignment

- **All projects** — available in every project, including projects created later.
- **Selected projects** — only the projects you pick. You must pick at least one.

Changing where a link type is available does not affect existing links — it only controls whether it can be chosen for _new_ links in those projects.

## Deleting a link type

Choose **Delete link type…** in the row's … menu. The row briefly shows **Checking use** while TestOrchestrator counts the links that use it; what happens next depends on the answer.

### No existing links

A simple confirmation: “No links use it, so nothing else changes.” Confirm to delete it.

### In use — the links move first

> **If links use this type, you choose where they go before it is deleted.** The dialog shows how many links use it and asks you to pick a replacement under **Move links to**. Only enabled link types that count as the same thing are offered, so defect reporting does not change. **Move links and delete** reassigns every link to the replacement, then deletes the type.

If no other enabled link type counts as the same thing, the dialog says so: create or enable one first, or disable this one instead.

> **Built-in link types cannot be deleted** even if nothing uses them. Disable them instead.
