Link Jira work items and Confluence pages
10 min
Intermediate
By the end of this lesson, you’ll be able to:
- Create a Confluence page from Jira
- Add links to Confluence pages in Jira work items
- Add links to Jira work items on Confluence pages
- Use smart links between apps
Create Confluence pages from Jira
Pages are created and maintained in Confluence, but you can initiate, link, and collaborate on them from within Jira, ensuring a seamless workflow between the two platforms. They are available for team-managed and company-managed software spaces.
Pages can be enabled from the Features section. If you want to edit a page in Confluence, you can click the Open in Confluence link at the top of the preview window.
👇 This is how you can open a previewed page in Confluence.
Link content between Jira and Confluence
Because work items represent your work, they often reference content available in Confluence pages. Linking these pages helps everyone to stay aligned and limits duplicate information. Pages can change location or title and remain linked to the work item. Any changes reflect automatically.
To link a Jira work item to a Confluence page:
- Open a Jira work item.
- Select the + dropdown, and select Page.
- Select Link page. You can also create a new page by clicking Create page.
- Search for a Confluence page or paste the page URL. You can also filter by Confluence space here.
- You will also see AI suggest some pages that you can link to the work item.
- Select Link.
- View your Confluence page linked in your Jira work item.
👇 Here’s how your Confluence link will appear in a work item.
If you link a Jira work item to a Confluence page, you will see the link to the Jira work item in the Show Details section on the bottom right of the page. This is an easy way to see all linked Jira work items and navigate to them.
👇 Here’s how Confluence displays a pages work item summary.
Use a macro to link Jira work items on pages
The Jira work items macro allows users to add links to related Jira work items on Confluence pages with an efficient JQL editor. The link automatically provides the current status and summary of the listed work item. Pages with links to Jira work items are automatically listed on those work items in Jira to create a two-way link. Pages show a summary of all the work items listed on the page.
👇 This is how a list of Jira work items is displayed in Confluence using the Jira work items macro.
To add the Jira work items macro to a Confluence page:
- In the main toolbar, select Insert elements (represented by +) or type / on the Confluence page.
- Type “Jira” and select the Jira work items macro from the list.
- In the macro configuration window, search for the work item or work items that you would like to link to.
- From the dropdown in the top right, select either List or Inline link.
- If you select List view, then you can configure the work item's fields displayed. You can also adjust these once the macro is on the page.
- Select Insert results.
Jira work items added in a list through a JQL query are called a dynamic list. Dynamic lists will update as work items update in Jira and match the JQL search.
👉 For example: A JQL searches for all work items linked to the Epic IAD-8 and lists them on a Confluence page. As more work items are created and linked to the epic, they are automatically listed on the Confluence page along with the original work items that were results from the original search.
Use smart links to quickly preview content
You can paste URLs to Jira work items straight into Confluence as an alternative to the Jira work items macro. The URL automatically converts to a Smart Link, which shows a quick preview of the linked information and dynamically updates.
👇 This is what a work item smart link looks like in Confluence.
To learn more about Smart Links and the other apps they work with, visit Atlassian documentation.
How was this lesson?
next lesson
Develop Jira work items using Confluence
- Create a single Jira work item in Confluence
- Use existing content to create multiple Jira work items