Display Jira issues in a list

If your Confluence instance is connected to Jira, you can search and display Jira issues in a list on Confluence pages. You can then customize the display to add, remove, and reorder fields.

Make changes to your search with keywords, filters, or JQL (Jira Query Language).

Insert Jira issues

Edit a Confluence page or create a new one. You have 3 options to insert Jira issues:

Option 1

Select  from the toolbar and select Jira issues:

Option 2 

While editing a page, type /jira and select Jira issues:

Option 3

You have the option to search for issues in Jira and paste the search filter URL into a Confluence page.

Search for issues 

Start inserting Jira issues by using filters with basic keyword search or with JQL.

1. BASIC is selected by default. With this option, you can use filters and keywords to search for issues.

2. If you select JQL, enter your query or search keywords. For example, project = 'Starfish'

3. Select COUNT VIEW if you want to display just the number of issues.

4. Select Insert issues.

Manage field columns

Once your Jira issues are displayed as a list, you can drag columns to move them around. Choose the columns you want to appear by selecting the column icon .

Edit your issues

If you need to make changes to your search query, select the pencil icon at the bottom of the list.

Resize the width of the list by selecting the expand icon from the side.

Using the Jira legacy macro for Marketplace app users

Using the Jira macro, you can:

• Display a list of issues on your page, based on a Jira Query Language (JQL) search, filter or URL.

• Display a single issue.

• Display a count of issues.

• Create new issues and display the issues on your page without leaving Confluence.

Use the Jira legacy macro

To add the Jira legacy macro:

To edit the Jira legacy macro:

Displaying issues via a Jira Query Language (JQL) search

You can use the macro to display a list of issues on your page, based on the results of a search using Jira Query Language (JQL).

JQL is a simple query language that is similar to SQL. A basic JQL query consists of a field, followed by an operator (such as = or >), followed by one or more values or functions.

Examples:

• The following query will find all issues in the 'TEST' project:

  1 2 3 4 project = "TEST"

• The following query will find all issues in the 'documentation' component of the  'CONF' project:

  1 2 3 4 project = CONF and component = documentation

For more information about JQL syntax, see Advanced searching in the Jira documentation.

To display a list of issues based on a JQL search:

1. Insert the Jira macro onto your Confluence page, as described above.

2. Choose a Jira instance next to the Search button.

3. If prompted, log in to the Jira instance.

4. Enter the JQL query into the Search box.

5. Select Search.

6. If you want to customize the display, select Display options and adjust the columns and number of issues that will appear in your list of issues.

7. Select Insert.

Displaying issues via a Jira URL

You can paste any of the following Jira application URLs into the Jira Issues macro. Confluence will immediately convert the URL to a JQL search.

• Any URL for an issue search or filter.

• A URL for a single issue.

• The URL of the XML view of a search.

Displaying a single issue, or selected issues

To display a single Jira issue, choose one of the following methods:

• Paste the URL of the issue directly onto the Confluence page. (There is no need to use the macro browser.) Confluence will auto-convert the link to a Jira Issues macro.

• Or: Add the Jira issues macro to the page as described above, and choose Recently Viewed to see the issues you have visited recently. Select an issue and choose Insert.

• Or: Add the Jira issues macro to the page as described above, and paste the issue URL into the search box in the macro browser.

• Or: Add the Jira issues macro to the page, define your search criteria in the macro browser via JQL as described above, then select the check box next to the issue in the search results, within the macro browser.

You can choose to show just the issue key, or the issue key and a summary. Select the macro placeholder and choose Show Summary or Hide Summary. 

To display a subset of Jira issues from your search results:

1. Add the Jira issues macro to the page.

2. Define your search criteria in the macro browser via JQL, as described above.

3. Select the check boxes next to the required issues in the search results, within the macro browser.

Displaying a count of issues

You can choose to display the number of issues returned by your search, rather than a list of issues. The Jira Issues macro will display a count of issues, linked to the search in your Jira application.

To display an issue count:

1. Add the Jira Issues macro to the page.

2. Define your search criteria in the macro browser via JQL, as described above.

3. Select Display options, then select Total issue count next to 'Display options' in the macro browser.

4. Select Insert.

Creating a new issue 

While editing a Confluence page, you can create an issue in Jira and display it on your Confluence page, without leaving the Confluence editor.

To create an issue and add it to your page:

1. Add the Jira Issues macro to the page, as described above.

2. Select Create New Issue.

3. Supply the information about your Jira instance, project, and issue, as prompted.

4. Select Insert.

Confluence will send a request to your Jira application, to create the issue, then display the newly created issue on your page.

Limitations

The Jira legacy macro will notify you if it is unable to create an issue in the selected project. This may be because the project has a required field, field configuration or other customization that is not supported by the Jira legacy macro. In this situation you will need to create the issue directly in your Jira application.

Rendering HTML from Jira applications

Formatted fields from Jira can be displayed in Confluence if you set up a Confluence-to-Jira application link. Otherwise, such formatted fields will be escaped within the output of the Jira legacy macro. This is to prevent the possibility of malicious HTML being served by an untrusted Jira instance. The most likely field where you will notice this is in the description field.

Disabling the Jira legacy macro