In a few areas of server configuration (Notification templates, Review templates, Collaborator triggers, Perforce triggers) you are allowed to use variable substitution to insert useful live data into a text-based template.
This section details those variables and how they work.
Syntax
Variable substitution is indicated with a dollar sign followed by curly braces surrounding the variable name. For example, to access the review.creator.name variable you would use this:
${review.creator.name}
When embedding in other text, variables are inserted into the text wherever they should be replaced. An example that is commonly used in the changelist-update Perforce trigger is:
ID ${review.id}: "${review.title}" by ${review.participants.rolename}
Context
Not all of the substitution variables are applicable in all contexts.
-
In general, notification templates use
${review.*}, ${role.*}, ${actor.*}for the sender and${user.*}for the recipient. -
The Review Created trigger uses
${review.*}and${user.*}is the review creator. -
The Review Phase Changed trigger uses
${review.*}and${user.*}(not${actor.*}). -
The Added File trigger uses
${review.*},${changelist.*}and${files.paths}. -
The Notifications Sent trigger uses
${review.*}and${user.*}. -
The Defect Activity trigger uses
${actor.*}and${defect.*}. -
The User Created trigger uses
${user.*}. -
The Role Changed trigger uses
${review.*}, ${user.*} and ${role.*}, where${role.*}stands for the new current role.
Also, pay your attention that not all of the variables are available at the moment the trigger fires. In this case they will return Not available instead of their value.
Section
The following table lists all the variable substitutions.
| Variable | Description | ||
|---|---|---|---|
${review.id} |
The numeric ID of a review. Example: 4235.
|
||
${review.title} |
The title field of a review. This variable is not available for the Review Created trigger. | ||
${review.workflow} |
The name of the workflow (template) this review is currently in. If you change the template name in workflow configuration this text changes too, so be careful of scripts which depend on this value. | ||
${review.phase} |
The name of the phase this review is currently in. For example: Inspection or Completed or Canceled. |
||
${review.phase.previous} |
The name of the previous phase of the review. Valid only in the context of a phase change. | ||
${review.creator.*} |
User information corresponding to the creator of the review. The asterisk should be replaced by a user-specific variable (described elsewhere). For example, the full name of a user: ${review.creator.name}.
|
||
${review.author.*} |
User information corresponding to the primary author assigned in the review. The asterisk should be replaced by a user-specific variable (described elsewhere). For example, the full name of a user: ${review.author.name}.
|
||
${review.custom.*} |
The value of one of the review custom fields. The final variable component should be the full title of the custom field, including whitespace and so forth. If this review does not have this field because the user has not entered it yet, if there is a default value it will be returned. If this review does not have this field because the workflow does not include the field, you will get an error message. If you supply the name of a custom field that does not exist, you will get an error message to that effect including the list of valid custom field names. You can use this fact to create an error on purpose to get the list of valid custom fields. |
||
${review.datecreated} |
The date when the review was created. | ||
${review.deadline} |
The date when the review should be completed. | ||
${review.group.guid} |
GUID of the group associated with the review. | ||
List of role and user pairs of the people assigned to the review. In the rolename case, the full names of users are used. In rolelogin, the system login names of users are used. Roles are named by the display name as configured. Be careful when writing scripts that depend on this text, and remember that different workflows can define different text for the role name.
|
|||
${review.changesummary} |
A multi-line summary of the changes in the review, lines (+add, *mod, -del) for each file.
|
||
${review.shortchangesummary} |
A short summary of the changes in the review, total lines (+add, *mod, -del) for all the files in the review.
|
||
${review.defectlog} |
The log of all defects in a review. | ||
${user.id} |
The unique ID of the user in our own database. | ||
${user.login} |
The system login for the user. If LDAP authentication is being used, this is the LDAP login of the user. The login is unique for every user in the system. | ||
${user.name} |
The full name of a user, as they configured it themselves. This is not guaranteed to be unique in the system. | ||
${user.email} |
The email address of a user. Blank if not configured. | ||
${user.phone} |
The value of a phone number field in a user record, exactly as they configured it themselves. | ||
${files.paths} |
A set of file paths, in no particular order, separated by the pipe symbol. This is typically a set of paths in the SCM server style, not local file paths. This variable is not available for the Review Created trigger. | ||
${changelist.paths} |
Same as ${files.paths}. This variable is not available for the Review Created trigger.
|
||
${changelist.scmid} |
The ID of this changelist according to the SCM system. For example, thechangelist ID in Perforce or Subversion revision number. This variable is not available for the Review Phase Changed trigger. | ||
${changelist.author} |
The author of the changelist according to the SCM system.
|
||
${changelist.comment} |
The comment given in the SCM system for this changelist. | ||
${defect.id} |
The unique ID of this defect in our own database. | ||
${defect.creator.*} |
User information corresponding to the creator of the defect. The asterisk should be replaced by a user-specific variable (described elsewhere). For example, the full name of a user: ${defect.creator.name}.
|
||
${defect.file} |
The full path to the file this defect is attached to, or a blank string if the defect was review-wide. | ||
${defect.line} |
The line number in the file where this defect is attached, or 0 if this defect is attached to the overall file, the overall review, or something else that is not relevant to a specific line.
|
||
${defect.text} |
The text entered in the comment field for this defect. This can be long and multilined. | ||
${defect.isfixed} |
Boolean text. true if the defect is currently marked as fixed, false if the defect is currently opened.
|
||
${defect.isexternal} |
Boolean text. true if the defect is currently marked as external, false if the defect is currently marked as internal.
|
||
${defect.externalname} |
The external name specified when the defect was marked external. | ||
${defect.custom.*} |
The value of one of the defect custom fields. The final variable component should be the full title of the custom field, including whitespace and so forth. If this defect does not have this field because the workflow does not include the field, you will get an error message. If you supply the name of a custom field that does not exist, you will get an error message to that effect including the list of valid custom field names. You can use this fact to create an error on purpose to get the list of valid custom fields. |
||
${role.title} |
The title of the role assigned to the user in the review. | ||
${role.description} |
The description of the role assigned to the user in the review. | ||
${comment.text} |
The plain-text version of the comment. | ||
${actor.*} |
The user responsible for triggering this action. The asterisk should be replaced by a user-specific variable (described elsewhere). | ||
${actionUser.id} |
The unique ID of the user who is involved in trigger action. | ||
${actionUser.login} |
The login of the user who is involved in trigger action. | ||
${actionUser.name} |
The name of the user who is involved in trigger action. | ||
${actionUser.email} |
The email address of the user who is involved in trigger action, or blank if it is not configured. | ||
${actionUser.phone} |
The phone number of the user who is involved in trigger action, or blank if it is not configured. | ||
${remotesystem.title} |
The title of the remote repository integration as specified in its configuration. | ||
${remotesystem.repourl} |
The URL of the remote repository integration as specified in its configuration. | ||
${remotesystem.token} |
The short name of remote repository service: GitHub, GitLab, Bitbucket, Bitbucket Server, Azure DevOps. | ||
${pullrequest.id} |
The identifier of the pull request. | ||
${pullrequest.title} |
The title of the pull request as specified on the remote repository side. | ||
${project.id} |
The identifier of the project. | ||
${project.title} |
The title of the project. |