Displays a list of JIRA issues in a page.

JIRA is the issue tracking and project management system supplied by Atlassian. The JIRA Issues macro allows you to display a list of issues from a JIRA site on a Confluence page.

You can list publicly accessible issues from any JIRA site, as well as issues restricted to your user account on a JIRA site, assuming:

  • You are logged in to both the JIRA and Confluence sites, and
  • Your usernames on both of these sites match.

(tick) You can also create, find and insert JIRA issues directly within text on a Confluence page or blog post. For more information, refer to Inserting JIRA Issues.

Screenshot: Example of JIRA issues shown on a Confluence page

On this page:

Related pages:

Using the JIRA Issues Macro

To add the JIRA Issues macro to a page:

Refer to the instructions below for details on obtaining the URL of the XML view of a search. An example URL is:

http://jira.atlassian.com/sr/jira.issueviews:searchrequest-xml/temp/SearchRequest.xml?jqlQuery=project+%3D+CONF+AND+%28summary+%7E+jiraissues+OR+description+%7E+jiraissues+OR+comment+%7E+jiraissues%29&tempMax=10

Displaying a List of JIRA Issues from any Accessible JIRA Site

Step 1 — Obtain the URL of the Issue Filter

  1. Log in to your JIRA system.
  2. Go to the 'Issues' screen and create a new filter. Do not modify an existing filter.
  3. Set up your search parameters and use 'View' to check the issues returned.
  4. Once the filter is finished, go to the Filter's 'View' tab/section in the top-left area of the JIRA interface.
  5. Copy the XML link. To do this, follow the appropriate step below:

Step 2 — Embed the Issue Filter URL onto your Confluence Page

  1. Log in to your Confluence system.
  2. Edit the page where you wish to display the list of JIRA issues.

  3. Add the JIRA Issues macro to the page, as described above.

  4. Edit the macro, and paste the JIRA filter URL from your clipboard into the URL box.
  5. Customise the macro output using the optional parameters. See below.
  6. Save the Confluence page.

Parameters

The JIRA Issues macro allows the following parameters:

Parameter

Default

Description

URL

none

The URL of the XML view of your selected issues in the JIRA Issue Navigator.
Note: If the URL in the URL parameter does not contain a tempMax argument, then the value of tempMax will default to 500. For JIRA 3.12 or earlier, the JIRA Issues macro will return a maximum of 500 issues. For JIRA 3.13 or later, the JIRA Issues macro will return a maximum of 500 issues per page.

JIRA Field Columns to Display

By default, the following columns are shown:

  • type
  • key
  • summary
  • assignee
  • reporter
  • priority
  • status
  • resolution
  • created
  • updated
  • due

A list of JIRA column names, separated by semi-colons (;). Example columns are: key, summary, type, created, fixversion, updated, due, assignee, reporter, priority, status and resolution. You can include any columns recognised by your JIRA site, including custom columns. See the JIRA documentation for a list of names.

Display Total Numbers Only

false

When selected, the issue list will only show the number of issues in JIRA. The count will be linked to your JIRA site.

Cache

on

  • on – the macro maintains a cache of the issues which result from the JIRA query.
  • off – the relevant part of the cache is cleared each time the macro is reloaded.

Anonymous Retrieval

false

When selected, JIRA will return only the issues which allow unrestricted viewing i.e. the issues which are visible to anonymous viewers, as determined by JIRA's viewing restrictions. Otherwise, the results depend on how your administrator has configured the communication between JIRA and Confluence. By default, Confluence will show only the JIRA issues which the user is authorised to view. See more details below.

Width

100%

The width of the table displaying the JIRA issues. Can be indicated either as a percentage (%) or in pixels (px).

Height (pixel value only)

480

The height in pixels of the table displaying the JIRA issues.
Note that this height specification is ignored in the following situations:

  • If you set the Render Mode parameter (see below) to static.
  • When the JIRA issues are displayed in a PDF or Word document, in an email message or in an RSS feed.

Title

JIRA Issues

You can customise the title text at the top of the JIRA issues table with this parameter. For instance, setting the title to 'Bugs-to-fix' will replace the default 'JIRA Issues' text. This can help provide more context to the list of issues displayed.

Render Mode

static – when the JIRA issues are displayed in a PDF or Word document, in an email message or in an RSS feed.

dynamic – for all other formats.

  • dynamic– dynamic issue display with the following features:
    • Click the column headers to sort the output.
    • Drag and drop the columns into a different order.
    • Temporarily remove a column from the display.
    • View a page of issues at a time, for faster response times. 
  • static – disables the dynamic display features.

 

Displaying Issues which have Restricted Viewing

Maybe your JIRA instance is not visible to anonymous visitors — everyone has to log in before they can see JIRA issues. Or maybe some of the JIRA issues are restricted to viewing by certain users only. This section explains how to handle JIRA issues that have restricted viewing.

Using Confluence-to-JIRA Trusted Communication (Recommended)

For Confluence 2.7.0 and later and JIRA 3.12 and later, your administrator can set up trusted communication between Confluence and JIRA. The entire process is described in the Confluence Administrator's Guide. Provided that your administrator has set up trusted communication, you don't need to add any extra parameters. Confluence and JIRA will work out the security between them, ensuring that the user will see only the issues they are authorised to see. Read the section below if you want more detail.

 

Rendering HTML from JIRA

Formatted fields from JIRA can be displayed in Confluence if you set up a Confluence-to-JIRA Trust as described above. Otherwise, such formatted fields will be escaped within the JIRA issues macro output. This is to prevent the possibility of malicious HTML being served by an untrusted JIRA server. The most likely field where you will notice this is in the description field.

So, for example, without the trust relationship, a description column that rendered in JIRA like this -

This is

  • the description
  • of my issue

- would actually appear in the JIRA issues macro like this -

<p>This is<ul><li>the description</li><li>of my issue</li></ul></p>

Configuring Confluence-to-JIRA Trust as described above will enable the field to be rendered as expected.

Troubleshooting

HTTPS

The JIRA Issues macro can access a JIRA instance running under SSL as long as the Confluence server is set to accept the JIRA SSL certificate. Refer to the Confluence Knowledge Base article for more information about problems connecting to SSL services.

And see also Troubleshooting Trusted Communication between JIRA and Confluence