Linking issues | Jira Software Data Center 9.17 (2024)

Issue linking allows you to create an association between two existing issues on either the same or different Jira servers. For example:

  • An issue may relate to another.
  • An issue may duplicate another.
  • An issue may block another.

Issue linking also allows you to:

  • Create a new linked issue from an existing issue in a service desk or business project.
  • Create an association between anissueand a Confluence page.
  • Link anissue to any other web page.

Your Jira administrator cancustomizethe types of links that you can create, see configuring issue linking.

On this page:

Issue links within an issue look like this:

Linking issues | Jira Software Data Center 9.17 (1)

Note:Resolvedissues (i.e.issueswith a Resolution set) are displayed in strike-through font, e.g.DEMO-1.

To create links on issues, you need to have the Link Issues permission in the project(s) to which the issues belong.

Creating a link to another issue on the same Jira site

  1. Open the issue you wish to link to another issue in the same Jira site.
  2. SelectMore > Linkto display theLinkdialog box.
    Linking issues | Jira Software Data Center 9.17 (2)
  3. Ensure that theJira Issueitem is selectedatthe left of the dialog box and then choose the type of link to be created from theThis issuedrop-down list.
    Linking issues | Jira Software Data Center 9.17 (3)If your Jira system administrator has configuredfully reciprocalapplication linksbetween your Jira site and another one, aServerdrop-downlist may appear above theThis issuelist. If this is the case, ensure your Jira site appears or has been selected from theServerlist.
  4. In theIssuesfield, specify the issue(s) to be linked to your currently viewed/selected issue. There are two ways to do this:
    • Type the full issue key (e.g.ABC-123)— or to link to multiple issues, press the 'Enter' key between each typed issue key.
      Linking issues | Jira Software Data Center 9.17 (4)If you have previously browsed an issue, you can quickly find the issue by typing the first few letters of the issue key (or part of the Summary), which will appear in an 'autocomplete' drop-down list for selection:
      OR:
    • Click thesearch for an issuelink to use theFind Jira issuespopup, which allows you to perform either a simpletext searchor anadvanced searchfor issues.
  5. Optional: Add aCommentto describe why you are linking these issues.
  6. Click theLinkbutton at the bottom of the dialog.

Creating a link to an issue on another Jira site

Linking issues | Jira Software Data Center 9.17 (5)To create this type of link, your Jira system administrator should have configuredfully reciprocalapplication linksbetween your Jira site and the other Jira site containing the issue(s) you want to link to.

  1. Open the issue you wish to link to another issue.
  2. SelectMore > Linkto display theLinkdialog box.
  3. Ensure that theJira Issueitem is selectedatthe left of the dialog box.
    Linking issues | Jira Software Data Center 9.17 (6)Note:
    • This option will not be available if your Jira system administrator has not configured anapplication linkbetween your Jira site and the remote Jira site.
    • If, after selecting this option, you are prompted forauthorization, you may be required to log in to the remote Jira site, which will allowyourJira site to access the remote Jira siteon behalf of your account on the remote Jira site.
      Linking issues | Jira Software Data Center 9.17 (7)This behavior means the application links configured between your Jira site and the remote Jira site use OAuth authentication.
  4. If your Jira siteis connectedto multiple remote Jira sites, choose the relevant Jira site from theServerdrop-downlist.
  5. Choose the type of link to be created from theThis issuedrop-down list.
  6. Type theIssuekey of the issue on the remote Jira site that you want to link to. Alternatively, you can search for issues on the remote Jira site by clicking thesearch for an issuelink, which opens theFind Jira issuespopup.
    Linking issues | Jira Software Data Center 9.17 (8)You can link to any issue on the remote Jira site to which you have accessonthat site.
  7. Select theCreate reciprocal linkcheckbox to create the complementary link on the remote issue you are linking to, back to your issue. For example, if you create ablockslink typetoa remote issue, the reciprocal link generated on the remote issue will be ais blocked bylink type backto your local issue.
  8. Optional: Add aCommentto describe why you are linking these issues.
  9. Click theLinkbutton at the bottom of the dialog.

Troubleshooting

Linking issues | Jira Software Data Center 9.17 (9)Problem:If you selected theCreate reciprocal linkcheckbox, but after clicking theLinkbutton, you discover that a reciprocal link from the remoteissueback to yourissue has not been created, then your Jira system administrator has most likely created only a one-way link from your Jira site to the remote Jira site.

Linking issues | Jira Software Data Center 9.17 (10)Solution:Ask your Jira system administrator to configurefully reciprocalapplication linksbetween your Jira site and the remote Jira site.

Linking issues | Jira Software Data Center 9.17 (11)Problem:If you attempted to create a reciprocal link but received the following message:

'A reciprocal link from issue 'XYZ-123' back to this issue was not createdasthe remote Jira server returned the following error: No Link Issue Permission for issue 'XYZ-123'.' (where 'XYZ-123' is the issue key on the remote Jira site),

thena reciprocal link on the remote Jira site will not have been created, because the user account through which you authenticated on the remote Jira site (at step 3 above) does not have theLink Issues project permission.

Linking issues | Jira Software Data Center 9.17 (12)Solution:

  • Ask the Jira project administrator(s) on the remote Jira site to grant your user account the Link Issues project permission for the relevant project(s) to which you need to create issue links.
  • Alternatively, if the application link between your Jira site and the remote Jira site use OAuth authentication and you suspect you may have authenticated on the remote site with another user account that does not have the Link Issues project permission, repeat the procedure above but during theauthorizationstep (at step 3),authenticateon the remote site with a user account which has this permission.
    Linking issues | Jira Software Data Center 9.17 (13)If you are not prompted for authentication duringauthorization, try clearing your browser's cookies first and repeat the procedure again.

