Email templates

Jira Data Center 8.14 includes a new page in the Jira administration where you can download a ZIP archive with all available Jira mail templates and upload it back after making your changes locally. Modifying email templates lets you change the look and feel of emails and notifications sent to your users, so it can come in handy when you need to customize these to your organization’s needs.

Accessing email templates

To open the email templates page:

1. Go to Administration > System.
2. Open Email templates.

Downloading templates

You can download available templates as a ZIP archive. You will then need to extract the archive and make your edits locally.

Uploading templates

After making changes to the templates, you need to archive them into the same ZIP archive and upload it back to Jira.

Required ZIP structure

When editing the templates, you shouldn’t change their filenames or location within the folder, as Jira will validate the file structure. You can, of course, add additional files, like graphics, and link them from your templates.

The following file structures will be accepted:

• Email folders in the templates folder (default): 

  - templates
  	- email
  	- email-batch

• Email folders directory in the ZIP archive: 

  - email
  - email-batch

Applying the changes

After uploading the templates, they won’t be applied right away. Jira will first validate the file structure, and then ask you to apply the changes if everything looks right.

Templates: Default vs. current

Current templates

Current templates are templates that Jira using for email notifications. They are stored in your Jira shared home directory and are updated every time you upload a new ZIP archive and apply the changes.

• Separate notifications: <Jira-shared-home>/data/templates/email
• Batched notifications: <Jira-shared-home/data/templates/email-batch

Default templates

Default templates are backup templates that are stored in the Jira resources, either in the installation directory (separate notifications) or in one of the plugins (batched notifications). It's what you would edit to customize your emails before Jira 8.14. These templates work as backups and will only be used in these cases:

• Missing files: One of the templates is missing in your Jira shared home directory. For this template, Jira will fall back to the default one.
• Revert to default: You chose to revert your templates to default. Default templates will be copied to your shared home directory, overwriting the current templates.
  
  

Reverting templates to default

If something isn't right with your modified templates, you can bring the default ones by clicking Revert to default. Here's what happens when you do it:

1. Jira copies the default templates from its resources to the Jira shared home directory.
2. The default templates overwrite any existing templates in <Jira-shared-home>/data/templates.
3. After a successful revert, we clear the template cache, so the default templates are applied right away.

Caching email templates

All templates in the Jira shared home directory are cached. Thanks to that, Jira can use these templates even if the Jira shared home isn't accessible. We don't cache information about missing files—if one of the templates is missing from the Jira shared, Jira will try to read it every time and will always fall back to the default template.

Copying templates on upgrade

When you start Jira 8.14 for the first time, the default templates will be automatically copied to your Jira shared home directory. This will happen only once, when you run the version that supports this feature. Later on, your edited templates will stay in the Jira shared home directory, so you won’t have to repeat your customizations with every upgrade.

In the future, you will need to copy any new additions from the default templates to your current ones. Changes like that don't happen too often and we'll let you know about them in the upgrade notes.