Collaborator Server > Server Administration

Top |Previous |Next

Variable Substitution

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.*}. And 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.

Reference

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). So for example, the user's full name would be ${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). So for example, the user's full name would be ${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.title}

Title of the group associated with the review.

${review.group.guid}

GUID of the group associated with the review.

${review.participants.
rolename}

${review.participants.
rolelogin}

List of role/user pairs of the people assigned to the review. In the rolename case the user's full names are used; in rolelogin the user's system login names 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 user's LDAP login. The login is unique for every user in the system.

${user.name}

The user's full name, as they configured it themselves. This is not guaranteed to be unique in the system.

${user.email}

The user's email address, or blank if it is not configured.

${user.phone}

The user's phone number field, 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, Perforce changelist ID 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.
 
Note that although this username might correspond to a user in Collaborator, this is not required. Further note that because this is a simple text field and not a user object, you cannot continue with other sub-fields like email or phone number.

${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). So for example, the user's full name would be ${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's not relevant to a specific line.
 
Note that this line number refers to the file at the time of review; in the future the file can change and line numbers can change with it.

${defect.text}

The text entered in the comment field for this defect. This can be long and multi-lined.

${defect.isfixed}

Boolean text "true" if the defect is currently marked fixed, "false" if the defect is currently open.

${defect.isexternal}

Boolean text "true" if the defect is currently marked 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.


© 2003-2025 SmartBear Software. All rights reserved.