February 12, 2008

Enhanced Perforce Integration

Helix ALM

Works with TestTrack 2008 and later

Works with Perforce 2007.2

This article outlines how to implement a more enhanced integration with Perforce. In some previous examples, we've looked at how to trigger a defect update on P4 submit and prevent P4 submit based on defect status. Here we're going to look at a two-way integration between TestTrack Pro and Perforce that requires no special handling by a user.

[toc] You'll need:
  • The TestTrack SDK installed.
  • The path to the TestTrack SDK installation. If you're familiar with how web servers work and your IT environment, you can probably guess this. If not, ask your TestTrack administrator or IT staff for help.
  • Working Perforce client/server installation.
You'll get:
  • A working two-way integration between Perforce and TestTrack Pro.

Download

The download contains the source files and binaries for the application. Download the P4Sync zip file.
  • SyncJob.exe - Executable built with C# .Net and Visual Studio 2005. The application handles all of the necessary integration points, and provides some flexibility in how you implement those integrations.
  • Source Code - Visual Studio 2005 solution and all required source code to build the executable. You only need this if you want to make changes to the application or it doesn't work as-is in your environment.

How It Works

The basic scenario this sample uses is:
  1. Create a Perforce job, that links back to one TestTrack Pro defect.
  2. Update the linked defect when the job is "fixed". This can be done from TestTrack or Perforce, both are supported within the sample.
Here's what the Source Code tab will look like in TestTrack, with the changelist # in brackets.
To accomplish this, we're going to be modifying your P4 jobspec and adding TestTrack and (optionally) Perforce triggers. Probably not a bad idea to try this out a test server first!

Configure Perforce Jobspec

We're going to link jobs with defects, so we need to customize the Perforce jobspec to support storing a defect number. We'll use a field called DefectNum, which requires just one line added to the spec, under the Fields header.
108 DefectNum word 32 default
Be sure you know what you're doing when you configure the jobspec. Consult your Perforce admin if you're not 100% clear on how to edit the spec or what the line above does.

Configure Integration

Once you've re-configured the P4 jobspec, you're ready to get started with the integration.

Create Perforce Job

The first step is to create a job/defect link between the two systems. We'll do this with a TestTrack trigger, so TestTrack is driving the integration. You can configure the trigger in any manner you want, including using multiple triggers. The goal here is to simply create a job in Perforce that links back to the defect that fired the trigger. TestTrack triggers don't allow cmd-line parameters, so first setup a bat file with the following contents
C:JobSync.exe create
Notice that we're calling the application you just donwloaded, and we only need to send one param which is essentially a flag telling the application to create a job from the defect. Defect information is pulled from environment variables passed to the application at runtime.

Sync Job Fix with Defect

The second piece of the integration requries that we update the defect once the associated job has been "fixed" in Perforce. You can accomplish this in a couple ways, as outlined below. Feel free to use either or both of these methods, as fits your process.

TestTrack Trigger

This trigger will pull the job fix information from Perforce, and update the associated defect. Here you get a one-to-many relationship for defects-to-jobs. An example would be you want to synchronize with job fixes when the defect is marked as Fixed in TestTrack Pro. Setup your batch file.
C:JobSync.exe ttsync http://localhost/cgi-bin/ttsoapcgi.exe myuser mypwd
Notice the flag is now ttsync, so we're telling the application to do something besides create a job. Since we're running as a TestTrack trigger, we can pull most of the information from the environment variables passed to the application at runtime.

Perforce Trigger

This method will push Perforce submits to the associated TestTrack defects. Here we can support a many-to-many relationship for defects-to-jobs. We're going to create a post-commit trigger that calls our script to update TestTrack. The basic syntax here is: <trigger name> change-commit //depot/... <script> The trigger I created to test this: P4JobSync change-commit //depot/... "C:Pythonpython.exe C:JobSync.exe p4sync http://localhost/cgi-bin/ttsoapcgi.exe myuser mypwd myproj %changelist%" Now we're sending the p4sync flag and we're adding 2 additional parameters. Since we're not executing as a TestTrack trigger, you must specify the TestTrack project to update. Additionally, you need to specify the changelist that triggered execution.

Tech Details and Notes

This sample was written and tested using Perforce 2007.2 and TestTrack Studio 2008.
  • The connection to Perforce is established using cached credentials from the system. If this doesn't work in your environment, you can update the source to specify connection data manually.
  • The application uses the P4COM interface to interact with the Perforce server. The dll is included in the source, and is required to build the application (be sure to register it).
  • Application logs are written to C:P4JobSync.log, which is hard-coded into the app.