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.

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 .
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
2
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.

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
   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
   #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
   #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
   #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
   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
   2
   #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
   #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
   # To enable autoreloading, set cache to false and uncomment the autoreload line
   class.resource.loader.cache=true
   #velocimacro.library.autoreload=true