• Products
  • Documentation
  • Resources

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).

If you’re an Atlassian Marketplace user, you may be looking for help on using the legacy Jira issue macro.

You can paste a link to a single Jira issue using Smart Link display options.

Insert Jira issues in Confluence

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:

Select Jira issues from Confluence editor chevron

Option 2 

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

Select Jira issues from /jira in Confluence

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.

Learn how to search for Jira issues using JQL (Jira Query Language).

  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.

Search for Jira issues and insert in Confluence

Manage field columns

Once your Jira issues are displayed as a table, 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:

  1. When editing, select from the toolbar

  2. Find the macro by name and select it

  3. Configure it as needed

You can also type / on the page to bring up the same list you'd see by selecting from the toolbar. Continue typing the name of the macro to filter the list.

To edit the Jira legacy macro:

  1. Select the macro placeholder.

  2. Select the Edit icon to open the configuration panel.

  3. Configure the parameters. Your changes are saved as you go.

  4. Resume editing the page, and the panel closes.

You can also select the centered , medium-width , and full-width icons to adjust the width of some macros. Select the trashcan iconto remove the macro.

See what the Jira macro looks like after being inserted into a Confluence page

You can use the macro to display a table 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 Software documentation.

To display a table 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 table of issues.

  7. Select Insert.

See the display options available with the Jira macro that let you control how the information is presented

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.

Auto-convert: You can paste URLs directly into the Confluence editor (without calling up the macro browser). Confluence will automatically convert the URL into a Jira Issues macro.

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 table 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

Apps cannot be disabled in Atlassian Cloud applications. To stop using an app, you must either uninstall, or unsubscribe, which cancels your subscription to the app.

Additional Help