Adding custom fields to emails (batched notifications)

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.

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.

2. Edit the template.

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

Step 4: Upload the updated templates to Jira

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.