カスタム フイールドをメール (バッチ処理された通知) に追加する

このページの内容

お困りですか?

アトラシアン コミュニティをご利用ください。

コミュニティに質問

このチュートリアルでは、一括メール通知にカスタム フィールドを追加する方法について説明します。通常のメールにカスタム フィールドを追加する場合、「通常のメール通知へのカスタム フィールドの追加」を参照してください。

このチュートリアルは、高度なユーザー向けの内容を含み、アトラシアン サポートの対象外です。メール通知が基づく、Velocity テンプレートのコードを編集することで、カスタム フィールドを追加できます。

概要

通知は、課題のフィールド (標準のフィールドとカスタム フィールドの両方) についての変更を示します。フィールドの値が変更されなかった場合、通知する情報がないため、そのフィールドは通知に含まれません。通知は変更を伝えることにのみ焦点を当てています。

ここでは、このフィールドが更新されなかった場合も、課題に関する各通知にカスタム フィールドとその値を含める方法を紹介します。これを使用すると、通知される課題についてより正確に説明できます。たとえば、課題のセキュリティ レベルを指定するカスタム フィールドを含めることで、それらを適切に分類したり、その課題に関する通知を非表示にしたりすることができます。 



はじめる前に

  • メール通知のバッチ処理を有効化します。これは、 > [システム] > [メール通知のバッチ処理] で行えます。

  • 課題にカスタム フィールドを追加します。

  • Limitation: Adding extra issue fields to your emails is not supported for batched notifications. You can only add custom fields. If you want to have issue fields displayed, you’ll need to switch to separate notifications, where these fields are supported. There's a feature request for adding issue fields to batched notifications, you can vote for it here.

ステップ 1: カスタム フィールドの ID を探す

ID を使用してメール テンプレートにカスタム フィールドを追加します。カスタム フィールドの URL を調べるか、データベースにクエリを送信することで ID を検索できます。

カスタム フィールドの URL を調べる

  1. > [課題] に移動し、[カスタム フィールド] ページを開きます。

  2. カスタム フィールドを見つけ、 をクリックしてオプションを表示します。

A. ドロップダウン メニューで [設定] アイテムにマウスを合わせます。URL がブラウザのフッターに表示されます。

B. これがカスタム フィールドの ID です。この例では、10108 です。

データベースへのクエリ送信

データベースで以下のクエリを実行します。

SELECT * FROM customfield WHERE cfname LIKE '%mycustomfield%';

mycustomfield がカスタム フィールドの名前です (例: assignee)。 

ステップ 2: Velocity コンテキストへのカスタム フィールドの追加

メールにカスタム フィールドを追加する前に、それを Velocity コンテキストで定義する必要があります。これらの手順には、REST API に関する知識が必要な場合があります。問題が発生した場合は、「Jira REST API」を参照してください。

1. 現在定義されているカスタム フィールドを取得

以下のコマンドを使用できます。

curl -D- \
    -u username:password \
    http://@localhost:8080/rest/inform-batchers/1.0/customfields

カスタム フィールドを追加していない場合、以下の例のように、リストが空になるはずです。

    {
        "customFieldIds": []
    }

2. カスタム フィールドを追加

Velocity コンテキストにカスタム フィールドを追加するには、以下のコマンドを使用できます。<ID> はカスタム フィールドの ID に置き換えます。

    curl \
       -D- \
       -u username:password \
       -X POST \
       -H "Content-Type: application/json" \
       http://localhost:8080/rest/inform-batchers/1.0/customfields?id=customfield_<ID>

このコマンドの結果は以下のようになるはずです。

    {
        "customFieldIds": ["customfield_10108"]
    }

カスタム フィールドの削除

このコマンドを使用することで、Velocity コンテキストから任意のカスタム フィールドを削除できます。 

curl \
       -D- \
       -u username:password \
       -X DELETE \
       -H "Content-Type: application/json" \
       http://localhost:8080/rest/inform-batchers/1.0/customfields?id=customfield_<ID>

ステップ 3: Velocity テンプレートの取得

一括メール通知に使用される Velocity テンプレートは、Jira inform-batchers アプリにあります。これらを抽出する必要があります。

1. アプリ バージョンを調べる

Jira インストール ディレクトリに、このアプリの複数のバージョンがある場合があります。現在のバージョンを確認して、後で編集するファイルを確認します。

  1.  > [アプリの管理] に移動し、[アプリの管理] ページを開きます。

  2. ドロップダウンから、[すべてのアプリ] を選択し、「Jira inform - batchers」を検索します。

  3. アプリを展開し、バージョンを確認します (以下の例では 1.1.3 です)。 

2. Jira インストール ディレクトリからアプリをコピー

アプリを別のディレクトリにコピーします。Jira インストール ディレクトリ内の .jar ファイルは編集しないでください。変更を元に戻す必要がある場合に備えて、元の JAR ファイルを保持することもおすすめします。

  1. <jira-installation-directory>/atlassian-jira/WEB-INF/atlassian-bundled-plugins/ に移動します。

  2. batchers-<version>.jar ファイルを見つけます。

  3. ファイルを別のディレクトリにコピーします。

