Freemarker and notification templates
Notification templates in Bamboo can be modified to customize the format and content of your notifications. The templates are written in Freemarker. This page is intended to complement the Modifying notification templates page and contains information on the Bamboo objects available from Freemarker templates, tips on writing Freemarker templates and examples.
Changes to notification templates only take effect after a Bamboo restart.
Accessing Bamboo data
Each individual notification has a different subset of data that can be accessed from the Freemarker templates. You can find information on the objects available in our javadocs below.
- Build Completed Notification ("All Completed Builds" and "Failed and First Success")
- After X Failed Builds Notification
- Build Commented Notification
- Build Hung Notification
- Build Error Notification
Special considerations when working with Freemarker
Never assume data exists
Unfortunately Freemarker is not very forgiving if data does not exist or is null. Hence, you will need to check whether information exists before adding it to a page. The sample code below shows how you can validate for non-existent data.
[#if issue.jiraIssueDetails.summary?has_content][/#if]
[#if issue.jiraIssueDetails.summary??][/#if]
${issue.jiraIssueDetails.summary?if_exists}
${issue.jiraIssueDetails.summary!}
Check the encoding of your information
Freemarker has built-in utilities for escaping special characters. These could be characters that you deliberately do not want to be interpreted as HTML, or data that could potentially contain malicious content. The sample code below shows how you can escape characters in Freemarker.
${commit.comment?html} // for data to be encoded to be displayed as html
${commit.author?url} // for data to be encoded for a url
You can find more information on these utilities in the official Freemarker documentation.
Use white space carefully
When editing text email content and instant message content, you need to be very careful with spacing and line breaks. Any spaces and line breaks that you have entered in the Freemarker template will also exist in the evaluated content. Freemarker provides you with some utilities to remove white space, so that you can still retain some formatting in the templates.
More information can be found the official Freemarker documentation.
Freemarker examples
Below are some raw examples of additional information that you can add to your emails.
Please note, these examples are intended to demonstrate the use of Freemarker and how to access Bamboo objects. You will need to modify these examples to include your desired formatting and make it work with your data.
List files in a commit
[#if buildSummary.commits.size() > 0]
[#list buildSummary.commits as commit]
[#if commit_index gte 3][#break][/#if] //only shows 3 commits
Author: <a href="[@ui.displayAuthorOrProfileLink commit.author/]">
${commit.author.fullName?html}
</a>
<br/>
Comment: ${commit.comment?html}
<br/>
[#if commit.guessChangeSetId()?has_content]
Revision: ${commit.guessChangeSetId()?html}
<br/>
[/#if]
[#if commit.files?has_content]
Files:
[#list commit.files as file]
${file.cleanName} [#if file.revision?has_content](${file.revision})
<br/>
[/#list]
[/#if]
[/#list]
[#else]
This build does not have any commits.
[/#if]
Provide test error details
[#list buildResults.testResults.newFailedTests.values() as testResultClass]
[#list testResultClass.testResults as testResult]
<a href="${baseUrl}${fn.getViewTestClassResultUrl(build.key, buildResults.buildNumber, testResultClass.name)}">
${testResultClass.shortName?html}
</a> :
<a href="${baseUrl}${fn.getViewTestCaseHistoryUrl(buildSummary.buildResultKey, testResult.className,
testResult.actualMethodName)}">
${testResult.methodName?html}
</a>
<br/>
[#if testResult.errors?has_content]
[#list testResult.errors as error]
<pre>${error.errorMessage}</pre> // a <pre/> tag is required to reserve formatting of error
[/#list]
[/#if]
[/#list]
[/#list]