You are not logged in. Click here to log in.

codeBeamer ALM

Search In Project

Search inClear

Customizing Notification Emails

Overview

Email content generated by Codebeamer is completely customizable.
The templates that are used to render the emails are found in the CODEBEAMER_HOME/tomcat/webapps/cb/config/templates/email directory. There is one set of 3 files for each email type:
  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.

Email TypeObjects
Anyoriginator (who performed the action),
recipient,
remoteAddress (if available)
artifact_comment_createdcomment,
artifact,
artifact.project
artifact_* artifact,
contentUpdated (boolean flag),
diffHtml
forum_post_createdforumPost,
forumPost.forum,
forumPost.forum.project
lost_passwordpassword (String),
homeSite (URL as String)
project_createdproject
project_join_*project,
comment (String)
scc_modification_committedcommit (the changeset itself),
commit.changeFiles,
commit.project,
diffHtml,
diffStats
send_emailbody (String)
tracker_item_association_createdassociation,
assocaition.fromDto,
association.toDto,
trackerItem,
trackerItem.tracker,
trackerItem.tracker.project
tracker_item_attachment_createdattachment,
attachment.trackerItem,
attachment.trackerItem.tracker,
attachment.trackerItem.tracker.project
tracker_item_comment_createdcomment,
comment.trackerItem,
comment.trackerItem.tracker,
comment.trackerItem.tracker.project
tracker_item_*trackerItem,
trackerItem.tracker,
trackerItem.tracker.project,
modificationComment and modificationCommentFormat (if comment is not empty),
modifiedProperties (collection)
user_*user (the actual account the email is related to, it's not identical with the originator!)
wikipage_comment_createdsame as for artifact_comment_created
wikipage_*same as for artifact_*, but wikiPage instead of artifact

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;