Variable Substitution

 Top  Previous  Next

In a few areas of server configuration (e.g. 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}

 

Reference

The following table lists all the variable substitutions.

${review.id}

The numeric ID of a review.  Example: 4235
${review.title}

The title field of a review.
${review.workflow}

The name of the workflow this review is currently in.  If you change the 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, e.g. "Inspection" or "Completed" or "Canceled".
${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 doesn't have this field because the user hasn't entered it yet, if there's a default value it will be returned.  If this review doesn't have this field because the workflow doesn't include the field, you will get an error message.

If you supply the name of a custom field that doesn't exist, you'll 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.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.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.group.title}

Title of the group associated with the review.
${review.group.guid}

GUID of the group associated with the 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's 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.
${changelist.paths}

Same as ${files.paths}.
${changelist.scmid}

The ID of this changelist according to the SCM system.  For example, Perforce changelist ID or Subversion revision number.
${changelist.author}

The author of the changelist according to the SCM system.
 
Note that although this username might correspond to a user in Code 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.
${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 of code.
 
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.isexternal}

Boolean text "true" if the defect is currently marked external, "false" if the defect is currently open.
${defect.externalname}

The external name specified when the defect was marked external.
${defect.isfixed}

Boolean text "true" if the defect is currently marked fixed, "false" if the defect is currently open.
${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 doesn't have this field because the workflow doesn't include the field, you will get an error message.

If you supply the name of a custom field that doesn't exist, you'll 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
${actor.*}

The user responsible for triggering this action. The asterisk should be replaced by a user-specific variable (described elsewhere).