3. アプリの JAR ファイルからテンプレート ファイルを抽出

テンプレートを抽出する最も簡単な方法は、以下のコマンドを使用することです。このコマンドを動作させるには JDK がインストールされている必要があることにご注意ください。 

jar xf batchers-1.1.3.jar templates/email

ステップ 4: Veloctity テンプレートの編集

Velocity テンプレートを抽出したら、それらを直接編集し、カスタム フィールドを表示する任意のコード スニペットを追加できます。

1. 更新するテンプレートを選択

一括メール通知ではいくつかのテンプレートが使用されます。必要となる最も重要なテンプレートは次のとおりです。

テンプレート ファイル説明

IssueUpdateBatcher-subject.vm

課題更新時のメール件名。

IssueUpdateBatcher-header.vm

メール ヘッダー。これには、メールで表示される最初の区切り文字より手前のすべての情報 (プロジェクト名、課題名、課題キー、および更新を要約した導入テキスト) が含まれます。

このファイルは、メンションにも使用されます。

IssueUpdateBatcher-content.vm (HTML 形式の場合)

IssueUpdateBatcher.vm (テキスト形式の場合)

作成された課題、課題の更新、およびコメントの詳細などのすべての変更の一覧を含む、メールの主要部分。

このファイルは、メンションにも使用されます。

MentionIssueUpdateBatcher-subject.vm

メンションのメールの件名。

footer.vm

メールのフッター。


2. テンプレートの編集

Jira は html 形式とテキスト形式のメールをサポートしています。Jira で設定された形式に従って手順を選択する必要があります。

テキスト形式...
  1. 変更するメール タイプの Velocity テンプレートを見つけます。すべてのテンプレートは次のディレクトリにあります。

    /templates/email/batch/text/
  2. 以下のスニペットを、ファイル内の表示したい位置に追加します。

    #if($customFields.get('customfield_<ID>').getValue())
    ${customFields.get('customfield_<ID>').getName()}: ${customFields.get('customfield_<ID>').getValue()}
    #end
HTML 形式...
  1. 変更するメール タイプの Velocity テンプレートを見つけます。すべてのテンプレートは次のディレクトリにあります。

    /templates/email/batch/html/
  2. 以下のスニペットを、ファイル内の表示したい位置に追加します。

    #if(${customFields.get('customfield_<ID>').getValue()})
    <tr>
        <td>$escape.apply($customFields.get('customfield_<ID>').getName()):</td>
        <td>      
            $escape.apply($customFields.get('customfield_<ID>').getValue())
        </td>
    </tr>
    #end

このコード スニペットの編集に関するいくつかのヒント:

  • これはカスタム フィールドの ID を入力する場所です。

    ${customFields.get('customfield_<ID>').getValue()

任意で、この行を以下の 2 行のいずれかに置き換えることができます。

  • このコードを使用すると、カスタム フィールドの最新の値を取得できます。これは、カスタム フィールドが削除されたときに役立ちます。その場合、値は null として返されます。元の行では、削除前の最後の値が取得されます。

    ${customFieldsCurrent.get('customfield_<ID>').getValue()}
  • このコードを使用すると、カスタム フィールドの名前を取得できます。

    ${customFiels.get('customfield_<ID>').getName()}

ステップ 4: Jira への更新されたテンプレートのアップロード

変更のテスト

本番環境に適用する前に、ステージング環境で変更をテストすることをおすすめします。Velocity 構文に違反した場合、メールは一切送信されません。

  1. JAR ファイルにテンプレートを戻します。 

    jar uf batchers-1.1.3.jar templates/email
  2. アプリを Jira にアップロードします。

    1. > [アプリの管理] > [アプリの管理] に進みます。

    2. [アプリのアップロード] をクリックし、JAR ファイルをアップロードします。アプリが再インストールされると、変更が表示されます。Jira を再起動する必要はありません。

トラブルシューティング

テンプレートの編集時に発生する一般的な問題です。

変更を元に戻す場合...

Jira インストール ディレクトリには、Jira inform - batchers アプリの元のバージョンが含まれます。変更を元に戻すには、アプリの JAR ファイルを見つけ、 > [アプリの管理] > [アプリの管理] に移動して、手動でアップロードします。

アプリの JAR ファイルは <jira-installation-directory>/atlassian-jira/WEB-INF/atlassian-bundled-plugins/ にあります。

変更がメールに表示されない...

この問題は、Jira インスタンスが使用している Jira inform - batchers アプリと異なるバージョンのテンプレートを編集する場合に多く発生します。適切なバージョンの取得方法については、「ステップ 3: Velocity テンプレートの取得」を参照してください。

Jira のアップグレード後に変更が反映されない...

Jira inform - batchers アプリおよびそれに含まれるテンプレートは、Jira インスタンスをアップグレードするたびに上書きされます。つまり、アップグレード後に変更を再適用する必要があります。テンプレートのコピーを保管すると、より迅速に変更を再適用することができます。

最終更新日 2020 年 1 月 9 日

この内容はお役に立ちましたか?

はい
いいえ
この記事についてのフィードバックを送信する
Powered by Confluence and Scroll Viewport.