November 18, 2009

Integrated CM Toolbox

Surround SCM

Works with Surround SCM 2010 and later

Will not work with Surround SCM 2009 and earlier

A few months back, I posted a tool called CM Toolbox, which allowed you to see the current status of defects that had files attached from Surround SCM. The criteria used for showing defects was the branch selected from a dropdown, which was then used to search each defect's source code list and see if any belonged to that branch. If a match was found, the defect was added to the list. Integrated CM toolbox gives you basically the same thing, although with a different approach. Using the Surround SCM API and the plug in architecture, this tool queries all Attach to Defect events for all files in the selected branch in the Surround SCM client. It parses the comments from all of these events and builds a defect list. For each defect, it connects to TestTrack using the SOAP SDK to get the current status of each defect. [toc] This version uses Surround SCM history as "source of truth" whereas the old version used TestTrack. Also, this version can handle multiple TestTrack projects, the older version only supports one.

CM Toolbox Interface

Requirements

Integrated CM Toolbox uses both the TestTrack SOAP SDK and the Surround SCM API. It is designed to work using Surround SCM's plug in architecture. A user account is needed that has access to connect TestTrack via the SOAP SDK and Surround SCM using the API.

Configuration

Access from Surround SCM client

Please refer to the Surround SCM Custom Client Menus article for help on creating a custom menu option to access CM Toolbox. The tool is meant to be used as a plugin and will not work otherwise. While the tool maybe accessed from anywhere, remember that it queries history based on the selected repository, so it makes sense that it should be accessed from the repository context menu.

Configuration File

The tool uses a configuration file to determine the location of the SOAP SDK and the user account to use to connect to both TestTrack and Surround SCM. The configuration file is called "CMConfig.xml". This file must reside on the same directory as the Rollback Changelist.exe file. A sample file is provided with the Download. The file must have the following information:
  • UserName - User name to connect to Surround SCM and TestTrack Pro
  • Password - Password for the above user
  • TTServerAddress - URL to the TestTrack SOAP SDK
  • SCMServerAddress - Surround SCM IP address or host name
  • SCMServerPort - Port of the above server
The file must have the following structure:
<CMData>
	<UserName></UserName>
	<Password></Password>
	<TTServerAddress></TTServerAddress>
	<SCMServerAddress></SCMServerAddress>
        <SCMServerPort></SCMServerPort>
</CMData>

App Flow

When the tool launches, it gathers the name of the current branch, repository and mainline from the environment variables made available by the Surround SCM plugin architecture. The tool then uses the Surround SCM API and retrieves all AttachToDefect events from all files in the current repository recursively. As it parses each event, it parses the comments to extract the defect id and project name. As it extracts this information it builds a list of defects and the file associated to that defect. Once the list has been compiled, it connects to TestTrack. For each project, it gets the entire defect list that includes the defect record id, number, summary and status. Those defects whose record id matches the ones on the list that it build when querying Surround SCM are added to the list. The tool actually builds two tables. One is a "filtered" version of the defect list, only containing the defects that where associated in Surround SCM. The other table contains the Surround SCM file name, the timestamp of the event (in GMT) the version associated with the defect and the defect's record id. When the form loads, it loads the defect list and selects the first defect. When a defect is selected, it populates the file list by matching record ids. NOTE: The number column in the defect list will display the current defect number, not the one when the Surround SCM file was attached to the defect. The defect might have been renumbered since. Also, if the tool is unable to connect to the TestTrack project, it will display the record id of the defect instead.

Download

You can download the full Visual Studio 2008 project from here. The zip file contains a bin directory where you will find a compiled debug version of the tool. Under the graphics folder you will find the icon used in the windows form and its PNG equivalent to use in the context menu configuration.

Limitations/Known Issues

The following are things noticed during development and testing. Some of this could be addressed, which is one reason the source code is provided.

Performance

When you launch CM Toolbox, it may take a few seconds for the application to launch. Remember that it has to go through all attach to defect events for all files in a repository and then has to get the entire defect list for each project and find matches. Avoid launching CM Toolbox from a root repository, as this means that the tool will have to query historical events for every file in the current branch.

Possible Improvements

  • If you have very large defect list and only a few defects have been associated to Surround SCM, it may be faster to get only the defects. Getting each defect however, means you are pulling a lot more data per defect, so at some point this will be slower than the current approach.
  • If you are storing TestTrack in an RDBMS system, you may want to query the database directly.

All timestamps are in GMT

The Surround SCM API handles timestamps in GTM. This tool does not make any attempt to translate this to your local time.

Error Logging

Most errors are displayed to the user in message boxes. All errors are written to a file called "error.log". The file Note: Seapine does not provide support for sample scripts.