Customizing Notification Emails

Overview

1. a Groovy script (see *.groovy files) that determines whether emails are sent or not
2. a Velocity template (see *_subject.vm files) to specify the subject of the email
3. a Velocity template (see *_body.vm files) to specify the body of the email

Customizing the Email Content

Velocity is a powerful, yet simple template technology. For general information about the Velocity template language, read Velocity Engine Manual. CodeBeamer supports every feature available in Velocity (conditions, cycles, arithmetic, etc.).
The templates can be modified on-the-fly, there is no need to restart the container (Tomcat).

Velocity context for each Email Type

The following beans can be used in the email templates. These are available both in the subject and body templates.

Note that for the nested object (e.g. trackerItem.tracker), only the id and name properties are fetched for performance reasons.

Examples

To display the project name in the subject of tracker issue creation emails, modify tracker_item_created_notification_email_subject.vm as:

New CB Tracker Item in ${trackerItem.tracker.project.name} "${trackerItem.summary}"

To display the severity of a tracker issue when it is updated, you have to iterate over it as a collection property in tracker_item_updated_notification_email_body.vm:

Severity:
#foreach($severity in $trackerItem.severities)
	${severity.name}
#end

To display the full commit message in the email subject, remove the use of the textFormatter.abbreviate tool in scc_modification_committed_notification_email_subject.vm as:

CB Change Committed to [${commit.project.id}] ${commit.project.name} "${commit.message}"

#if(${commit.changeFiles.size()} == 1)
	(1 change)
#else
	(${commit.changeFiles.size()} changes)
#end

(+${diffStats.linesAdded} -${diffStats.linesRemoved})

Customizing the Email Sending

CodeBeamer runs a Groovy scripts to decide whether to send a notification email to an addressee. For each mail and for each addressee, it evaluates a script that must return a boolean return value:

• TRUE: send the mail to the addressee
• FALSE: skip this addressee

Groovy is a full-blown scripting language that integrates very well with Java, so you have unlimited possibilities with this and in most of the cases it requires only minimal programming skills. Our only limitation is that there is one script for each email type and you can't customize it for each user.
The default scripts that are shipped with CodeBeamer will allow sending any email to all addressee:

return true

The scripts can be modified on-the-fly, there is no need to restart the container (Tomcat).

Examples

To disable tracker item creation emails in certain projects or trackers, modify tracker_item_created_notification_script.groovy by adding the appropriate project IDs or tracker IDs to the lists:

// list of project IDs, tracker IDs and tracker item IDs
// that will be ignored when sending notification emails
def ignoredProjects = [-1, -2]
def ignoredTrackers = [-1, -2]
def ignoredTrackerItems = [-1, -2]

// reject if listed
if(trackerItem.tracker.project.id in ignoredProjects ||
   trackerItem.tracker.id in ignoredTrackers ||
   trackerItem.id in ignoredTrackerItems) {
	return false
}

return true

To restrict tracker item update emails only to certain property changes, check the modifiedProperties collection in tracker_item_updated_notification_script.groovy. In this example, the mail will be sent only when status is changed to Closed:

for(modifiedProperty in modifiedProperties) {
  if(modifiedProperty.fieldName == "Status" && modifiedProperty.newValue == "Closed") {
    return true;
  }
}

return false;

Temporarily Disabling Notification Emails at High Memory Usage

Notification emails may contribute to the server overload when the amount of free memory is low. You can use a Groovy script to temporarily disable these emails based on the memory usage:

1. Navigate to the CODEBEAMER_HOME/tomcat/webapps/cb/config/templates/email directory.
2. Locate the .GROOVYfile related to the notifications you want to temporarily disable based on the memory usage.
   • For example, tracker_item_mass_updated_notification_script.groovy
3. Backup the file.
4. Edit the file and replace the content with the following Groovy script:

   • import org.apache.logging.log4j.LogManager
     import org.apache.logging.log4j.Logger
     
     def MAX_MEMORY_USAGE = 80 // In percentage, adjust as needed
     
     def logger = LogManager.getLogger("EMAIL_SCRIPT")
     
     def runtime = Runtime.getRuntime()
     def MB = 1024*1024;
     def totalMemory = Math.round(runtime.totalMemory()/MB);
     def freeMemory = Math.round(runtime.freeMemory()/MB);
     def maxMemory = Math.round(runtime.maxMemory()/MB);
     def usedMemory = Math.round(totalMemory - freeMemory);
     def usedMemoryPercentage = Math.round((usedMemory/maxMemory) * 100);
     
     logger.info("Used memory " + usedMemory + "M from maximum " + maxMemory + "M percentage:" + usedMemoryPercentage + "%");
     
     if (usedMemoryPercentage > MAX_MEMORY_USAGE) {
       logger.warn("Skipping email sending because used memory: ${usedMemoryPercentage}% is exceeding threshold of ${MAX_MEMORY_USAGE}%")
       return false;
     }
     
     return true;

5. Save the file. The change takes effect immediately. Codebeamer server restart is not required.

Explanation

The script temporarily disables the email notifications when Codebeamer uses more than 80% of the available memory. You can customize the maximum memory threshold using the MAX_MEMORY_USAGE flag.

Logging

The script also prints information to the server logs. See the following two examples:

• MAX_MEMORY_USAGE threshold is not exceeded:

INFO  EMAIL_SCRIPT - Used memory 715M from maximum 2958M percentage:24% [GlobalScheduler_Worker-10] [37] {Req#=send-tracker-item-notification-job-4f02ea0c-9e11-4897-b754-6bd5b6a78dba, Sess#=send-tracker-item-notification-job-4f02ea0c-9e11-4897-b754-6bd5b6a78dba, serverId=server}    

• MAX_MEMORY_USAGE threshold is exceeded:

WARN  EMAIL_SCRIPT - Skipping email sending because used memory: 85% is exceeding threshold of 80% [GlobalScheduler_Worker-6] [33] {Req#=send-tracker-item-notification-job-f5ff6dd5-cd41-4cd3-901f-2bdd494dd38a, Sess#=send-tracker-item-notification-job-f5ff6dd5-cd41-4cd3-901f-2bdd494dd38a, serverId=server

Adding images to Emails

Normally the images are removed from emails: they are replaced by a an image looks like .

This happens for security reasons and also to prevent broken images in the emails which may happen in the user who looks at the email does not have a permission to view the referenced image(s).

However if you want to include images into your emails and keep them in your custom email templates then your options are:

• Embed your image into the HTML template using Data URI scheme, so these images will be kept in your emails. For example this HTML markup will render an red dot:
  

  <img src="data:image/png;base64,iVBORw0KGgoAAA
  ANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4
  //8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU
  5ErkJggg==" alt="Red dot" />

• Or use a special keepImageInEmailsCSS class in your HTML markup to mark the images should be kept in your email. In the next example the image "myImage.png" will be preserved in your email because it has this special CSS class:
  

  <img src="http://mysite/myimage.png" class="keepImageInEmails" />

Listing All Objects Available in a Groovy Script

The following fragment lists all objects available inside a Groovy script:

// Loop through all variables in the binding and log them:
binding.variables.each { name, value ->
  // Use reflection to get the class type
  def clazz = value.getClass()
  logging.info("Variable: $name, Class: $clazz, value: $value");
}