Set Custom Field To Defect Number

From Seapine Labs

The following article illustrates how to use the TestTrack Integration, along with custom fields and triggers, and be able to easily identify the defect number that files are attached to.

Surround SCM already provides ways to filter and use the defect number that a file is attached to. This article simply extends this functionality to display the defect number in the source file list pane in the Surround SCM client.

This is for display purposes only.

Contents 1 Requirements 2 Custom Fields 2.1 Setting Up the Custom Field 2.2 Displaying the Custom Field in the Source File List Pane 3 The Script File 3.1 Creating the Script File 4 The Trigger 4.1 Creating the Trigger 5 What it Looks Like

[edit] Requirements

The only requirement for this is that Surround SCM is set up to integrate with TestTrack Pro. Also, custom fields were introduced in version 5 of Surround SCM, so you must have at least version 5.0 installed.

[edit] Custom Fields

First, we must create a custom field that we will use to display the defect number. The main advantage of this is that now we can take advantage of the functionality of custom fields, like displaying them in the file pane, restrict when another trigger may be fired, etc.

The Surround SCM User Guide includes more information about custom fields.

[edit] Setting Up the Custom Field

To create a custom field in Surround SCM choose Tools > Administration > "Custom Fields.

Click the Add button in the Custom Fields dialog box.

Create a custom field similar to the one shown in Figure 3. Note that your fields does not have to match exactly what is shown below.

A brief description of each field:

• Field name: Should be something meaningful. Use something to match the terminology already in use in your environment.

• Field code: Should be unique and resemble the field name for easy identification. This field code can be used as an environment variable in scripts or email templates.

• Field format: Select the type of custom field. I chose it to be an integer for sorting reasons. Making it a string may not result in the desired sorting.

• Field Properties: I have left this blank.

[edit] Displaying the Custom Field in the Source File List Pane

To display any custom field in the Source File List pane, place your mouse cursor over any of the columns, right click, select Custom Fields><Name of your custom Field> as shown in Figure 4:

By default, the column will be place on the far right and be the last column. You can then click on that column and drag it, if you want to move it.

I moved mine to be fifth column, right after the status column.

Note that the fields are empty for the files displayed. This is because we haven't set up or run the trigger yet.

[edit] The Script File

The next step is to create the script. Create the script before creating the trigger, because you will have to reference the script in the trigger. How can you reference something that does not exist yet?

For this example I am in a windows environment and will be using batch files.

[edit] Creating the Script File

Following is the syntax for the SetCustomField CLI command:

sscm setcustomfield FileName FieldID Value [-bBranch] [-pRepository] [-h] [-y[Username:Password|+]] [-zSCMServerAddr:PortNum] [+u]

For more details on this command please refer to the Surround SCM CLI guide or type "sscm scf -h" on your terminal window/DOS prompt.

By the way, you get the custom field ID by using the "lscustomfield" command. Again, please refer to the Surround SCM CLI guide or type "sscm lscustomfield -h" on your terminal window/DOS prompt for more information.

All the script really needs is something like this:

sscm scf "%SSCM_FILE%" 1007 %SSCM_DEFECTNUMBER% -b"%SSCM_BRANCH%" -p"%SSCM_REPOSITORY%" -yAdministrator: -z127.0.0.1:4900

Acutally, you should just be able to use this same line, except for the custom field ID, unless your "Administrator" user does have a password set. The recommended approach is to pass a different <username>:<password>. You really don't want the Administrator password in clear text in some text file on the server, do you? However, the script file has to be stored on the server, so you could also limit who can access that folder for security reasons (if you go with this approach, make sure that the account that the Surround SCM Server is running under can access it).

My batch file has a bit more than the above, but for troubleshooting and error logging. This is what my batch file looks like:

echo sscm scf %SSCM_FILE% 1007 %SSCM_DEFECTNUMBER% -b"%SSCM_BRANCH%" -p"%SSCM_REPOSITORY%" -yAdministrator: -z127.0.0.1:4900 >D:\test.log

sscm scf "%SSCM_FILE%" 1007 %SSCM_DEFECTNUMBER% -b"%SSCM_BRANCH%" -p"%SSCM_REPOSITORY%" -yAdministrator: -z127.0.0.1:4900 >>D:\test.log

I echo the command first, this way I can see how the variables are being expanded. I can make sure that the command being passed is correct. Second, I pipe (append) the actual command output to make sure that it ran correctly. If the command runs successfully there will be no output by the command. So no news is good news!

[edit] The Trigger

Now we are ready to create the trigger. We will use the "Attach to defect" event to fire the script file.

[edit] Creating the Trigger

To create triggers, select "Tools" > "Administration" > "Triggers...".

This opens the Triggers window. Click on the "Add..." button. Please review the Surround SCM User Guide for details on how to create triggers.

Here is the summary for the trigger I created:

Trigger applies to files in branch [WysiCorp Products] and in repository [WysiCorp Products/WysiCalc] [recursively] -- after an event on a [Attach to defect] -- Run script located at "D:\batch\setcustomfiel.bat"

This trigger will run on my branch called "WysiCorp" and for any file under the "WysiCorp Products" repository or any of its sub-repositories.

I saved my batch file on the D:\batch folder on the same machine where I have the Surround SCM server running.

[edit] What it Looks Like

So now I checked out all three files separtely shown above in figure 5. I made changes to each file and on check-in, I attached each file to a separate defect.

This is what it looks like: