October 26, 2010
Display the Information You Need with Surround SCM Custom Fields and Triggers
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 FieldThe 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.
Step 2: Create the Batch FileThe 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.logLet's break this down.
sscm setcustomfieldThis 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.
1003This 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:4900These are the options and connection parameters. Change these to match your environment.
>>c:setfield.logAppends any message returned by the command to this log on the C: drive.
Step 3: Create TriggerAs 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.
- 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.
- 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.