Configuring issue linking
About issue linking
You can link Jira issues with each other to create associations. These Jira issues can be on the same Jira installation or another Jira server. For instance, you can use issue links to specify that one issue duplicates another, or its resolution depends on another's.
Issue linking also allows you to:
- create an association between a Jira issue and a Confluence page
- link a Jira issue to any other web page
When you link Jira issues together, you create a bi-directional connection between them:
a source issue that the link originates from has an Outward link to the destination issue (e.g. the issue that the link joins to)
a destination issue has an Inward link back to the source issue
For example, “Issue A” that is blocked by “Issue B” has an outward link of type is blocked by, which goes to “Issue B”. At the same time, “Issue B” has an inward link of type blocks that goes back to “Issue A”.
New installations of Jira come with four default types of links:
- relates to / relates to
- duplicates / is duplicated by
- blocks / is blocked by
- clones / is cloned by
You can add, edit or delete link types to suit your organization, as described below.
Before you begin
- To link issues, your users must have the Link issues permission.
- Issue linking is enabled be default. If you don’t want your team to link issues, you can disable it globally for all users, as described in this section.
- If you want to link Jira issues to issues on a different Jira server or to Confluence pages, see Configuring issue linking for external applications (below) for details on how to set this up.
For all of the following procedures, you must be logged in as a user with the Jira administrators global permission.
Add a link type
- In the upper-right corner of the screen, select Administration
> Issues.
- Under Issue features (the left-side panel), select Issue linking.
- In the Add new link type form, configure the following settings:
Name: enter the name of a new link type.
Outward link description: add a description of a link that’ll originate from the source issue.
Inward link description: add a description of a link that’ll join the destination issue.
- Select Add. You’ll be redirected to the Issue linking page with a new section listing the Caused link type.
Edit or delete a link type
We don’t recommend deleting the Clones link type as it’s used to automatically link issues when they are cloned.
To edit or delete a link type:
- In the upper-right corner of the screen, select Administration > Issues.
- Under Issue features (the left-side panel), select Issue linking.
- Go to the Operations column and select either the Edit or Delete link next to the link type you wish to edit or delete.
Configure issue linking for external applications
It is possible to create links to issues on a remote Jira instance or pages on a Confluence instance (running Confluence version 4.0 or later). To do this, create fully reciprocal application links between your Jira instance to the remote Jira or Confluence instance.
Fully reciprocal application links mean that:
- an application link must be configured on each server to the other.
- each of these application links must have both incoming and outgoing authentication configured to each other's servers.
To link your Jira instance and a remote Jira or Confluence instance:
- Log in as a user with the Jira System administrators global permission.
- Create an application link to your remote Jira or Confluence instance. (See Link to other applications for details.) When you create the link, make sure that:
- During step 2 of the Link applications wizard, you choose the option to create a link from the remote server back to your server.
- During step 3 of the wizard, you choose the These servers fully trust each other option. This will ensure that incoming and outgoing authentication is configured for the application link on each server to the other server.
If you configured a fully reciprocal application links between your Jira instance and a Confluence instance, ensure that the Confluence instance's system administrator has enabled the Remote API (XML-RPC & SOAP) feature. See Enabling the Remote API in the Confluence documentation for details.
If you don't enable the Remote API (XML-RPC & SOAP) feature, Jira can't communicate with Confluence. As a result, your users:
- will see "Failed to load" messages in the Confluence links they create or add to Jira issues.
- won't not be able to search for Confluence pages using the Find a Confluence page dialog box.
Althought you can create a one-way application link from your Jira instance to a remote Jira instance or Confluence instance, we recommend that you create fully reciprocal links instead.
A one-way link results in a partial loss of functionality for users when they create remote links. For example, when your users create a link to a remote Jira issue, they will find that the Create reciprocal link checkbox on the Link dialog won't function correctly.
Disabling issue linking
To disable issue linking globally for all users:
- In the upper-right corner of the screen, select Administration > Issues.
Under Issue features (the left-side panel), select Issue linking.
- If issue linking is enabled, select Deactivate. The Issue linking page reloads, stating that linking is disabled.
Configure the order of linked issues displayed on the View issue page
Jira system administrators can define the order in which linked issues are displayed in the Issue links section on the View issue page.
To change the order of linked issues, edit the value of the jira.view.issue.links.sort.order property on Jira's Advanced settings page. This property can accept the following individual field values:
- 'key'
- 'type'
- 'status'
- 'priority'
- resolution'
Specify the fields by which to sort issues by entering the appropriate 'value' for each field in a comma-separated list as shown here.
The jira.view.issue.links.sort.order property behaves similarly to a list of values specified after the ORDER BY keyword in Jira Query Language (JQL). That is, sort is performed by the first and then subsequent fields specified in the list.