Modifying notification templates
If you want to customize the layout and content of your Bamboo notifications, you can customize the templates for each of the notification types (i.e. HTML email, text email, instant message) and events (e.g. Build Commented). The notification templates are written in Freemarker.
Some content in notifications can also be configured via system properties, such as the number of log lines to include in email notifications that display log information.
Changes to notification templates only take effect after a Bamboo restart.
On this page:
Related pages:
Modifying a notification template
To modify a notification template:
- Locate the default notification templates in
WEB-INF/classes/notification-templates/ - Copy the notification template that you wish to modify into the
templates/notification-templatesfolder of your Bamboo home directory, e.g.HOME/templates/notification-templates
The filename will have formatted as: <event name><notification type>.ftl, e.g.AfterXFailedHTMLEmail.ftl - Modify the copied template, as desired. Please see the section on Working with Freemarker below for tips on updating templates.
- Save your changes to the template. You need to restart your Bamboo server for the template changes to take effect.
Working with Freemarker
The Bamboo notification templates are written in Freemarker. The Freemarker engine allows for dynamic content generation based on the Freemarker markup tags that are used in templates. This document does not describe the Freemarker language in detail. Please see the Freemarker Online Manual for full information on using this markup language.
Generating content via Freemarker involves merging a template (*.ftl file) with a context map. You can access any data in the context map from within the template using the Freemarker markup. For the notifications we have provided a specific subset of Bamboo objects that you can access. For example,
[#if buildSummary.successful]
${buildSummary.buildResultKey} was successful.
If you had a successful Bamboo build with build result, BAM-1234-1, the above markup would return the following text in your notification:
BAM-1234-1 was successful.
You can find more information on working with Freemarker, including Bamboo objects available from Freemarker templates, tips on writing Freemarker templates and examples in the Freemarker and notification templates document.
Configuring notifications content via system properties
The following system properties can be configured to control some of the content that is included in notifications (e.g. the number of log lines to include in email notifications that display log information). For instructions on how to configure a system property, please refer to the Starting Bamboo page.
Before you begin:
The system properties below do not add content to notifications. You still need to ensure that your notification templates contain the relevant entities to display the content. For example, changing the bamboo.notifications.logLinesToInclude property will not add log information to your notifications. It only modifies the number of log lines displayed in notification templates that already include logs.
System Property | Description | Default Value |
|---|---|---|
| Specifies the number of log lines to include in email notifications that display log information. | 100 |
Notes
- Bamboo does not validate notification templates. If you have incorrectly formatted the markup text in the template, Bamboo will still use the template to send out notifications. If this happens, your users may receive notifications with unreadable or missing information, as well as error messages. Errors will also be posted to your logs.