Jira 課題マクロ
スクリーンショット: リリース前に解決しなければならない課題を表示する Jira 課題マクロが含まれる、プロジェクトのステータス ページ。
Confluence と Jira を接続する
このマクロを使用するには、Confluence と Jira アプリケーションがアプリケーション リンクを介して接続されている必要があります。ページを表示しているユーザーは、Jira サイトで公開されているアクセス可能な課題を見ることができます。Jira サイトに表示制限が設定されている場合 (ユーザーに課題の表示権限が必要な場合)、制限付き課題を表示する前に認証が必要となります。
詳細については、「Jira アプリケーションと Confluence を一緒に使用する」を参照してください。
このマクロをページに追加する
Jira マクロをページに追加するには、次の手順を実行します。
- エディターのツールバーから、[挿入]
> [その他のマクロ] の順に選択します。 - [開発] カテゴリから [Jira] を選択します。
- フィルターを入力するか、Jira 課題を検索します。
- [挿入] をクリックします。
その後、ページを公開するとマクロの動作を確認できます。
スクリーンショット: 課題の一覧を表示するための Jira 課題マクロの設定。
JIRA クエリ言語 (JQL) 検索経由で課題を表示する
また、マクロを使用し、JIRA Query Language (JQL) を使用した検索結果に基づいて、ページ上で課題の表を表示することもできます。
JQL は、SQL に似たシンプルなクエリ言語です。基本的な JQL のクエリは、フィールド、演算子 (= や > など)、1 つ以上の 値 または関数 で構成されています。
例:
次のクエリは、 プロジェクト内のすべての課題を検索します。
project = "TEST"次のクエリは、'CONF' プロジェクトの 'documentation' コンポーネント内のすべての課題を検索します。
project = CONF and component = documentation
JQL 構文の詳細については、JIRA Software ドキュメントの「詳細検索」を参照してください。
JQL 検索に基づいて課題のテーブルを表示するには:
- 上記のように、Confluence ページに JIRA 課題マクロを挿入します。
- 検索ボタンの横にある JIRA サーバーを選択します。
- プロンプトが表示されたら、JIRA サーバーにログインします。
- JQL クエリを検索ボックスに入力します。
- 検索を選択します。
- ディスプレイをカスタマイズする場合は、表示オプションを選択し、課題の表に表示される列と課題数を調節します。
- [挿入] を選択します。
スクリーンショット JIRA 課題マクロ ブラウザーの表示オプション。
JIRA URL 経由で課題を表示する
次の JIRA アプリケーション URL を JIRA 課題マクロに貼り付けることができます。Confluence は URL を直ちに JQL 検索へと変換します。
- 課題検索またはフィルターの URL。
- 1 つの課題の URL。
- 検索の XML ビューの URL。
自動変換: URL を直接 Confluence エディターに貼り付けることができます (マクロ ブラウザーを呼び出さずに)。Confluence は URL を JIRA 課題マクロに自動変換します。
1 つの課題、または選択した課題を表示する
1 つの Jira 課題を表示するには、次の方法からいずれかを選択します。
- Confluence ページに直接課題の URL を貼り付けます。(マクロ ブラウザーを使用する必要はありません。)Confluence は JIRA 課題マクロへのリンクを自動変換します。
- または: 上記のように JIRA 課題マクロをページに追加し、最近の表示履歴 を選択して最近訪問した課題を表示します。課題を選択し、 挿入を選択します。
- または: 上記のように JIRA 課題マクロをページに追加し、マクロ ブラウザーの検索ボックスに課題 URL を貼り付けます。
- または: JIRA 課題をページﾞに追加、上記のように JQL 経由でマクロ ブラウザで検索条件を定義、またはマクロ ブラウザ内の検索結果で、課題の横にあるチェックボックスを選択します。
課題キーのみや、課題キーとサマリーを表示するよう選択できます。マクロ プレースホルダーをクリックして、「概要を表示」または「概要を非表示」を選択します。
検索結果から JIRA 課題のサブセットを表示します。
- ページ JIRA 課題マクロを追加します。
- JQL 経由でマクロ ブラウザーの検索条件を定義します (上記のとおり)。
- マクロ ブラウザーで、検索結果の必要な課題の隣にあるチェックボックスを選択します。
スクリーンショット: 表示する課題のサブセットを選択する
課題数を表示する
課題の表ではなく、検索で返される課題の数を表示するよう選択できます。JIRA 課題マクロは、JIRA アプリケーションの検索にリンク付けされた課題の数を表示します。
スクリーンショット: 課題数を表示する Jira 課題マクロ。
課題カウントを表示するには:
- JIRA 課題マクロをページに追加します。
- JQL 経由でマクロ ブラウザーの検索条件を定義します (上記のとおり)。
- 表示オプション を選択し、マクロブラウザで [表示オプション] の横にある 合計発行数 を選択します。
- [挿入] を選択します。
新しい課題を作成する
Confluence ページで編集を行いながら、Confluence エディターを開いたまま JIRA で課題を作成し、Confluence ページにその課題を表示させることができます。
課題を作成してページに追加するには:
- 上記のように、ページに JIRA 課題マクロを挿入します。
- 新しい課題作成 を選択します。
- 要求されたら JIRA サーバー、プロジェクト、課題に関する情報を提供します。
- [挿入] を選択します。
Confluence は課題を作成するよう JIRA アプリケーションにリクエストを送信した後、ページで新しく作成した課題を表示します。
制限事項
JIRA 課題マクロは選択されたプロジェクトで課題を作成できない場合、通知します。これは、プロジェクトに JIRA 課題マクロでサポートされていないフィールド、フィールド設定およびその他のカスタマイズがあることが原因の可能性があります。この状況では、JIRA アプリケーションで直接課題を作成する必要があります。
制限付き課題を表示するアプリケーションリンクの設定
このマクロを使用するには、Confluence と Jira のサイトがアプリケーション リンクを介して接続されている必要があります。
Jira が匿名ユーザーに対して課題の閲覧を許可している場合、アプリケーション リンクを設定する必要がありますが、Jira アプリケーションと Confluence の間で外向きおよび内向きの認証を設定する必要はありません。Confluence ページを表示しているユーザーは、公開されている課題を見ることができます。
Jira サイトに表示制限が設定されている場合や、一部のプロジェクトまたは課題で表示を特定の人物に制限している場合、ユーザーは制限付き課題を表示する前にログインと承認を行うよう求められます。
JIRA アプリケーションからの HTML レンダリング
Conflucnce から JIRA へのアプリケーション リンクを設定すると、JIRA の書式付きフィールドを Confluence に表示することができます。この操作を行わない場合、JIRA 課題マクロの出力内で、これらの書式付きフィールドはエスケープされます。これにより、信頼されない JIRA サーバーによる不正な HTML の可能性を防ぐことができます。これに気付く可能性が最も高いフィールドは、説明フィールドです。
この例では、JIRA での説明列の表示方法を示します。
説明
これは
- 課題の
- 説明です
JIRA と Confluence の間のアプリケーション リンクがない場合、JIRA 課題マクロには次のように説明が表示されます。
説明
<p>これは課題の<ul><li>説明</li><li>です</li></ul></p>
JIRA 課題マクロの無効化
"Jira Macros" と呼ばれるシステム アプリ (プラグイン) により提供される機能です。ご使用のサイトでマクロを使用できないようにするために、アプリを無効にすることもできます。「アプリの無効化と有効化」を参照してください。
注意
HTTPS: Confluence サーバーが Jira SSL 証明書を受け入れるように設定されている場合、Jira 課題マクロは SSL で実行中の Jira アプリケーションにアクセスできます。「SSL 経由で LDAP、 Jira アプリケーション、または他のサービスに接続する」を参照してください。
フィールドの名前を引用符で囲まずに使用すると、カスタム フィールドをテーブルの列として簡単に追加できます。以前のバージョンのマクロでは、カスタム フィールド ID (例: customfield_10100.) を使用する必要がありました。
このマクロを追加するその他の方法
手入力でこのマクロを追加する
Wiki マークアップを使用してこのマクロを追加する
これは、エディタ外部 (スペースのサイドバー、ヘッダー、フッターのカスタム コンテンツなど) でマクロを追加する場合に便利です。
マクロ名: jiraissues
マクロ本文: なし。
この例では、Jira フィルターを使用します。
{jiraissues:anonymous=true|url=https://jira.atlassian.com/issues/?filter=41225}マクロ ブラウザー経由で使用できない多数の付加パラメーターは、ストレージ形式や Wiki マークアップで利用可能です。
Confluence と Jira を使いこなす
Atlassian Marketplace の次のアプリを使用することで、Jira 課題のさらに高度な表示を実現できます。
- Issue Macro from Jira to Confluence: 1 つの Jira 課題レポートの外観をカスタマイズしたり、優れた形式のフィルター レポートを生成
- Issues Forms for Confluence: Confluence ページで Jira 課題 / チケットを作成および表示