Variable Substitution

Applies to Collaborator 13.5, last modified on December 21, 2021

In a few areas of server configuration (Notification templatesCollaborator 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.

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.

${review.participants.rolename}

${review.participants.rolelogin}

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.
Note: Though this username might correspond to a user in Collaborator, this is not required. Also, since this is a simple text field and not a user object, you cannot continue with other subfields 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).
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.
Note: 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 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
${actor.*} The user responsible for triggering this action. The asterisk should be replaced by a user-specific variable (described elsewhere).

See Also

Triggers
Notification Templates
Admin Tasks

Highlight search results