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:

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.

パラメーター

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:

パラメーター

既定

説明

URL

なし

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

既定では、次の列が表示されます。

  • 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 – 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.

幅

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.

タイトル

JIRA 課題

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:
    • 列ヘッダーをクリックして出力を並べ替えます。
    • 列をドラッグし、別の順序にドロップします。
    • ディスプレイから列を一時的に削除します。
    • 応答時間を短縮するため、一度に課題のページを表示します。 
  • 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:

必要な操作

Macro parameter

URL parameter

コメント

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.

トラブルシューティング

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:

関連トピック

Inserting JIRA Issues
JIRA Portlet Macro
Working with Macros

In the Administrator's Guide:

Take me back to the Confluence User's Guide.

Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 2.5 Australia License.