Change requests configurations

This topic describes the change requests configuration file and how to set the message syntax.

Change request configuration file

This section describes the ChangeRequest.xml configuration file. Your server configuration repository contains a Notifications subfolder containing this and other configuration files.

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<notification-config version="1.0">  <rule-list>    <rule project="*" event="new" template="cr-new-html"/>    
  <rule project="*" event="modified" template="cr-modified-html"/>  </rule-list>  
     <template-list>     
       <template>   
         <subject>New Change Request #~~ChangeNumber~~</subject>       <body content-type="text/html" template-file=".\cr-new.html" />     
       </template>     
       <template>       
         <subject>Modified Change Request #~~ChangeNumber~~</subject>       <body content-type="text/html" template-file=".\cr-modified.html" />     
       </template>     
      <template>       
         <subject>New Change Request #~~ChangeNumber~~</subject>       <body content-type="text/plain" template-file=".\cr-new.txt" />     
      </template>     
      <template>       
        <subject>Modified Change Request #~~ChangeNumber~~</subject>       <body content-type="text/plain" template-file=".\cr-modified.txt" />     
      </template>  
   </template-list>
</notification-config>

Note: template is a mandatory rule attribute. It specifies the message template that you wish to use for the notification and it must correspond to one of the template nodes, such as <template id=”cr-new-html”>. event and project are optional rule attributes. event specifies whether the item triggering the notification is being created (“new”) or edited (“modified”) or either of the two (“*”). If omitting the event attribute, the notification applies to any event. project allows the notification to be limited to a certain project or projects only. If omitted, the notification applies to all projects.

Note: You can give the template-file attribute an absolute file path or a path relative to the Notifications folder.

Understanding the change requests configuration file

When you create or modify a change request, the server searches through the rules defined in the <rule-list> element for the first project attribute that matches the name of the current project that consists of more than the asterisk wildcard character. This allows you to use project=”*” for any projects where you have not created a more specific rule. For example, using the sample code shown above, a project names Project2 would use the text templates and a project named Whitestar would use the HTML templates.

Next, the server searches the matching rule to determine if it applies to the current “new” or “modified” change request. The event attribute of the rule determines this by the values “new” or “modified”. If this value is absent or set to “*”, all change requests use the rule. If the current change request is new, a rule with an event attribute of “new” or “*” must be found.

Once the server finds the correct rule, the template attribute indicates where to look in this .xml file for the subject line to use in the email, the type of template file, and the path to the template file. In the sample ChangeRequest.xml file, if the template attribute in the selected rule was “cr-new-txt” the server uses the following template section to obtain more information:

<template id=”cr-new-txt”><subject>New Change Request #~~ChangeNumber~~</subject><body content-type=”text/plain” template-file=”.\cr-new.txt” /></template>

The subject line of the email reads New Change Request followed by the change request number. The template content type is “text/plain” and the template file is located at “.\cr-new.txt”. You can use the absolute path or a path relative to the Notifications folder for the location of the template file. This example uses a relative path to locate the template file within the Notifications folder.

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~~

Message template syntax rules

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)

Property field names in a message template

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.