Adding custom fields to emails (batched notifications)

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

This tutorial will help you add a custom field to batched email notifications. If you’re looking to add custom fields to regular emails, see Adding custom fields to regular email notifications instead.

This tutorial is for advanced users, and is out of scope of Atlassian support. You will be adding custom fields by editing the code in the Velocity templates, which email notifications are based on.

Overview

Notifications inform you about changes in the issue's fields (both built-in and custom fields). If a field's value did not change, it won't be included in the notification, because there's nothing to be notified about. After all, notifications are all about showing a change.

Here you can learn how to include a custom field, and its current value, in every notification for an issue, even if this field wasn't updated. You can use it to describe the issues you're being notified about more precisely. For example, you can include a custom field that specifies the issue's security level, and then properly categorize or even hide the notifications for this issue. 



Before you begin

  • Enable batched email notifications. You can do it in   > System > Batching email notifications.

  • Add your custom field to an issue.

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

Step 1: Find the ID of your custom field

You will add custom fields to your email templates by using their IDs. You can find the ID by examining the URLs of custom fields or by querying the database.

Examining the URL of a custom field

  1. Go to  > Issues, and open the Custom fields page.

  2. Find your custom field, and click  to see more options.

A. Hover your mouse over the Configure item in the drop-down menu. The URL will display in the footer of your browser.

B. Here’s the custom field’s ID. In this example, it’s 10108.

Querying the database

Run the following query on your database:

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

Where mycustomfield is the name of your custom field, for example assignee

Step 2: Add the custom field to the Velocity context

Before you can add custom fields to the email templates, you need to define them in the Velocity context. These steps might require some knowledge about REST API. If you’re having problems, see Jira REST API.

1. Retrieve currently defined custom fields.

You can use this command:

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

If you haven’t added any custom fields yet, the list should be empty, like in the following example:

    {
        "customFieldIds": []
    }

2. Add your custom field.

To add your custom field to the Velocity context, you can use the following command. Replace <ID> with the ID of your custom field.

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

The result of this command should look similar to this:

    {
        "customFieldIds": ["customfield_10108"]
    }

Removing a custom field

You can remove any of the custom fields from the Velocity context by using this command: 

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

Step 3: Retrieve the Velocity templates

The Velocity templates used for batched email notifications are in the Jira inform - batchers app. You’ll need to extract them.

1. Find out the app version.

Your Jira installation directory might have more versions of this app. Check your current version to know which file to edit later.

  1. Go to  > Manage apps, and open the Manage apps page.

  2. From the drop-down, select All apps, and search for Jira inform - batchers.

  3. Expand the app, and check your version (in the example below, it’s 1.1.3). 

2. Copy the app from the Jira installation directory.

Copy the app to a separate directory. You should never edit the .jar files inside the Jira installation directory. It’s also good to keep the original JAR file in case you needed to revert the changes.

  1. Go to <jira-installation-directory>/atlassian-jira/WEB-INF/atlassian-bundled-plugins/.

  2. Find the batchers-<version>.jar file.

  3. Copy the file to a separate directory.

3. Extract the template files from the app’s JAR file.

The easiest way to extract the templates is to use the following command. Note that you’ll need JDK installed for it to work. 

jar xf batchers-1.1.3.jar templates/email

Step 4: Edit the Velocity templates

Once you’ve extracted the Velocity templates, you can edit them directly to add code snippets that will display your custom fields.

1. Choose a template to update.

Batched email notifications are using several templates. Here are the most important ones that you’ll need.

Template fileDescription

IssueUpdateBatcher-subject.vm

Email subject for issue updates.

IssueUpdateBatcher-header.vm

Email header. This includes everything above the first separator visible in the email, that is project name, issue name, issue key, and introduction text summarizing the updates.

This file is also used for mentions.

IssueUpdateBatcher-content.vm (for HTML format)

IssueUpdateBatcher.vm (for text format)

Main part of the email, containing the list of all changes, like details about the created issue, issue updates, and comments.

This file is also used for mentions.

MentionIssueUpdateBatcher-subject.vm

Email subject for mentions.

footer.vm

Email footer.


2. Edit the 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. All templates are in this directory:

    /templates/email/batch/text/
  2. Add the following snippet where you want it to appear in the file:

    #if($customFields.get('customfield_<ID>').getValue())
    ${customFields.get('customfield_<ID>').getName()}: ${customFields.get('customfield_<ID>').getValue()}
    #end
HTML format...
  1. Find the Velocity template of the email type you wish to modify. All templates are in this directory:

    /templates/email/batch/html/
  2. Add the following snippet where you want it to appear in the file:

    #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

Some tips for editing this code snippet:

  • This is where you enter the ID of your custom field.

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

Optionally, you can replace this line with one of the two below:

  • Use this code to retrieve the most up-to-date value of your custom field. This is useful when a custom field gets deleted, in which case the value is returned as null. In the original line, you’d get the last value before the deletion.

    ${customFieldsCurrent.get('customfield_<ID>').getValue()}
  • Use this code to retrieve the name of your custom field.

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

Step 4: Upload the updated templates to Jira

Testing your changes

We recommend that you test your changes in a staging environment before applying them in production. If you break the Velocity syntax, emails won’t be sent at all.

  1. Insert the templates back into the JAR file. 

    jar uf batchers-1.1.3.jar templates/email
  2. Upload the app to Jira.

    1. Go to  > Manage apps > Manage apps.

    2. Click Upload app, and upload the JAR file. The changes will be visible once the app is reinstalled, and you don’t have to restart your Jira instance.

Troubleshooting

Here are some common issues we’ve encountered when editing the templates.

Reverting the changes...

Your Jira installation directory contains the original version of the Jira inform - batchers app. To revert the changes, find the app’s JAR file and upload it manually to Jira by going to > Manage apps > Manage apps.

You can find the app’s JAR file in <jira-installation-directory>/atlassian-jira/WEB-INF/atlassian-bundled-plugins/.

Changes are not visible in emails...

This problem often occurs when you edit the templates from a different Jira inform - batchers app version than the one your Jira instance is using. See Step 3: Retrieving the Velocity templates for more information on how to get the version right.

Changes disappeared after upgrading Jira...

The Jira inform - batchers app, and the templates inside it, will get overwritten after every upgrade of your Jira instance. This means that you have to reapply the changes after an upgrade. It’s good to keep the copy of the templates somewhere, so you can reapply the changes more quickly.

Last modified on Jan 9, 2020

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.