Notification template variables

Use variables in your notification templates.

Notification templates

Notification templates are HTML documents that combine static and dynamic elements to create email messages. The messages can provide information about the events that trigger the notifications and other related information. As triggering events occur, variables in the template are resolved based on the context of the event. Notifications can be triggered for events related to releases, applications, deployments, segments, tasks, and approvals. You use templates by attaching them to rules in notification schemes or to notification tasks.

Template variables are resolved with the Velocity Template Language (VTL). IBM® UrbanCode™ Release supports VTL 1.7 or above. The variables that are available depend on the event and the context. The following sections describe the most commonly used variables and their properties. The contexts in which the variables are referenced are provided along with examples of use.

VTL variables

You can enter variables into the template Subject or Body areas. The syntax for variables is the prefix character of $ followed by an identifier. For example, to display the current task, you enter:
$task
To reference variable properties, the syntax is the prefix character of $ followed by an identifier, followed by the period character ., followed by another identifier. For example, to reference the name of the current task, you enter:
$task.name

To display the status for a deployment, you can use a statement similar to the following code fragment:

$scheduledDeployment.deployment.status
You can intersperse variables with static text. For example, you might add static text to the variable:
The currrent status is $scheduledDeployment.deployment.status

VTL operations

You can create variables by using the VTL #set statement. For example, you can create a variable named $myVariable by using this statement:
#set($myVariable = "Release1")
You can use other VTL operations such as #foreach and #if.
For example, you can run null value checks by using statements similar to this example:

#if (some_variable) 
 ... do stuff here if the variable is not null
#end

For more information about VTL, see the VLT documentation.

Dates

Most date variables are time stamps. You can format the time stamps with the templateUtil.formatter, which has this syntax:

$templateUtil.format($[dateToFormat], '[Format Pattern]') 
To display the scheduled date for a deployment, you can use a statement similar to this code fragment:

$templateUtil.format($scheduledDeployment.scheduledDate, 'MM/dd/yy hh:mm a')

A notification message with this statement displays a value similar to this example: 03/30/16 12:00 AM.

See the Java SimpleDateFormat documentation for the available patterns.

Images

To use images in templates, the images must be uploaded to the server, and then referenced in the template Body. Images are stored in the directory specified by the notification.images.folder.path property in the server.properties file. By default, the location is [server_installation]/UCRelease/ucrelease/notification-images folder.

To insert the image in the message body, use the following syntax:


<img src=../notificationTemplates/image/[Name of image]�? width=�?[Size in pixels]’/>
Note: If you use a high availability configuration, the folder that is specified by the notification.images.folder.path property must be shared by all nodes.

The supported image format is PNG.

Environment variable available to all notifications

The $serverURL variable is available to all notification messages. The $serverURL variable returns the public URL of the IBM UrbanCode Release server, and can be used in hyperlinks.

Event variables

The following variables are available to all notification messages and are inherited from the triggering event.
Table 1. Variables available for all notifications inherited from the triggering event
Variable Variable description Properties Property description
$event Event that triggered the notification.

$event.displayName

Event name. For example, Task is about to start.
$event.detailText Event description. For example, This task is estimated to start in X minutes.
$eventDate Event date. For example, 03/30/16 05:11 PM.
$rule Notification rule that triggered the notification. $rule.offsetInMinute Number of minutes before or after the event as defined by the rule. For example, This task is more than 6 minutes late.
$user User who is the recipient of the notification message. $user.displayName or $user.Name John Smith.

Release variable

Releases are referenced with the $release variable. The release variable returns the release that triggered the notification.

The $release variable properties are described in the following table.
Table 2. $release variable properties
Property Description Example
$release.name Name of the release. March Release
$release.targetDate Planned release date. 03/30/16 05:11 PM
$release.applications Application that is assigned to the release.

JPetStore
Pet Accounting
$releaseUrl Hyperlink to the release. http://localhost:8080/urelease/release/000000000036
To display all applications in the release, you can use a statement similar to this code fragment:

#foreach ($application in $release.applications)
    $application.name
#end

Application variable

Applications are referenced with the $application variable. When an application is added to a release or removed from one, the application is available to the release context.

The $application variable properties are described in the following table.
Table 3. $application variable properties
Property Description Example
$application.name Name of the application. JPetStore
$application.description Application description. Ecommerce application for pet supplies.

Scheduled deployment variable

Scheduled deployments are referenced with the $scheduledDeployment variable. This variable returns the deployment that triggered the notification.

The context for the $scheduledDeployment is the release for which the deployment is scheduled.

The $scheduledDeployment variable properties are described in the following table.
Table 4. $scheduledDeployment variable properties
Property Description Example
$scheduledDeployment.derivedName Computed name for that scheduled deployment. March Release:DEV-1 at March 30, 2016 at 5:26:00 PM EDT
$scheduledDeployment.status Scheduled deployment status color. Possible values are Green / Orange / Red
$scheduledDeployment.statusText Text that describes the status of the scheduled deployment. There are issues with the database backup.
$scheduledDeployment.deployment.status Scheduled deployment execution status. Possible values are EMPTY, NOTSTARTED, INPROGRESS, SOFTFAILED, FAILED, COMPLETE, ABORTED
$scheduledDeployment.scheduledDate Deployment scheduled date. March 30, 2016 at 5:26:00 PM EDT
$scheduledDeployment.deployment.startTime Actual deployment start time. March 30, 2016 at 5:26:00 PM EDT
$scheduledDeployment.deployment. endTimeActual Actual deployment end time. March 30, 2016 at 8:32:00 PM EDT
$scheduledDeployment.environment.name Name of the scheduled deployment environment. PROD-1
$scheduledDeployment.phase.phaseModel.name Name of the scheduled deployment phase. PROD
$scheduledDeployment.autoStart Indicates whether the scheduled deployment started automatically. Possible values are False / True
$scheduledDeployment.approval.taskList List of approvals for the scheduled deployment. Prod Deployment Approval - SUCCESS - CLOSED
$scheduledDeployment.versions List of versions in the scheduled deployment. PetStore -1.1 Pet Accounting – 2.0
$segments or $scheduledDeployment.deployment.segments List of segments in the scheduled deployment.

