October 26, 2010

Display the Information You Need with Surround SCM Custom Fields and Triggers

Surround SCM
Every once in a while we get feature requests for new columns in the Surround SCM Source View window. Some of the most popular column requests are for the comments that were part of the last check in of a file, the last user who performed a check in, and the last defect number the file was attached to. (By the way, make sure you are submitting your feature requests. That's the only way we'll know about them.) While all feature requests are reviewed, and may be implemented in a future release, we haven't yet added new columns to the Source View. So, I'm going to show you how to use Surround SCM's customer fields and triggers to create your own Source View columns. For this example, I'm going to create a column that displays the last user to check in the file.

Step 1: Create Custom Field

The Surround SCM User Guide is an excellent resource for learning more about custom fields. Here I am just going to show a screenshot of how I configured my custom field under Tools > Administration > Custom Fields.

Surround SCM Custom Field

If you want to display different information, you'll probably want to use a different field format and name.

Step 2: Create the Batch File

The batch file is run by the Surround SCM trigger every time a check in takes place. The batch file takes advantage of Surround SCM's environment variables, which are available at run time. For a complete list of what information is available at run time, Appendix D of the Surround SCM User Guide is the place to go. Following is the content of the batch file:
sscm setcustomfield "%SSCM_FILE%" 1003 "%SSCM_USER%" -b"%SSCM_BRANCH%" -p"%SSCM_REPOSITORY%" -yAdministrator -z127.0.0.1:4900>>c:setfield.log
Let's break this down.
sscm setcustomfield
This is the command line interface (CLI) command to set a custom field. For more information about this command, review the Surround SCM CLI Guide.
"%SSCM_FILE%"
This is the Surround SCM environment variable that contains the file name that caused the trigger to fire. Use quotation marks in case the file name has spaces.
1003
This is the ID of the custom field. To find out the ID of your custom field, run the sscm lscustomfield command. For more information about this command, review the Surround SCM CLI Guide.
"%SSCM_USER%"
This is the Surround SCM environment variable that contains the user who performed the action that fired off the trigger. This is the user to set the custom field. If you want to set your custom field to a different value, use a different environment variable. For example, you could use "%SSCM_DEFECTNUMBER%" if you want to set it to the defect number that you attached the file to.
-b"%SSCM_BRANCH%"
The -b option is the branch where the custom field is changed. The %SSCM_BRANCH% environment variable is the branch where the action that launched the trigger took place. This is the same branch where I want to set the custom field.
-p"%SSCM_REPOSITORY%"
The -p option is the repository path. The %SSCM_REPOSITORY% environment variable is the repository where the action that launched the trigger took place. This is the same repository where I want to set the custom field.
-yAdministrator -z127.0.0.1:4900
These are the options and connection parameters. Change these to match your environment.
>>c:setfield.log
Appends any message returned by the command to this log on the C: drive.

Step 3: Create Trigger

As with custom fields, the Surround SCM User Guide has good information about creating triggers. Here is a screenshot of how I set up my trigger. Since I want this to work on all branches and repositories, I did not specify a single Pre-Condition.

Surround SCM Trigger Setup

The action may vary depending on the information that you want to show in the custom field. In the defect number example, you would choose the Attach to Defect event instead of a check in. And that is it. From now on, every time a file is checked in, the field will be populated. So do not expect the field for all files to be instantly populated.

If you want to populate the field for all the files, I have a couple of suggestions:
  1. Manually set the field. You could use the Bulk Custom Field Changes... command on the Activities menu, and have users select all the files that they just checked in and set the field for all the selected files.
  2. Use the Surround SCM API to query the history for each file in each repository to figure out the last user to check in each file. You could then pass this information to the CLI to set the fields.
If you are looking for another example, I blogged about the defect number example some time ago. It is basically the same concept.