Create a new linked issue from an existing issue in a service desk or business project

To create a linked issue, you need to have Create issue and Linked Issuespermissionsin the destination project(s).

To create a linked issue:

  1. Open the issue from which you wish to create the linked Jira issue.
  2. Inthe Issue screen, selectMore > Create linked issue to display the Create Linked Issue dialog box
    The newly created linked issue contains the same Project, Issue Type, and Summary information stored in the original issue. It is also linked to the service desk issue, in this case CTF-2.
    Linking issues | Jira Software Data Center 9.17 (14)
  3. Select the destination Project in which the new linked issue is to be created.
  4. Select the correct Issue Type for the new linked issue.
  5. In theLinkedissues field, specify issue(s) to be linked to your new linked issue.
  6. Edit the linked issueSummary.
  7. Edit the Description anddescribe why you are linking these issues.
  8. Select theCopy attachmentscheckbox to include any attachments from the original issue.
  9. Select theCopy linkscheckbox to include any URLs from the original issue.
  10. Click the Create button at the bottom of the dialog.

Your linked issue has now been created.

Creating a link to a Confluence page

This feature is only supported in Confluence versions 4.0 or later.

Linking issues | Jira Software Data Center 9.17 (15)To create this type of link, your Jira system administrator needs to have configured anapplication linkbetween your Jira site and the Confluence site containing the pages you want to link to.

  1. Open the issue you wish to link to another issue.
  2. SelectMore > Linkto display theLinkdialog box.
  3. Click theConfluence Pageoption at the left of the dialog box.
    Linking issues | Jira Software Data Center 9.17 (16)This option is not available if your Jira system administrator has not configured anapplication linkbetween your Jira site and Confluence site.
  4. If more than one application link has been configured between your Jira site and other Confluence sites, then choose the appropriate Confluence site from theServerdrop-downlist.
  5. Specify the Confluence page to be linked to your currently viewed issue. There are two ways to do this:
    • In thePage URLfield, enter the URL of a page on the Confluence site you want to link to. For example:

      http://<confluence-server>/display/ds/Welcome+to+the+Confluence+Demonstration+Space
    • Click thesearch for a pagelink. TheLinkdialog box is replaced by theFind a Confluence pagedialog box.
      Linking issues | Jira Software Data Center 9.17 (17)If you are prompted forauthorization, you may be required to log in to the Confluence site, which will allowyourJira site to access the Confluence siteon behalf of your accountonthe Confluence site.
      This behavior means the application links configured between your Jira site and the remote Confluence site use OAuth authentication.
      1. In the firstSearchfield, specify one or more search terms that appear in the page you want to link to. This field is mandatory.
      2. Optional: In the secondSearchfield, select the Confluence space to further narrow down the search.
      3. Click theSearchbutton and then the title of the page you want to link to.
  6. Optional: Add aCommentto describe why you are linking these issues.
  7. Click theLinkbutton at the bottom of the dialog.

Troubleshooting

Linking issues | Jira Software Data Center 9.17 (18)Problem:IfConfluence pagelinks you create showFailed to loadon theissue or if you attempted to search for a Confluence page but received the following message:

'Content on the Confluence site could not be accessed because the Confluence server's 'Remote API' feature is disabled. The Confluence system administrator must enable this 'Remote API' feature for Jira to successfully access this content.'

thenJira was unable to communicate with the Confluence server to either:

  • retrieveinformation about the link or
  • conducta Confluence page search in theFind a Confluence pagedialog box.

Linking issues | Jira Software Data Center 9.17 (19)Solution:

Ask the Confluence system administrator to enable theRemote API (XML-RPC & SOAP)feature, since this Confluence feature is disabled by default. SeeEnabling the Remote APIin the Confluence documentation for details.

Creating a link to any web page URL

  1. Open the issue you wish to link to another issue.
  2. SelectMore > Linkto display theLinkdialog box.
  3. Click theWeb Linkoption at the left of the dialog box.
  4. Specify theURLof the web page you want to link to.
  5. Specify theLink Textthat will appear in theIssue Linkssection of the 'view issue' page and will behyperlinkedto your URL.
  6. Optional: Add aCommentto describe why you are linking these issues.
  7. Click theLinkbutton at the bottom of the dialog.

Deleting a link

  1. Go to an issue that contains links, and locate theIssue Linkssection.
  2. Hover your mouse over the link you wish to delete, and click theDelete(trashcan) icon that appears.

Searching forlinkedissues

You can search for issues that are linked to a particular issue. SeeAdvanced searching for more information.

Linking issues | Jira Software Data Center 9.17 (20)Be aware that this functionality does not extend to issues on a remote Jira server.

Linking issues | Jira Software Data Center 9.17 (2024)
Top Articles
Latest Posts
Article information

Author: Edwin Metz

Last Updated:

Views: 6697

Rating: 4.8 / 5 (78 voted)

Reviews: 93% of readers found this page helpful

Author information

Name: Edwin Metz

Birthday: 1997-04-16

Address: 51593 Leanne Light, Kuphalmouth, DE 50012-5183

Phone: +639107620957

Job: Corporate Banking Technician

Hobby: Reading, scrapbook, role-playing games, Fishing, Fishing, Scuba diving, Beekeeping

Introduction: My name is Edwin Metz, I am a fair, energetic, helpful, brave, outstanding, nice, helpful person who loves writing and wants to share my knowledge and understanding with you.