Pre-Deployment Tasks
Deployment Task
Post-Deployment Tasks
$scheduledDeployment.relatedDeployment.event.name Enterprise event that the deployment is participating in. March Enterprise Release Event
$scheduledDeploymentUrl URL of the scheduled deployment. http://localhost:8080/urelease-dev/scheduledDeployment/1f45bc60-da7c-4de3-ad7b-59eb03c1b955#execution
To display all approvals in a scheduled deployment, you can use a statement similar to this code fragment:

#foreach ($approval in $scheduledDeployment.approval.taskList)
    $approval.name -  $approval.result - $approval.status 
#end
To display all versions in a scheduled deployment, you can use a statement similar to this code fragment:

#foreach ($version in $scheduledDeployment.versions)
    $version.application.name -  $version.name
#end
To display all segments in a scheduled deployment, you can use a statement similar to this code fragment:

#foreach ($segment in $scheduledDeployment.deployment.segments)
    $segment.name 
#end

Task variable

Tasks are referenced with the $task variable. This variable returns the task that triggered the notification.

The contexts for the $task variable are described in the following table.

Table 5. $task variable contexts
Context Description
$segment Parent segment of the task.
$scheduledDeployment Scheduled deployment to which the task belongs.
$release Release to which the task belongs.
The $task variable properties are described in the following table.
Table 6. $task variable properties
Property Description Example
$task.Name Task name. Deploy War File
$task.description Task description. Backup all databases for JPetStore
$task.duration Task duration in minutes. 10
$task.executorRole.name Role that is assigned to the task. Release Manager
$task.executorGroup.name Group that is assigned to the task. Support Group
$task.currentAssignedUser.name User who is assigned to the task. John Smith
$task.application.name Name of the application assigned to the task. JPetStore
$task.automated Indicates whether the task is automated. True / False
$task.comments Comments that are attached to the task. First attempt to deploy failed – 10/12/16 10:45 AM.
$task.status Task status. Possible values are PLANNED, OPEN, EXECUTING, CLOSED
$task.result Task result. Possible values are SUCCESS, FAILURE, SKIPPED, NOT_APPLICABLE
$task.startTimeActual Time that the task started. 10/12/16 10:45 AM
$task.endTimeActual Time that the task finished. 10/12/16 10:45 AM
$taskUrl URL of the task. http://localhost:8080/urelease-dev/scheduledDeployment/1f45bc60-da7c-4de3-ad7b-59eb03c1b955#execution/Segment/39aa9dfb-0d01-46cb-a8e3-b0b56aaf9214/TaskExecution/5de5e93a-2b48-4778-b72d-d92317cba501
To display all comments added to a task, you can use a statement similar to this code fragment:

#foreach ($comment in $task.comments)
    $comment.comment - $templateUtil.format($comment.dateCreated, 'MM/dd/yy hh:mm a')
#end
To display the actual start time for a task, you can use a statement similar to this code fragment:

$templateUtil.format($task.startTimeActual, 'MM/dd/yy hh:mm a')
    

Segment variable

Segments are referenced with the $segment variable. This variable returns the segment that triggered the notification.

The contexts for the $segment variable are described in the following table.

Table 7. $segment variable contexts
Context Description
$scheduledDeployment Scheduled deployment to which the task belongs.
$release Release to which the task belongs.
The $segment variable properties are described in the following table.
Table 8. $segment variable properties
Property Description Example
$segment.Name Segment name. Deployment Tasks
$segment.description Segment description. All tasks related to deployments
$segment.role.name Role that is assigned to the segment. Release Manager
$segment.group.name Group that is assigned to the segment. Marketing Group
$segment.tasks Tasks in the segment.

Backup DB 
Deploy WAR
To display all tasks in a segment, you can use a statement similar to this code fragment:

#foreach ($task in $segment.tasks)
    $task.name 
#end

Approval variable

Approvals are referenced with the $approval variable. This variable returns the approval that triggered the notification.

The contexts for the $approval variable are described in the following table.

Table 9. $approval variable contexts
Context Description
$scheduledDeployment Scheduled deployment to which the task belongs.
$release Release to which the task belongs.
The $approval variable properties are described in the following table.
Table 10. $approval variable properties
Property Description Example
$approval.Name Approval name. Allow Production Deployment
$approval.status Task status. Possible values are PLANNED, OPEN, CLOSED
$approval.result Task result. Possible values are SUCCESS, FAILURE
$approval.currentAssignedUser.name User who provided the approval. John Smith
$approval.executorRole.name Role that is assigned to the approval. John Smith
$approval.endTimeActual Time the approval was made. 10/12/16 10:49 AM