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 Relate to a user story, or a run might be linked to a Defect that it uncovered. 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. Used for any link that does not represent a defect. | Relates to, Implements, Covers |
| 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, Blocked by, Bug |
Choose the semantic type carefully — it affects how the link appears in reports. A link labelled Defect will be counted against defect metrics; a General link will not.
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 or Defect (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.