Inserting JIRA Issues

If your Confluence site is connected to a JIRA site via an application link, you can easily insert individual issues from this JIRA site directly into text on your Confluence page using the 'Insert JIRA Issue' dialogue box. Each issue inserted onto the page is linked to the issue in JIRA itself.

Using the 'Insert JIRA Issue' dialogue box, you can also:

Create a new issue on the JIRA site and insert the issue onto your page.
Insert a table of JIRA issues onto your page based on the results of a search (using JIRA Query Language (JQL) syntax).

Furthermore, you can insert JIRA issues on a page using 'shorthand' notation directly within the editor.

If your Confluence site is not connected to any JIRA site via an application link, this feature will not be available. However, you can still list JIRA issues on a page or blog post using the JIRA issues macro.

On this page:

Quick guide to inserting JIRA issues

Click the insert JIRA issues icon on the editor toolbar.
- To insert a single issue, select one of these options on the 'Insert JIRA Issues' dialogue box:
  - 'Recently Viewed' — Insert an issue onto your page from a list of issues you have recently viewed on the JIRA server.
  - 'Create New Issue' — Create a new issue in the JIRA server and insert it onto your page.
  - 'Search' — Use JQL syntax to narrow down a list of issues, from which you can select one to insert onto a page.
- To insert a table of issues:
  - Select 'Search' on the 'Insert JIRA Issues' dialogue box, use JQL syntax to narrow down a list of issues and choose to insert the list onto a page.

If Confluence is connected to more than one JIRA server, ensure that you choose the appropriate JIRA server before using this dialogue box to select, create or search for issues.

Wiki Markup Editor and Rich Text Editor

You can click the 'Insert Link' icon in either Wiki Markup mode or the Rich Text Editor. The functionality described below is the same for both editing modes.

Inserting JIRA Issues Using the Dialogue Box

Inserting a JIRA Issue from a List of Recently Viewed Issues

To insert a JIRA issue onto a page from a list of recently viewed issues on a JIRA site:

Place your cursor at the point where you want to insert your JIRA issue.
Click the insert JIRA issues icon on the editor toolbar to open the 'Insert JIRA Issues' dialog box.
Click the 'Recently Viewed' option on the left (if not already selected).
If Confluence is connected to more than one JIRA server, select the appropriate JIRA server whose issues you want to insert from the 'Server' dropdown. If otherwise, this dropdown will not be available.
If Confluence connects to your JIRA server using OAuth outgoing authentication (refer to notes below for more information), you may need to click 'Login & Approve' at this point to gain access to the JIRA server and restricted issues.
Select an issue from your list of recently viewed JIRA issues on the JIRA site.
As defined by JIRA, the last 50 issues you viewed in JIRA are shown.
Click the 'Insert' button to insert that issue on the page.

Creating a New JIRA Issue and Inserting it

This feature works best with JIRA issue types whose mandatory field requirements have not been altered. With the exception of a JIRA issue's 'Component/s' or 'Fix Version/s' fields, you cannot use this dialogue box to add an issue whose issue type has customised mandatory field requirements upon issue creation.

To create a new JIRA issue on a JIRA site and insert this issue onto a page:

Place your cursor at the point where you want to insert your JIRA issue.
Click the insert JIRA issues icon on the editor toolbar to open the 'Insert JIRA Issues' dialogue box.
Click the 'Create New Issue' option on the left (if not already selected).
If Confluence is connected to more than one JIRA server, select the appropriate JIRA server whose issues you want to insert from the 'Server' dropdown. If otherwise, this dropdown will not be available.
If Confluence connects to your JIRA server using OAuth outgoing authentication (refer to notes below for more information), you may need to click 'Login & Approve' at this point to gain access to the JIRA server and create a new issue.
Select the project on this JIRA server to which the new issue will be added. Upon choosing a project, more mandatory fields (specific to your project and issue type) will appear on the dialogue box, such as Component/s and (Fix) Version/s.
Complete the remaining fields on this dialogue box:
- 'Issue Type' — Choose the type of issue to log in this project.
  Issue types with customised mandatory field requirements upon issue creation may not be available from this list.
- 'Summary' — Enter a one-line summary for the issue.
- 'Component/s' — Choose one or more components which apply to this issue.
- 'Version/s' — Choose one or more versions in which the issue will be addressed.
- 'Description' — Enter a more detailed description about the issue.
  Some of these fields may not be visible if they have been customised in your JIRA project.
Click the 'Insert' button to create the JIRA issue and insert it onto the page.

Searching for JIRA Issues and Inserting them

To search a JIRA site for a subset of issues matching a JQL query and insert one or more of these issues:

Place your cursor at the point where you want to insert your JIRA issue.
Click the insert JIRA issues icon on the editor toolbar to open the 'Insert JIRA Issues' dialogue box.
Click the 'Search' option on the left (if not already selected).
Enter a JQL query into the first field.
If Confluence is connected to more than one JIRA server, select the appropriate JIRA server whose issues you want to insert from the second field's dropdown. If otherwise, this dropdown will not be available.
If Confluence connects to your JIRA server using OAuth outgoing authentication (refer to notes below for more information), you may need to click 'Login & Approve' at this point to gain access to the JIRA server and restricted issues.
Click the 'Search' button to find the issues on the JIRA server which match your JQL query.
This dialog box shows a maximum of the first 20 issues retrieved by your JQL query.
If you wish to insert a single issue, select the issue from your list and click the 'Insert' button.
If you wish to insert the full list of issues retrieved from JIRA by your JQL query, select the 'Insert all query results as a table' check box before clicking the 'Insert' button.

Inserting JIRA Issues Directly within the Editor

You can also use the following 'shorthand' notation within the editor to do the following:

To show individual issues from a JIRA site directly within text on a Confluence page, the syntax is:

{jira:<Issue key>|server=<JIRA site name>}

For example,

The {jira:EXAMPLE-1|server=Example Company JIRA Site} bug has been causing us major headaches over the last few months.

To show a list of specific issues from a JIRA site, the syntax is:

{jira:<Issue Key 1>, <Issue Key 2>, <Issue Key 3>, etc.|server=<JIRA site name>}

To show issues based on a JQL query from a JIRA site, the syntax is:

{jira:<JQL Query>|server=<JIRA site name>}

For example,

{jira:summary ~ example|server=Example Company JIRA Site}

Notes

The issues from a JIRA site which you can access in the 'Insert JIRA Issues' dialogue box depends on the application link's outgoing authentication used by Confluence to communicate with that JIRA site. While you can always access publicly visible issues:

If 'Trusted Applications' outgoing authentication is used — you can also view issues restricted to an account on JIRA whose user name matches your user name in Confluence.
If 'OAuth' outgoing authentication is used — you can also view issues restricted to the user account that you 'Login & Approve' (to the JIRA site) on the 'Insert JIRA Issues' dialogue box.
If 'Basic Access' outgoing authentication is used — you can also view issues restricted to the user account configured for the JIRA site's 'outgoing authentication'.

Child pages