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.

Add a link type

1. In the upper-right corner of the screen, select Administration  > Issues.
   
   
2. Under Issue features (the left-side panel), select Issue linking.
3. 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.

4. 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

To edit or delete a link type:

1. In the upper-right corner of the screen, select Administration  > Issues.
2. Under Issue features (the left-side panel), select Issue linking.
3. 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:

1. an application link must be configured on each server to the other.
2. 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:

1. Log in as a user with the Jira System administrators global permission.
2. 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:
   1. During step 2 of the Link applications wizard, you choose the option to create a link from the remote server back to your server.
   2. 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.

3. 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.

Disabling issue linking

To disable issue linking globally for all users:

1. In the upper-right corner of the screen, select Administration  > Issues.

2. Under Issue features (the left-side panel), select Issue linking.

3. 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.