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 (this is used when issues are cloned)

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 organisation, 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 organisation does not require the ability to link issues, you can disable it globally for all users as described below.

 

Adding a link type

To create a new link type, e.g. 'Causes':

  1. Log in as a user with the JIRA Administrators global permission.
  2. Choose > System. Select Issue Features > Issue Linking to open the Issue Linking page.
    (tick) Keyboard shortcut: g + g + start typing issue linking
  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.

To edit or delete a link type:

  1. Log in as a user with the JIRA Administrators global permission.
  2. Choose > System. Select Issue Features > Issue Linking to open the Issue Linking page.
    (tick)Keyboard shortcut: g + g + start typing issue linking
  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 site or pages on a Confluence site (running Confluence version 4.0 or later). To do this, create fully reciprocal application links between your JIRA site to the remote JIRA or Confluence site. 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 configure fully reciprocal application links between your JIRA site and a remote JIRA or Confluence site:

  1. Log in as a user with the JIRA System Administrators  global permission.
  2. Create an application link to your remote JIRA or Confluence site. (See Adding an Application Link  for details.) When creating the link:
    • During step 2 of the wizard, ensure you choose the option to create a link from the remote server back to your server.
    • 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 site and a Confluence site, ensure that the Confluence site'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:
    • Will see Failed to load messages in the Confluence Wiki page links they create on JIRA issues.
    • 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 site to a remote JIRA site or Confluence site. 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

To disable issue linking for your entire JIRA site, for all users:

  1. Log in as a user with the JIRA Administrators global permission.
  2. Choose > System. Select Issue Features > Issue Linking to open the Issue Linking page.
    (tick)Keyboard shortcut: g + g + start typing issue linking
  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 administrators can 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 Settings page.

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

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport