Jira 課題マクロ

JIRA is the issue tracking and project management system supplied by Atlassian. By adding the JIRA Issues macro to a Confluence page, you can display one or more issues from a JIRA site. You can also choose to create an issue in JIRA, at the time of adding the macro to the Confluence page.

このマクロを使用するには、Confluence および JIRA のサイトがアプリケーション リンク経由で接続されている必要があります。ページを表示しているユーザーは、JIRA サイトの公開されている課題を見ることができます。JIRA サイトに表示制限が設定されている場合 (したがって、ユーザーには課題を表示する権限が必要)、制限付き課題を表示する前に認証が必要です。制限付き JIRA 課題に関する詳細は、下記をご覧ください。

JIRA 課題マクロでできること

JIRA の課題マクロでできること :

• Display a table of JIRA issues on your page, based on the results of a search using JIRA Query Language (JQL).
• Jira の URL を使用して、ページ上に Jira 課題の表を表示する。
• JIRA のサイトから単一の課題を表示する、または、JIRA のサーチ結果から選択された課題のサブセットを表示する
• JIRA サイトの課題数を表示する
• Confluence にアクセスしたまま、ページで Jira に新しい課題を作成し、表示する。

JIRA 課題マクロの追加と更新 - 概要

Confluence ページ上のマクロを使用するためのクイックガイド:

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

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

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

スクリーンショット: Confluence ページでの JIRA 課題マクロの例

JIRA クエリ言語 (JQL) 検索経由で課題を表示する

また、マクロを使用し、JIRA クエリ言語 (JQL) を使用した検索結果に基づいて、ページ上に Jira 課題の表を表示することもできます。

JQL is a simple query language, similar to SQL, which works in JIRA. A basic JQL query consists of a field, followed by an operator (such as = or >), followed by one or more values or functions.

例:

• 次のクエリは、 プロジェクト内のすべての課題を検索します。

  project = "TEST"

• 次のクエリは、'CONF' プロジェクトの 'documentation' コンポーネント内のすべての課題を検索します。

  project = CONF and component = documentation

For more information about JQL syntax, see the JIRA documentation: Advanced Searching.

JQL 検索に基づいて課題のテーブルを表示するには:

1. Insert the JIRA Issues macro onto your Confluence page, as described above.
2. 検索ボタンの横にある JIRA サーバーを選択します。
3. プロンプトが表示されたら、JIRA サーバーにログインします。
4. JQL クエリを検索ボックスに入力します。
5. 検索を選択します。
6. If you want to customise the display, choose Display options and adjust the columns and number of issues that will appear in your table of issues.
7. [挿入] を選択します。

スクリーンショット JIRA 課題マクロ ブラウザーの表示オプション。

JIRA URL 経由で課題を表示する

You can paste any of the following JIRA URLs into the JIRA Issues macro. Confluence will immediately convert the URL to a JQL search.

• Any URL for a JIRA issue search or filter.
• 1 つの課題の URL。
• The URL of the XML view of a JIRA search.

Auto-convert: You can paste a JIRA URL 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 JIRA issue, or selected JIRA issues

1 つの JIRA 課題を表示するには、次の方法からいずれかを選択します。

• Confluence ページに直接課題の URL を貼り付けます。(マクロ ブラウザーを使用する必要はありません。)Confluence は JIRA 課題マクロへのリンクを自動変換します。
• Or: Add the JIRA issues macro to the page as described above, and choose Recently Viewed to see the JIRA issues you have visited recently. Select an issue and choose Insert.
• Or: Add the JIRA issues macro to the page as described above, and past 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 display a single issue in a simple format with only its description and status, or in table form.

検索結果から JIRA 課題のサブセットを表示します。

1. ページ JIRA 課題マクロを追加します。
2. Define your search criteria in the macro browser via JQL, as described above.
3. マクロ ブラウザーで、検索結果の必要な課題の隣にあるチェックボックスを選択します。

スクリーンショット: 表示する課題のサブセットを選択する

課題数を表示する

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

スクリーンショット: Confluence ページで課題数を表示する JIRA 課題マクロ

課題カウントを表示するには:

1. ページ JIRA 課題マクロを追加します。
2. Define your search criteria in the macro browser via JQL, as described above.
3. 表示オプション を選択し、マクロブラウザで [表示オプション] の横にある 合計発行数 を選択します。
4. [挿入] を選択します。

Creating a new JIRA issue in the editor

Confluence ページで編集を行いながら、Confluence エディターを開いたまま JIRA で課題を作成し、Confluence ページにその課題を表示させることができます。

To insert an issue into JIRA:

1. Add the JIRA Issues macro to the page, as described above.
2. 新しい課題作成 を選択します。
3. 要求されたら JIRA サーバー、プロジェクト、課題に関する情報を提供します。
4. [挿入] を選択します。

Confluence will send a request to JIRA, to add the issue to the JIRA site. Confluence will also display the resulting JIRA issue on the Confluence page.

制限事項

The JIRA Issues 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 customisation that is not supported by the JIRA Issues macro. In this situation you will need to create the issue directly in JIRA.

Configuring Application Links to display restricted JIRA issues

Before you can use this macro, your Confluence and JIRA sites must be connected via Application Links.

If the JIRA site allows anonymous viewing of issues, you must configure an application link, but there is no need to configure any incoming or outgoing authentication between JIRA and Confluence. People viewing the Confluence page will see the publicly accessible issues from the JIRA site.

If your JIRA site has restricted viewing, or if some JIRA projects or issues are restricted to viewing by certain people, then people will need to log in before seeing the restricted issues.

In such a case, the outgoing authentication in the Confluence Application Links determines how the JIRA Issues macro handles restricted issues:

• If the outgoing authentication is set to Trusted Applications, people can see restricted issues in JIRA if their username is the same in JIRA and Confluence, and if they have permission in JIRA to see the issue.
• If the outgoing authentication is set to OAuth, people may need to choose Login & Approve, to gain access to the JIRA server and restricted issues.
• If the outgoing authentication is set to Basic Access, people can see the JIRA issues that are visible to the user account configured in JIRA's outgoing authentication setting.

Rendering HTML from JIRA

Conflucnce から JIRA へのアプリケーション リンクを設定すると、JIRA の書式付きフィールドを Confluence に表示することができます。この操作を行わない場合、JIRA 課題マクロの出力内で、これらの書式付きフィールドはエスケープされます。これにより、信頼されない JIRA サーバーによる不正な HTML の可能性を防ぐことができます。これに気付く可能性が最も高いフィールドは、説明フィールドです。

この例では、JIRA での説明列の表示方法を示します。

JIRA と Confluence の間のアプリケーション リンクがない場合、JIRA 課題マクロには次のように説明が表示されます。

JIRA 課題マクロの無効化

The functionality is provided by an add-on (plugin) called 'JIRA Macros'. To make the macro unavailable on your site, you can disable the add-on. See Disabling and enabling apps.

注意

HTTPS: The JIRA Issues macro can access a JIRA site running under SSL provided the Confluence server is configured to accept the JIRA SSL certificate. See Connecting to LDAP or JIRA or Other Services via SSL.

Custom fields can be added as columns to the table simply by using the name of the field with no quotes. Earlier versions of the macro required you to use the custom field id, e.g. customfield_10100.

コー​​ドの例

次の例は、Confluence ページの基本的なマークアップを調べたり、編集したりする上級ユーザー向けに提供されています。 

マクロ名: jiraissues

マクロ本文: なし。

Note: A number of additional parameters that are not available via the macro browser are available in storage format and wikimarkup.

保存形式の例

Example using a URL that points to the XML view of a JIRA search:

<ac:structured-macro ac:name="jiraissues">
  <ac:parameter ac:name="anonymous">true</ac:parameter>
  <ac:parameter ac:name="columns">type;key;summary</ac:parameter>
  <ac:parameter ac:name="url">
    <ri:url ri:value="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&amp;tempMax=10"/>
  </ac:parameter>
</ac:structured-macro>

Example using JQL – note that Confluence will insert the server and serverId parameters, based on settings in Application Links:

<ac:structured-macro ac:name="jira">
  <ac:parameter ac:name="columns">key,summary,type,created,assignee,status</ac:parameter>
  <ac:parameter ac:name="server">Atlassian JIRA</ac:parameter>
  <ac:parameter ac:name="serverId">144880e9-a1111-333f-9412-ed999a9999fa</ac:parameter>
    <ac:parameter ac:name="jqlQuery">project = CONF AND component = documentation AND resolution = unresolved</ac:parameter>
  </ac:structured-macro>

Wiki マークアップ例

{jiraissues:anonymous=true|url=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|columns=type;key;summary|title=My List of Issues}