Configuring issue linking

About issue linking

Issue linking allows you to create an association between issues on either the same or different JIRA servers. For instance, an issue may duplicate another, or its resolution may depend on another's. 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

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.

You can add, edit or delete link types to suit your organization, as described below.

(info) Note:

  • Your users must have the Link Issues permission before they can link issues.
  • Issue linking must be enabled in order for your users to be able to link issues. Issue linking is enabled by default. If your organization does not require the ability to link issues, you can disable it globally for all users, as described below.
  • If you want to link JIRA issues to those 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.

Adding a link type

  1. Choose  > Issues.
  2. Select Issue Features > Issue Linking to open the Issue Linking page.
  3. In the 'Add New Link Type' form at the end of the page:
    • Enter 'Causes' in the Name text field.
    • Enter 'causes' in the Outward Link Description text field.
    • Enter 'is caused by' in the Inward Link Description text field.
  4. Click the Add button.
  5. This returns to the Issue Linking page, with a new section listing the Causes link type.

Screenshot: the 'Issue Linking' administration page


Editing or deleting a link type

(info) It is recommended that you do not edit or delete the Clones link type, as this is used to automatically link issues when they are cloned.

  1. Choose  > Issues.
  2. Select Issue Features > Issue Linking to open the Issue Linking page.
  3. Locate the link type you wish to edit or delete, and click the link type's associated Edit/Delete link in the Operations column.

Configuring 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 configure fully reciprocal application links between 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 Using AppLinks to link to other applications for details.) When creating the link:
    1. During step 2 of the wizard, ensure you choose the option to create a link from the remote server back to your server.
    2. During step 3 of the wizard, 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, since this Confluence feature is disabled by default. See Enabling the Remote API in the Confluence documentation for details.
    (warning)  If you do not enable this feature, JIRA will not be able to communicate with Confluence. As a result, your users:
    1. Will see Failed to load messages in the Confluence Wiki page links they create on JIRA issues.
    2. Will not be able to search for Confluence pages using the Find a Confluence page dialog box.

(warning) Please Note: You can create a one-way application link from your JIRA instance to a remote JIRA instance or Confluence instance. However, some loss of functionality will be experienced by your users when they create remote links. For instance, if your users create a link to a remote JIRA issue, they will find that the Create reciprocal link check box on the Link dialog box will not function correctly. Hence, it is recommended that you create fully reciprocal links instead.

Disabling issue linking

  1. Choose  > Issues.
  2. Select Issue Features > Issue Linking to open the Issue Linking page.
  3. A status message indicates whether issue linking is enabled. If issue linking is enabled, click the Deactivate button. The Issue Linking page reloads, stating that linking is disabled.

Configuring the order of linked issues displayed on the 'view issue' page

JIRA system administratorscan define the order in which linked issues are displayed in the Issue Links section on the 'view issue' page. This is done by editing the value of the jira.view.issue.links.sort.order property on JIRA's Advanced settingspage.

Specify the fields by which to sort issues in the Issue Links section on the 'view issue' page by entering the appropriate 'value' for each field in a comma-separated list. This property behaves similarly to a list of values specified after the ORDER BY keyword in JIRA Query Language (JQL), whereby sorting is conducted by the first and then subsequent fields specified in the list.

The jira.view.issue.links.sort.order property can accept the following individual field values: 'key', 'type', 'status', 'priority' and 'resolution'.

Last modified on Apr 28, 2017

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.