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. Using this macro, you can list publicly accessible issues from any JIRA site. Alternatively, you can allow users to see the issues that they have permission to see, based on their permissions on the JIRA site, assuming:

  • The users are logged in to both the JIRA and Confluence sites, and
  • Their usernames on both these sites match.

Note: You can also create, find and insert JIRA issues directly within text on a Confluence page or blog post. See Inserting JIRA Issues.

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.

オートコンプリートでマクロを素早く入力する方法

Type { and the beginning of the macro name, to see a list of suggested macros. Details are in Using Autocomplete.

既存のマクロを編集する方法: マクロのプレースホルダをクリックして、[編集] を選択します。マクロのパラメータが編集可能な場合、マクロのダイアログ ウィンドウが開きます。

On this 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

Screenshot: Example of JIRA issues shown on a Confluence page

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.

パラメーター

パラメータは、マクロ出力の内容や形式を制御するために設定するオプションです。

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 (Not applicable to Confluence OnDemand.)

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.

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.

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 -

説明

これは

  • 課題の
  • 説明です

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

説明

<p>これは課題の<ul><li>説明</li><li>です</li></ul></p>

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

JIRA 課題マクロの無効化

The functionality is provided by a plugin called the 'JIRA Macros Plugin'. To make the macro unavailable on your site, you can disable the plugin. See Disabling or Enabling a Plugin.

トラブルシューティング

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. Not applicable to Confluence OnDemand.

コー​​ドの例

参照先:

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