November 14, 2007

Perforce Trigger To Prevent Submit Based on TestTrack Defect Status

Helix ALM

Works with TestTrack 2008 and later

Works with Perforce 2007.2

This article outlines how to create a trigger in Perforce, which calls a script that validates defect status before allowing a Perforce submit. This was all developed and tested against TestTrack 2008 and Perforce 2007.2. 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 the TestTrack administrator or IT staff for help.
  • Perforce SCM and the necessary permissions to create triggers.
  • The path to the Perforce server.
You'll get:
  • A Perforce trigger that prevents Submit if the associated defects do not meet certain criteria.
What we'll do:
  • Review the script we're going to use to integrate with TestTrack.
  • Create a trigger to call the script.
  • Go through an example of using the new trigger.

Perforce Integration Script

The script we'll be using is written in Python. Python is good because it's easily installed and used on a variety of platforms. I'm not going to review the actual source, but it's not overly complex if you understand a little bit of Python and XML. If you need to enhance this script, I do not recommend using any of the Python SOAP libraries. I tried several of them in writing this script, and none of them worked as advertised. The common issue I ran into was lack of support for complex objects. Download Python Script The script requires five input parameters. They are listed below in the order they must be passed.
  • TT Project - Name of the TestTrack project you want to integrate to.
  • Username - Plaintext TestTrack username.
  • Password - Plaintext TestTrack password.
  • State - Defect state that should allow a submit, any other state will prevent the submit.
  • Changelist # - changelist number for the Perforce changelist to pull submit data from.
Once called, the script does the following:
  • Uses the p4 cli to fetch the referenced changelist.
  • Parses out the changelist comment.
  • Looks for the following token in the changelist comment: <ttp:defect#,{defect#>}.
  • If the token is found, parses out the defect numbers and tests that they are in the proper state.
For example, if you commit a changelist with <ttp:56,1065> somewhere in the comment, this script will test that defects 56 and 1065 are in the proper state for a submit. Other items of interest:
  • The path to the TestTrack SDK cgi is hard coded in the script, around line 20 or so.
  • The path to the Perforce server is hard coded in the script, at line 56.
  • You can call the script from a command prompt to get basic help on using it.

Create Perforce Trigger

Now that we understand how to call the script, we can create a trigger in Perforce.
  1. Open a command-prompt
  2. type p4 triggers
  3. Notepad or another text editor should open. If not, you'll need to read the Perforce documentation to figure out how to create a trigger on your version of Perforce.
We're going to create a pre-commit trigger that calls the script to update TestTrack. The basic syntax here is: <trigger name> change-content //depot/... <script> The trigger I created to test this: SeapineTTP4 change-commit //depot/... "C:Pythonpython.exe C:seapinettp4-commitvalidation.py p4 p4 p4 Open %changelist%" During a commit, but prior to the database save, the script should be called. We're connecting to a project named "p4", as user "p4", with password "p4". All associated defects must be in the "Open" state, or the submit will fail. %changelist% is simply a variable that Perforce will replace with the actual changelist number, on every fire of the trigger.

Using the Trigger

Now we can actually use the trigger!
  1. Edit a file in Perforce.
  2. Right-click on the file's changelist and select commit.
  3. Enter <ttp:1> This is my first attempt at using the trigger that will integrate to P4!! as the changelist comment.
  4. Commit the changelist
If defect 1 has a state of Open, then the submit should proceed successfuly. If defect 1 is not in the Open state, then the submit will fail with an error message. Note: Seapine does not provide support for sample triggers.