Freemarker and notification templates

Modifying notification templates

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

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.

(warning) 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.

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]
Last modified on Aug 10, 2021

Was this helpful?

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