DATA CENTER AND SERVER | CLOUD
How to Configure Jira Links to support Traceability
Overview
Important features of easeRequirements for Jira, such as the Coverage View and the Traceability Matrix depend on linking. Therefore, it is important that an organization have a well thought-out link configuration in its Jira installation. This page explains issue linking in Jira, how to configure link types and recommends a model for creating link types to be used in a Requirements Management solution to support traceability.
Jira linking
Jira conceives of a link between issues as having two properties:
outward description
inward description
Rather than trying to explain these properties abstractly, here is a concrete example of a link type that comes with Jira to support the built-in operation of cloning:
Name | Outward Description | Inward Description |
|---|---|---|
Cloners | clones | is cloned by |
When you clone issue A, a new issue B is created. The relationship can be understood by forming two statements describing the relationship between the issues:
A is cloned by B.
B clones A.
The first statement, with A as the subject, is formed using the Inward Description. The second statement, with B as the subject, is formed using the Outward Description. If you are viewing issue A in Jira, you’ll see the relationship presented as #1. The meaning is obvious. In particular, it is completely clear which is the original issue and which is the clone. If you are viewing issue B in Jira, you’ll see the relationship presented as #2. The meaning is again obvious. Note that statement #1 is in the passive voice while sentence #2 is in the active voice.
There is no inherent meaning in the terms that Jira uses – “outward” and “inward”. However, you should note that if you were to reverse the descriptions in the Cloners configuration, you would undermine the built-in cloning operation, with the result that the relationship between the original issue and the cloned issue would not appear correctly in Jira: It would look as if the cloned issue were the original issue. So whether we like how Jira uses these terms or not, we are stuck with it, and subsequently created link types should be configured in the same way.
In addition to directional link types such as Cloners, Jira supports bidirectional link types such as the builtin type “Relates”. A bidirectional link type has the same outward and inward descriptions (e.g. “relates to”) and indicates a symmetric relation: If issue A relates to issue B, then, necessarily, issue B relates to issue A. Bidirectional link types usually convey little information and, since they are unlikely to be valuable in traceability practices, we will not consider them further.
Recommendations for link configuration
We strongly suggest that the directional link types you create to support your organization’s solution be configured using Cloners as the model:
Use a passive verb construction as the Inward Description (e.g. “is cloned by”).
Use an active verb construction as the Outward Description (e.g. “clones”).
In fact, when you create a new link type Jira offers hints about creating a type called “Duplicate”, with link descriptions formed in exactly this manner.
The exact link types you need for your solution depend on the sort of items you want the solution to manage and the relationships between them. Therefore, we cannot recommend specific link types. Instead we present an example that may help you develop your own solution. Generally, Requirements Management solutions involve a hierarchical organization of artifacts – simplified example of different used levels:
Requirements
Specifications
Development Tasks (Epics, Stories)
Test Cases
We recommend that you first establish the hierarchy appropriate for your organization and then start at the top and work down from level to level, at each level forming two statements about the relationship between linked issues:
The first statement is in the passive voice with an issue at the higher level as the subject and the issue at the lower level as the object.
The second statement is in the active voice with an issue at the lower level as the subject and the issue at the higher level as the object.
The following link type configuration might result:
Name | Outward Description | Inward Description | Statements |
|---|---|---|---|
Specification | specifies | is specified by |
|
Implementation | implements | is implemented by |
|
Test | tests | is tested by |
|
Note that instances of each link type unambiguously describe the relationship between the issues. For example, if we see that A is specified by B, we know that B is the issue doing the specifying and A is the object of the specifying. Similarly for the other link types.
If you do not want to commit the solution to specific link types, then you can create a generic type that can be used to link issues in the hierarchy while also supporting traceability features of Requirements for Jira, such as the Coverage View and the Traceability Matrix:
Name | Outward Description | Inward Description | Statements |
|---|---|---|---|
Trace | traces from | is traced to |
|
A disadvantage of using such a generic link type is that the relationship between linked issues is not as clear as it is when a specific type is used. For example, if we see that Requirement A is traced to Specification B, we perhaps understand that B is some sort of specification of A and not vice-versa. But users may be confused about when to use “is traced to” as opposed to “traces from”, since the difference is not as obvious as that between “is specified by” and “specifies”. Some amount of user education will probably be needed to implement this solution consistently.
Use of arrows
In some displays in Requirements for Jira, arrows are used as a shorthand for link descriptions, particularly when space is at a premium such as the Traceability Matrix. The arrows have no inherent meaning and simply stand for the respective link descriptions, as follows:
Display | Outward Description | Inward Description |
|---|---|---|
Issue Detail View | ->
| <- |
Traceability Matrix | 
| 
|
If, for example, the link results from the Jira clone operation on issue A, then the Issue Detail View shows:
A ← B, which means “A is cloned by B”.
B → A, which means “B clones A”.
In the case of bidirectional link types (e.g. “Relates”), both arrows are combined into one arrow pointing in both directions.