Show Jira Issues in Confluence: A Live List of Stories (Jira Work Items Macro)
Put a live list of Jira stories on a Confluence requirements page with the Jira work items macro and a short JQL query. The status on the page updates by itself when the team moves the work in Jira.
Step by step
Why a live list
- Jira list in Confluence. Your requirements are in Confluence and the stories are in Jira. You can put the stories straight onto the requirements page as a live list that keeps itself up to date.
Add the list
- Edit. Open the requirements page and click Edit.
- A new line. Click in the first line of the page. Press End to jump to the end of that line, then press Enter to start a new, empty line for the list.
- Slash Jira. Type /jira work items. The slash opens the insert menu and finds the Jira work items macro. Press Enter. A search window opens, where you choose which work items to show.
/jira work items - A JQL query. Switch to JQL, so you can say exactly which work items you want. Select anything already in the box and type project = SCRUM AND type = Story ORDER BY key. This asks for every story in the SCRUM project, sorted by key. Click Search.
project = SCRUM AND type = Story ORDER BY key - Check the results. The search finds 12 stories. Each one shows its key, summary, priority and status. Click Insert results to put the list on the page.
Share it
- Update. Click Update to publish the page, so everyone can see the list.
- Always up to date. The stories now sit on the requirements page. When the team moves a story in Jira, its status on the page changes too. Nobody copies anything by hand.
Recap
- Slash Jira, query, insert. In short: type /jira work items, switch to JQL, type your query, click Search and insert the results. The list stays live.
Pick the columns and the display
After you insert the list, click it and open its settings. You can choose which columns show, such as Status, Assignee, Fix version or Sprint, and how many items appear. Depending on your Confluence version, you can also show just one work item, or only the count of items that match your search, such as 12 stories in scope, which is handy at the top of a requirements page.
Create a Jira story from Confluence text
On a published page, select a line of text such as a requirement and click the Jira icon that pops up. Pick the project and work type, check the summary and create it. Confluence links the new story back to the page, so the requirement and the story stay connected, and you don't have to copy the text across by hand.
Other Jira macros worth knowing
The Jira chart macro turns the same kind of search into a pie chart or a created vs resolved chart, which is useful in a status report. If you only need one item on the page, paste its Jira link: Confluence turns it into a smart link that shows the item's current status.
Common mistakes
- Leaving the page without clicking Update. The list is only in your draft until you click Update. Publish the page so other people see the stories.
- Searching with plain words instead of JQL. A word search can pull in work items from other projects or miss some stories. Switch to JQL and name the project and type, like project = SCRUM AND type = Story.
- Using the wrong project in the query. If the project in your query doesn't match a real Jira project, the search finds nothing or shows an error. Copy the project key from a work item key, such as the SCRUM part of SCRUM-1.
- Copying statuses into a table by hand. A typed table goes out of date the moment the team moves a story. Insert the macro instead, so the status comes from Jira every time the page loads.
When a business analyst uses this
On a release's requirements page, add a list with project = SCRUM AND type = Story ORDER BY key under the scope section. In a sprint review or at sign-off, stakeholders see each story's current status right next to the requirements, and you don't have to keep a copied status table up to date.
Questions people ask
How do I display Jira issues in Confluence?
Edit the page, type /jira work items and press Enter. Search for the work items, using JQL if you want an exact list, then click Insert results and Update.
Does the Jira ticket status update automatically in Confluence?
Yes. The macro reads the status from Jira, so when the team moves a story in Jira, the status on the Confluence page changes too.
Can I show a filtered list of Jira issues in Confluence?
Yes. Switch to JQL in the search window and type a query, such as project = SCRUM AND type = Story ORDER BY key, to show only those stories in key order.
