Documentation for JIRA 5.2. Documentation for other versions of JIRA is available too.

JIRA generates emails in reaction to events using a templating engine. The templating engine is Apache's Velocity. This is a relatively easy to use templating language that can pull apart java objects in useful ways. The mails are generated inside JIRA by invoking Velocity with a set of objects of relevance to the event.

(info) 注意:

  • To change the columns in your filter subscriptions, you don't need to customise the mail templates. See Customising your Issue Navigator.
  • There's a feature request to improve this at JRA-7266, which you can vote on to improve its chances of being implemented.
  • Bear in mind that the next time you upgrade JIRA – or need a new installation for any reason – you will have to manually copy any changes you have made to Velocity templates (as well as JSPs) into the new installation of JIRA. If the Velocity templates and/or JSPs have changed in the newer version, you will have to manually port your customisations into them (as opposed to copying these files directly over from your old JIRA installation to your upgraded one).

Customisations to Velocity templates or other JIRA files are not included in the scope of Atlassian Support.

メール テンプレートの場所

To customise email content, please follow this procedure.

  1. JIRA ディストリビューションを開き、次のパスに移動します。
    • The WEB-INF/classes/templates/email/ of the <jira-application-dir> in your JIRA Installation Directory.
    • The jira/src/etc/java/templates/email/ in your extracted JIRA source directory.
  2. このディレクトリには、html、text、および subject の 3 つのディレクトリがあります。html サブディレクトリには html 形式でメールを作成するために使用するテンプレートが含まれ、text ディレクトリにはプレーン テキスト メール出力が含まれます。subject ディレクトリにはメールの件名を生成するために使用されるテンプレートが含まれます。テンプレートには、メールをトリガーするイベントに関連する名前が設定されます。
  3. Bring the template up in your favourite text editor. Referring to the JIRA template documentation (particularly Velocity Context for Email Templates) and Velocity Users Guide, make the customisations you want.
  4. Jira を再起動します。

新しい電子メールテンプレートの場合:

  1. html、text、および subject ディレクトリで、それらのディレクトリ内の既存のファイルに基づき、新しく mytemplate.vm ファイルを作成します。
  2. テンプレートを atlassian-jira/WEB-INF/classes/email-template-id-mappings.xml に追加して、新しいイベントを追加する際に選択できるようにします。

Note that since JIRA 4.1 each new template has to have a corresponding file in the subject directory.

Advanced customisation

The Issue object is passed into the vm templates. Notice some of its implementation in /includes/summary-topleft.vm. As an example, calling $issue.getProject() would allow you to determine the project an issue comes from, and even create logic to show different information for emails from different projects.

JIRA を再起動せずに Velocity テンプレートを展開する

In a development instance, you can play with picking up velocity file changes without a restart.
From <jira-install>/atlassian-jira/WEB-INF/classes/velocity.properties:

  1. class.resource.loader.cache を true から false に変更します。
  2. #velocimacro.library.autoreload=true からコメント記号 (#) を削除します。

Making this change in production will eventually lead to JIRA not serving pages along with the ran out of parsers error in the log file.

See also Adding Custom Fields to Email.

1 Comment

  1. user-7606f

    May 06, 2013

    I've followed this step-by-step (and restarted 2x) and the new Template does not show up in my dropdown of available templates.  Is there a naming convention?  What is the <templatetype> field in the email-template-id-mappings.xml looking for?  Does the <templatemapping id> need to be registered somewhere or can I just take the next one in the sequence?

     

       <templatemapping id="17">

            <name>Outage Notification</name>

            <template>outagenotification.vm</template>  <–---in subject, html and text folders

            <templatetype>outagenotification</templatetype> <—is this right if all my .vm's are named accordingly?

        </templatemapping>

     

     



See our Getting Help page for details.



Raise an issue for our developers.



See answers from the community.



Tweet, blog and update our documentation.

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