Last updatedJun 1, 2018

Adding custom fields to email

This tutorial shows you how to print a custom field in an email. Note that there is an open feature request to integrate this into Jira, which is tracked here: JRA-4619.

Note that this tutorial will help you add a custom field to separate email notifications. If you’re looking to add custom fields to batched notifications, see Adding custom fields to batched email notifications instead.

Step 1. Find the Custom Field ID

You can find the Custom Field ID by examining the URLs of custom field pages or by querying the database.

Examining the URL of a custom field page

  1. Go to the Custom Field configuration in the Jira administration console, as described on Configuring a Custom Field page.
  2. To open the menu for the Custom Field, click cog icon.
  3. Hover your mouse over the Configure item in the menu. The URL will display in the footer of your browser. The URL will show the Custom Field ID.

For example, in this screenshot, the ID of the custom field is 10000.

Querying the database

Run the following query on your database:

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

Where mycustomfield is your custom field name.

Step 2. Edit the Velocity template

Jira supports html and text email formats. You should choose instructions according to format set in your Jira.

If using the EAR/WAR version, make changes in the edit-webapp directory, then rebuild and re-deploy the WAR file.

Text format

  1. Find the Velocity template of the email type you wish to modify. For instance, you may want to modify the issue created template, as well as the template reused in issue commented. They are located here:

    1
    2
    3
    4
    ``` bash
    atlassian-jira/WEB-INF/classes/templates/email/text/issuecreated.vm  
    atlassian-jira/WEB-INF/classes/templates/email/text/includes/issuesummary.vm
    ```
  2. Add the following snippet where you want it to appear in the file:

    1
    2
    3
    4
    #set ($customfield = $customFieldManager.getCustomFieldObject("customfield_10000"))
    #if ($issue.getCustomFieldValue($customfield))
    $stringUtils.leftPad($customfield.name, $padSize): $issue.getCustomFieldValue($customfield)
    #end

    You can find the javadoc for $stringUtils.leftPad here: StringUtils.

  3. Navigate to atlassian-jira/WEB-INF/classes/templates/email/text/includes/, add the following to the issuesummary.vm file:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    ``` java
    #set ($customfield = $customFieldManager.getCustomFieldObject("customfield_10000"))
    #if ($issue.getCustomFieldValue($customfield))
    >$stringUtils.leftPad($customfield.name, $padSize): $issue.getCustomFieldValue($customfield)
    #end
    ```
    
    Note that *you need to change the custom field ID* to the ID you found in step 1.
    In the example, the ID is 10000, yours will probably be different.
  4. If you wish to iterate over all related custom fields, you can use the following example:

    1
    2
    3
    #foreach ($value in $customFieldManager.getCustomFieldObjects($issue))
    >$stringUtils.leftPad($value.getName(), $padSize): $!value.getValueFromIssue($issue)
    #end

Html format

  1. Find the Velocity template of the email type you wish to modify. For instance, you may want to modify the issue created template that is located here:

    1
    2
    3
    ``` bash
    atlassian-jira/WEB-INF/classes/templates/email/html/issuecreated.vm  
    ```
  2. Add the following snippet where you want it to appear in the file:

    1
    #parse("templates/email/html/includes/fields/customfield.vm")
  3. Navigate to atlassian-jira/WEB-INF/classes/templates/email/html/includes/fields/ and create a new Velocity file customfield.vm.

  4. Add the following code to the file:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    #disable_html_escaping()
    #set ($customfield = $customFieldManager.getCustomFieldObject("customfield_10000"))
    #if($issue.getCustomFieldValue($customfield))
    <tr>
        <th>#text($customfield.name):</th>
        <td class="has-icon">      
            $textutils.htmlEncode($issue.getCustomFieldValue($customfield), false)
        </td>
    </tr>
    #end

Note that you need to change the custom field ID to the ID you found in step 1. In the example, the ID is 10000, yours will probably be different.

Step 3. Restart Jira

  1. To make the changes take effect, restart Jira.

    If you wish to avoid the continual restarts during testing, navigate to atlassian-jira/WEB-INF/classes/, open the velocity.properties file and edit the following section as the comment says:

1
2
3
# To enable autoreloading, set cache to false and uncomment the autoreload line
class.resource.loader.cache=true
#velocimacro.library.autoreload=true