Linking and referencing documents in Jira issues

Owned by David Claudia
Last updated: Nov 11, 2024
4 min read

mOn this page

Linking documents to Jira issues

You can link documents or folders to Jira issues by using the Link action of a Jira issue.

Follow these steps to link a document or folder to a Jira issue:

  • Open the Jira issue that you want to link the document to

  • Select More > Link to display the Link dialog box

  • Click the Document option from the left of the dialog box

  • Search for the document that you want to link. If you want to link a document from a project other than the current Jira project, select that project in the drop-down list near the search box

18.1.Link-doc---panel.png

The drop-down list contains only the projects for which the current user has view permissions.

  • In the search results table, click the Select link from the row of the document that you want to link

18.1.Link-doc---panel.png

  • Optionally, add a Comment to describe why you are linking the document

  • Click the Link button at the bottom of the dialog

  • The document you just linked is now listed under the Links section of the Jira issue.

Viewing the Jira issues linked to a document

To view the Jira issues that are linked to a specific document:

  • In Jira, go to Projects

  • Make sure you are on the right project

  • Click the Documents tab

  • Locate the document and click on its Linked Issues... option under the Actions menu. The Jira issues that are linked to the document will be displayed

Referencing documents in Jira issues

You can add references to documents or folders in the Jira fields (such as Description) or in comments. The way to do this depends on what edit mode is currently used.

In Text mode, this can be done via the {doc-key} macro.

For example, if the Key of your document is 180 (the Key of the document can be visualized in the Documents tab of the Jira project), you can add a reference to that document by entering the following text in the Jira field: {doc-key}180{doc-key}

A comment like this...

... will be displayed like this...

The text displayed by the macro depends on the type of document represented by the specified key.

  • If the key represents a document of type File, the macro displays the Title of the document as a link that allows downloading the newest file attached to the document.

  • If the key represents a document of type URL, the macro displays the Title of the document as a link that opens the URL associated with the document.

  • If the key represents a folder, the macro displays the Name of the folder as a link that displays the folder's content.

  • If the key is invalid or an error occurs, the macro displays an error message in red text.

The macro works only for the Jira fields that are configured to use the Wiki Style Renderer.

If the Rich Text Editor is enabled in your Jira instance, you can add references to your documents while in Visual mode.

  • Click the Document Link option from the insert menu

  • Search for and then select the document that you want to link

  • A link to the document will be inserted in the field

Â