ccollab admin trigger update-changelist

Applies to Collaborator 14.6, last modified on October 03, 2024

Description

It is convenient to have information like review id and participants' names in the description of a changelist, for which you created a review in Collaborator. Use this trigger to append review-specific information to or update it in the description automatically.

If you use this trigger as a "submit" trigger, it will add or update review-specific values in the description of a pending changelist when you are submitting this changelist to the repository. If you use this trigger as a "form-in change" trigger, then users will see the updated description whenever they edit the changelist.

All review-specific values appear in a single line in the description. You specify the values to be added in the command line (see below).

Command Line Syntax

ccollab [global-options] admin trigger update-changelist [--description-prefix <value>] [--description-template <value>] <changelist-spec>

Command Options

Option

Required?

Description

--description-prefix <value>

Yes

Specifies the prefix text for the review line in changelist description. The trigger uses this text to find the review line in the description (see the Remarks section below).

--description-template <value>

Yes

A single-line string that contains an arbitrary text and review-specific data to be posted to the changelist description. To insert review-specific values, use Collaborator variables (${...}). See examples in the Installation section below.

<changelist-spec>

Yes

%changelist% for a trigger of the submit or commit type, or %formfile% for a trigger of the form-in type.

Installation

To install the trigger, add a line like one of those below to your Perforce Triggers list:

  • Example 1: Adding the trigger as a submit trigger:

    ccollabupdatechangelist change-commit //depot/... "/usr/bin/ccollab --url <collabUrl> --user <collabUser> --password <collabPasswd> --scm perforce --p4port <p4port> --p4user <p4user> --p4passwd <p4passwd> --p4client <p4client> admin trigger update-changelist --description-prefix %quote%Review: %quote% --description-template %quote%ID ${review.id} by ${review.participants.rolename}%quote% %changelist%"

  • Example 2: Adding the trigger as a form-in trigger:

    ccollabupdatechangelist form-in change "/usr/bin/ccollab --url <collabUrl> --user <collabUser> --password <collabPasswd> --scm perforce --p4port <p4port> --p4user <p4user> --p4passwd <p4passwd> admin trigger update-changelist --description-prefix %quote%Review: %quote% --description-template %quote%ID ${review.id} by ${review.participants.rolename}%quote% %formfile%"

Some notes:

  • Specify your installation directory for ccollab and replace <values> with appropriate data. Also, type all parameters in a single line even though the text above occupies several lines.
  • The Perforce user that you specify must have read-write access to the changelist.
  • On Unix systems, Perforce incorrectly recognizes arguments that include spaces. It ignores quotes and other standard ways of indicating that the data with spaces is actually one argument. The workaround is to use a separate bash script to call our trigger.

Remarks

  • The --description-prefix option serves as an identifier of the review line in the changelist description. The trigger uses it to find the review-specific string within the description. If the string is found, the trigger updates information in-place. If the string is not found, the trigger appends a new line with review-specific data to the end of the description.
  • If there is a review in Collaborator that matches the specified changelist, the changelist description is always updated (either in-place, or appended as it was described above).
    If there is no review for the specified changelist, the description is updated only if the prefix is already present in the description. If the prefix is not found, the trigger does not append review-specific data to the description.
  • If the specified changelist is used in several reviews, then the ${review.id} variable will refer to the most recent of these reviews.
  • For information on variables that you use to insert review-specific data, see Variable Substitution. The examples in the Installation section insert the review identifier and a list of participants, plus the appropriate English words.
  • For information on Perforce triggers, see Perforce System Administrator's Guide.

See Also

ccollab admin trigger
Perforce Integration

Highlight search results