Change Request Message Template Syntax

This topic describes the cr-new.txt message template file and examines message template syntax in general. You can use HTML or text format for your custom templates. You server configuration repository contains a Notifications subfolder containing this file and other message template files in both HTML and text format for change requests, requirements, tasks, and topics.

cr-new.txt

This message has been sent to you automatically by StarTeam Server
because the Change Request described below has been created
by ~~ModifiedUserID~~.
The Change Request is located in
Project: ~~project~~
View: ~~view~~
Property Summary:
Type: ~~type~~
Status: ~~status~~
Responsibility: ~~responsibility~~
Priority: ~~priority~~
Severity: ~~severity~~
Platform: ~~platform~~
Entered By: ~~EnteredBy~~
Entered On: ~~EnteredOn~~
Synopsis: ~~synopsis~~
Description: ~~Description~~
You can access Change Request #~~ChangeNumber~~ by following this URL:
~~url~~

Examining the Message Template Syntax

Whenever you want to use the current value for a property field, enter the internal name for that field preceded and followed by two tildes (~~). For example, Status: ~~status~~ displays the word “Status:” in the email followed by the current value of the status property.

The file also uses ~~url~~ to include the StarTeam URL for the change request.

Note: Client-calculated property fields cannot be used in the notification message templates. Refer to the Fields Reference link at the bottom of this topic for a list of all fields. The description for the field includes its internal name and whether it is a client-calculated property.

Displaying Values for Modified Fields

The text of cr-modified.txt uses the following syntax:

~~isnew.AddressedBy?Addressed By: ~~~~isnew.AddressedBy~~~~isnew.AddressedBy?~~

In these expressions, the isnew prefix precedes the internal name of the property field. This allows a template to specify that the property field value and/or additional formatting text should be included in the resulting notification email only if the value of the field has been changed, that is, only if the previous version had a different value for this field.

The text Addressed By: (from the first expression, ~~isnew.AddressedBy?Addressed By: ~~), the value of the AddressedBy property (from the second expression ~~isnew.AddressedBy~~) and a trailing linefeed (from the last expression) display in the email notification message only if the value of the AddressedBy property has been changed from the previous revision of the change request.

If you are using an HTML message template instead of the text version, you could display the output of the expression in bold text (only if it was changed for this revision) as follows:

Addressed By: ~~isnew.AddressedBy? <b>~~~~AddressedBy~~~~isnew.AddressedBy?</b>~~

The above example behaves as follows in an email notification:

Addressed By:: (Text or formatting always included)
~~isnew.AddressedBy?<b>~~: (Text or formatting included only if the AddressedBy field changes in this revision)
~~AddressedBy~~: (Value always included)
~~isnew.AddressedBy?</b>~~: (Text or formatting included only if the AddressedBy field changes in this revision)

Definition of Message Template Syntax

In general, you can enter the following information into the message template files:

Note: In the following examples, propname could be type, status, responsibility, and so on. Refer to the example cr-new.txt file at the beginning of this topic for more examples of property field names.

~~propname~~: Replaced with the value of the specified property.
~~old.propname~~: Replaced with the old value of the specified property.
~~new.propname~~: Replaced with the new value of the specified property.
~~project~~: Replaced with the name of the project containing the item. This is not available as a normal item property.
~~view~~: Replaced with the name of the view containing the item.
~~url~~: Replaced with a StarTeam URL of the item.
~~isnew.propname~~: Replaced with the value of the propname property only if the property has a new value. Otherwise, this expression resolves to an empty string.
~~isnew.propname?text-string~~: Replaced with the text-string text only if the propname property has a new value. Otherwise, this expression resolves to an empty string.