Use Jira applications and Confluence together
Confluence and Jira are like bacon and eggs; coffee and cake; Simon and Garfunkel. Separately, they're great, but together, they're amazing!
If your Confluence and Jira sites are connected using Application Links, you can display and create Jira issues and more from within Confluence.
What you can do with Confluence and Jira depends on the Jira application, version, and how it is hosted. Find out about the required applications and versions later in this page.
On this page:
Want to learn how to integrate Confluence Cloud and Jira Software Cloud? Check out this guide.
For every project or team
Display issues on a page
You can display Jira issues on a Confluence page using the Jira Issues macro. Display a single issue, a list of issues, or show the total number of issues.
The simplest way to add a Jira issue to Confluence is to paste a Jira URL on a Confluence page.
<yourjirasite.com>/browse/CONF-1234will insert the Jira Issues macro and display a single issue.
<yourjirasite.com>/issues/?filter=56789will insert the Jira Issues macro and display a list of issues matching the saved filter.
<yourjirasite.com>/issues/?jql=project%20%3D%20CONFwill insert the Jira Issues macro and display a list of issues matching the Jira search.
Alternatively, you can add the Jira Issues Macro to the page and search for issues directly:
- In the editor choose Insert > Jira Issue.
- Follow the prompts in the macro browser to choose a project and search for an issue – you can even use JIRA Query Language (JQL).
Once you've added the macro, you can customize how the issue or list of issues appears on the page, including how much information to display, how many issues, and more.
Create reports and charts
Reporting on information stored in Jira is simple in Confluence. In addition to the Jira Issues Macro, you can use the Jira Report blueprint or Jira Chart macro to show information from your Jira application visually. It's the best way to give your stakeholders a snapshot of your team or project's progress.
- Use the JIRA Report blueprint to create a Change Log or Status report.
- Use the Jira Chart Macro to display data as a chart, including pie charts, created vs resolved, and two dimensional charts.
- Use JIRA Gadgets to display detailed Jira reports and charts on pages.
Create issues from inside Confluence
You can create issues while viewing a page or from the within the editor. This is really useful if you use Confluence for planning and gathering requirements.
To create an issue when viewing a page:
- Highlight some text on your page and choose the Create Jira issue icon that appears above the highlighted text.
- Enter your server (if you have multiple Jira sites connected to Confluence), project, issue type and description. Your highlighted text will populate the issue summary automatically.
- Choose Create.
The issue will be created in Jira and added to your page. If your text is in a table, you'll have the option to create multiple issues using text from the same column.
If you don't see a popup when you highlight text, check that Text Select is enabled in your profile settings.
To create an issue in the editor:
- In the editor choose Insert > Jira Issue > Create new issue.
- Enter your server (if you have multiple Jira sites connected to Confluence), project, issue type, summary, and description.
- Choose Insert.
The issue will be created in Jira and added to your page.
There are some limitations when creating Jira issues from Confluence. The Jira Issues macro or Create Jira Issue dialog will notify you if it's unable to create an issue in the selected project. You can find out more in the Jira Issues Macro page.
Move between Jira and Confluence
Whenever you add a link to JIRA issues in Confluence, or link to a Confluence page from your Jira application, the Jira Links button appears at the top of the Confluence page. This makes it really easy to jump from Confluence to Jira and vice versa, speeding up your workflow.
The number on the Jira Links button indicates the total number of issues, epics, and sprints connected to that page, regardless of whether you have permission to view them. The dropdown, however, will only show details of issues, epics, and sprints that you have Jira permissions to view.
The button doesn't detect links from issues displayed in the Jira Issues macro in table format.
Link to pages from Jira
When viewing an issue in Jira, you can link it to a relevant Confluence page.
How you do this depends on your Jira application, but there will be a Link option that will allow you to search for a Confluence page, or enter a URL.
If you use a Jira cloud application, the option to search for a Confluence Server or Data Center page is only available in sites that do not have Confluence cloud. This is because Jira defaults to search Confluence cloud, over any other linked Jira applications.
For software teams
Here's some suggestions to help you get the most out of Confluence and Jira Software and unleash the potential in your agile development team.
Define your requirements
Confluence is the perfect place to start defining your requirements. You can use the Product Requirements Blueprint to capture your requirements, then create your Jira epic and other issues right from the requirements page in Confluence.
Here's how it works:
- Create a Confluence page using the Product Requirements Blueprint.
- Choose the placeholder text 'Link to Jira epic or feature' and choose Create new issue to create your epic in Jira.
- Collaborate with your team to define your stories and save the page.
- Highlight text on your requirements page and choose the Create Jira issue link to create stories in Jira, and automatically link them to your epic.
- Track the progress of the stories from the Confluence page or from within Jira.
The tight integration between Confluence and Jira Software means you can easily access issues from the Confluence page and see their status at a glance, and from within Jira Software you can see links to related Confluence pages. All the information you need is right there.
If you have Jira Software Cloud, the option to automatically link issues created in Confluence to your epic is only available in Classic projects.
Manage your sprints
There's often a lot of material in Confluence that provides useful context for your team during a sprint. These might be requirements documents, designs, tech specs, customer research and more. By linking these pages to epics, you make them easy for your team to find during the sprint.
Here's how you can use Confluence to support your sprint from within Jira Agile:
- In Jira Software, create a Confluence page to plan your sprint. The page is created using the Meeting Notes Blueprint – a handy template that helps capture the details you need – and is automatically linked to the sprint.
- In an epic, link to useful Confluence pages, including requirements, designs, and more.
- Report on your progress to stakeholders using the JIRA Report blueprint in Confluence.
- Use the Retrospective Blueprint in Confluence at the end of your sprint to take stock of what went well and not so well.
For people who work mostly in Jira Software, the integration means that useful Confluence pages are only a click away.
If you have Jira Software Cloud, the option to create pages from your sprint is only available in Classic projects.
For service teams
Available for Jira Service Management (formerly Jira Service Desk) Server and Data Center only. If you use Jira Service Management Cloud, you cannot connect your project to a knowledge base space on a Confluence Server or Data Center site. You can only connect to a Confluence Cloud site. Read about how to migrate from Confluence Server to Cloud.
Provide self help resources for your customers
If you use Jira Service Management, you can help your customers resolve their issues without creating a request by connecting your service project to a knowledge base in Confluence. You'll need Confluence 5.10 or later.
In Jira Service Management, head to Project settings > Knowledge base to connect or create a Confluence space.
When customers search in the Customer Portal, pages in the linked knowledge base space will be suggested, allowing customers to help themselves.
Create knowledge base articles
The Knowledge Base space blueprint, along with templates for how-to and troubleshooting articles make creating new knowledge base articles super simple for your agents.
The templates used in the how-to and troubleshooting blueprints are completely customizable too. Set up the template with all your standard information and let your agents take it from there.
Allow any active user to see knowledge base spaces
If your Confluence instance is not public, you can still make a knowledge base space available via the customer portal.
When you link your service project to a Confluence space, you can choose to allow all active users and customers to see pages in the linked space, even if they don't have a Confluence license. These people get very limited Confluence access.
Unlicensed users can:
- View pages via the customer portal.
- Follow a URL to a page and then navigate within the linked space.
Unlicensed users can't:
- Like, comment on or edit pages (or be granted permission to do this).
- See the dashboard, user profiles, the people directory or space directory.
- Search the whole site.
This permission can only be enabled via Jira Service Management, but you can revoke access to the whole site or to particular spaces via Confluence's global permissions or space permissions.
Allowing all active users and customers to view a space will override all existing space permissions, so any logged in, licensed Confluence user will also be able to see the space (regardless of their group membership). This is due to the way Confluence inherits permissions.
Jira applications required
As you've seen, Confluence has many integration points, some of which are only available in particular Jira applications or versions.
This matrix outlines the specific Jira applications you'll need for each feature. We've also included:
- The minimum legacy Jira Server version (plus any add-ons) that you'll need if you're not using the latest Jira Server or Data Center applications.
- The minimum Cloud plan required, and whether there are any limitations on the project type or apps in your site (for example, some integrations won't be available if you also have a Confluence Cloud site).
|Feature||Jira Core||Jira Software||Jira Service Management (formerly Jira Service Desk)||Minimum legacy version||Jira Cloud plan|
|Display issues using Jira issues macro||Jira 4.3||Any|
|Display issue and project information using Jira chart macro||Jira 5.0||Any|
|Display issue and project information using the Jira Report blueprint||Jira 5.0||Any|
|Create an issue from Jira issues macro||Jira 4.3||Any|
|Create issues by highlighting text on a Confluence page||Jira 6.3.1||Any|
|Create issue by highlighting text on a Confluence page and automatically link issues to an epic||Jira 6.3.1 and |
Jira Agile 6.3.5
|Classic projects only|
|Link and create Confluence pages from epics and sprints||Jira 6.3.1 and |
Jira Agile 6.3.5
| Jira-only sites |
Classic projects only
|View linked issues with the Jira links button in Confluence||Jira 6.3.1||Any|
|Create a space using the Software Project space blueprint||Jira Software 7.0||Any|
Use a Confluence space as a knowledge base in the customer portal
|Jira 5.2 and |
Jira Service Desk 1.0
|Allow Service Management customers to view knowledge base articles without a Confluence license||Jira Service Desk 3.1|
Search for an existing Confluence page within the Jira link dialog
|Jira 4.3||Jira-only sites|
|Delegate user management to Jira||Jira 4.3|
|Add a Jira gadget to a Confluence page||Jira 4.3||Any|
That's it? Time to jump into Confluence and give some of these great features a try with your team or project.
Want to find out more about how to connect your Jira application to Confluence? Check out Integrating Jira and Confluence.