Confluence 4.1 : JIRA Issues Macro

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

Using the JIRA Issues Macro

To add the JIRA Issues macro to a page:

  1. In the Confluence editor, choose Insert > Other Macros.
  2. Find and select the required macro.

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:
    • If you are using JIRA 4.0.x or later, choose Views, right-click on XML, and choose Copy Link Location.

  • If you are using JIRA 3.13.x or earlier, locate the 'Current View' links section, right-click on XML, and choose Copy Link Location.

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

When editing, you can click on the macro placeholder and choose Edit to display the parameters for this macro in the Macro Browser.

Parameters are options that you can set for Confluence macros to control the content or format of the macro output. The table below lists parameters for this macro that can be set in the Macro Browser.

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.

Remove the username and password from your macro markup code

Prior to Confluence 2.7, you needed to include a username and password in the macro markup code if you wanted to display JIRA issues which had restricted viewing. Once your administrator has set up trusted communication between Confluence and JIRA, you no longer need to include a username and password in the markup code for your JIRA macros.

The following options are available for determining the issues which will be retrieved from JIRA and displayed on the Confluence page:

What you want to do

Macro parameter

URL parameter

Comments

Display the JIRA issues which the logged-in user is authorised to see. And if the user is not logged in, display only issues which allow unrestricted viewing.

 

 

Do not specify any authentication parameters. In this case, the behaviour depends on the way your administrator has set up trusted communication between JIRA and Confluence. Here is a summary of the behaviour. If trusted communication is enabled, the authorisation will work seamlessly. When a logged-in user views your page, they will see only the JIRA issues they are allowed to see. And if they are not logged in, they will see only the issues which allow unrestricted viewing. If trusted communication is disabled, the Confluence page will show only the JIRA issues which allow unrestricted viewing.

Ensure that Confluence will display only the JIRA issues which allow unrestricted viewing.

anonymous

 

Regardless of who the user is (logged in or not), the Confluence page will show only anonymously-visible issues. Confluence will not attempt to set up a trusted communication link with JIRA in this case.

Use a pre-determined username and password to access the JIRA issues.

 

&os_username=MYNAME&os_password=MYPASSWORD

Not recommended. Prior to Confluence 2.7, this was the only way of displaying issues with restricted viewing. For Confluence 2.7 and later, this method will still work. Confluence will not attempt to set up a trusted communication link with JIRA in this case.

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:

Related Topics

Inserting JIRA Issues
JIRA Portlet Macro
Working with Macros

In the Administrator's Guide:

Take me back to the Confluence User's Guide.