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

このページの内容

お困りですか?

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

コミュニティに質問

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

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

概要

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

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



はじめる前に

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

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

  • 制限: メールへの課題フィールドの追加は、一括通知ではサポートされていません。カスタム フィールドのみ追加できます。課題フィールドを表示したい場合、これらのフィールドがサポートされる個別の通知に切り替える必要があります。一括通知に課題フィールドを追加する機能リクエストがあり、こちらで投票できます。

ステップ 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. Go to <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 月 30 日

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

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