Mirroring Defects to an external issue-tracker

In this tutorial we will set up a script that will automatically mirror defects found during a code review in Code Collaborator to an external issue-tracking system.  In this tutorial we will mirror defects to FogBugz, but the steps in this tutorial can be modified to mirror defects to any external issue-tracker.

When a Defect is created in Code Collaborator the Defect activity trigger invokes a script which creates a new "Case" in FogBugz with a link back to the review.  Then the Defect in Code Collaborator is marked "external" with a link to the mirrored Case in FogBugz.

The script in this example is written in Perl, so the server must have the Perl runtime installed.  The script invokes the Code Collaborator Command Line Client, so that needs to be installed on your server machine as well.  Be sure to install these prerequisites so that they are accessible and executable by the system user which is running the Code Collaborator server (this is especially important on Unix systems).

The script will need to know a few values to do it's work.  These will be hard-coded in to the script:

# URL to the Code Collaborator Server

$CCOLLAB_URL = "http://localhost:8080";

# Login of Code Collaborator User who will mark the Defect as external

$CCOLLAB_USER = "admin";

# Password of Code Collaborator User who will mark Defect as external

$CCOLLAB_PASSWORD = "";

# URL to the FogBugz server

$FOGBUGZ_URL = "http://bugs";

# Email of user to use to create Case in to FogBugz

$FOGBUGZ_USER_EMAIL = "person\@yourcompany.com";

# Password of user to use to create Case in to FogBugz

$FOGBUGZ_USER_PASSWORD = "yourpasswordhere";

The Review ID, Defect ID, and Defect title will be supplied by Code Collaborator as parameters when it invokes the script from the trigger (we set that up in Step 9).  The script needs to read those parameters from the command-line:

# read parameters from command-line

$reviewId = $ARGV[0];

$defectId = $ARGV[1];

$defectTitle = $ARGV[2];

The script will use the FogBugz web services API to mirror the Defect in to FogBugz.  In order to use the API we first have to "logon" and acquire an "authentication token":

# logon to FogBugz

my $response = get("$FOGBUGZ_URL/api.php?cmd=logon&email=$FOGBUGZ_USER_EMAIL&password=$FOGBUGZ_USER_PASSWORD");

# extract authentication token

$response =~ /<token>(?:<!\[CDATA\[)?([^\]]+)(?:\]\]>)?<\/token>/;

my $token = $1;

The script creates a "Case" in FogBugz, setting the title of the Case to the text from the Code Collaborator Defect, and putting a link back to the Code Collaborator server in the description of the Case.  Note that the Defect title and Case description have to be escaped because they are going in to a "get" URI.  The script extracts the resulting Case ID and saves it for later:

# create new Case

$defectTitle = uri_escape($defectTitle);

$description = uri_escape("Defect D$defectId mirrored from Code Collaborator Review $reviewId ($CCOLLAB_URL/index.jsp?page=ReviewDisplay&reviewid=$reviewId)");

$response = get("$FOGBUGZ_URL/api.php?token=$token&cmd=new&sTitle=$defectTitle&sEvent=$description");

# extract Case ID

$response =~ /ixBug="(\d+)"/;

my $case = $1;

The script logs off from FogBugz, invalidating the authentication token:

# log off from FogBugz (invalidate authentication token)

$response = get("$FOGBUGZ_URL/api.php?token=$token&cmd=logoff");

The script runs the Command Line Client ccollab admin review defect mark-external command to mark the Defect as external.  The "external-name" of the Defect is the Case number in FogBugz (which will appear as a link after Step 8):

# mark Defect as "external" in Code Collaborator

$ccollabOptions = "--url $CCOLLAB_URL";

$ccollabOptions .= " --user $CCOLLAB_USER";

$ccollabOptions .= " --password \"$CCOLLAB_PASSWORD\"";

$ccollabOptions .= " --quiet --non-interactive"; 

system("ccollab $CCOLLAB_OPTIONS admin review defect mark-external $defectId \"Case $case\""); 

That's our whole script!  Here it is in finished form: mirror-defect.pl.  Don't forget to replace the constants in the script (urls, users, passwords etc...) with the appropriate values for your environment, then copy the script to an accessible place on your server.  The script needs to be readable by the system user which is running the Code Collaborator server.

Before you configure the Code Collaborator server to invoke the script automatically, test it manually by opening a console on your server machine running it on the command-line. Be sure to log in to your server machine as the user which is running the Code Collaborator server.  First create a review and create a defect in the review, then run the script.

For example, if you created Review 1234 with Defect D5678, then run the script with this command:

C:\Perl\perl.exe "C:\Program Files\Code Collaborator Server\mirror-defect.pl" 1234 5678 "mirrored Defect title"

You should see output similar to this:

Mirrored Defect D5678 in FogBugz as Case 91011

Connecting to Code Collaborator Server http://localhost:8080

Connected as: Collaborator Administrator (admin).

D5678 marked as external

When you refresh your browser in Code Collaborator you should see the Defect has been marked as external, with the description "Case 91011".

Using the Code Collaborator built-in Bug-Tracking hyperlink function, set up the text "Case <number>" to automatically hyperlink to that Case number in FogBugz. Now if you go back to look at Defect D5678 in Code Collaborator the text "Case 91011" should be a hyperlink to Case 91011 in FogBugz.

Make sure you have Step 7 working before you move on to this step.  The last thing we need to do is tell the Code Collaborator server to automatically invoke the mirror-defect.pl script when a Defect is created.  We do this with the Defect Activity trigger.  We will use these values:

Executable: C:\Perl\perl.exe

Parameters: "C:\Program Files\merge2.2\specs\collab\Baggage\mirror-defect.pl" "$review.id" "$defect.id" "$defect.txt"

Defect Activity Trigger

Note that it is important to use the FULL PATH of both the Perl runtime and the mirror-defect.pl script.  Also note that the parameters are enclosed in quotes in case they have spaces in them.  The Review id, Defect id, and Defect text come from substitution variables.

That's it!  Now when anyone creates a Defect in Code Collaborator it will be automatically mirrored to FogBugz, and the Defect will be "marked as external" with a link to the Case in FogBugz.  Note that for performance reasons the trigger runs after the Defect is created in a separate thread, so you may have to refresh your browser a couple of seconds after creating the Defect to see it automatically externalized.