In this tutorial we will set up a script that will automatically mirror defects found during a peer review in Collaborator to an external issue-tracking system. We will mirror defects to FogBugz, but the steps in this tutorial can be modified to mirror defects to any external issue-tracker.
Outline
When a Defect is created in 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 Collaborator is marked "external" with a link to the mirrored Case in FogBugz.
Prerequisites
The script in this example is written in Perl, so the server must have the Perl runtime installed. The script invokes the 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 Collaborator server (this is especially important on Unix systems).
Script Step 1: Set Up Constants
The script will need to know a few values to do it is work. These will be hard-coded in to the script:
# URL to the Collaborator Server
$CCOLLAB_URL = "http://localhost:8080";
# Login of Collaborator User who will mark the Defect as external
$CCOLLAB_USER = "admin";
# Password of 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";
Script Step 2: Read Parameters From Command Line
The Review ID, Defect ID, and Defect title will be supplied by 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];
Script Step 3: Logon to FogBugz
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;
Script Step 4: Create Case in FogBugz
The script creates a "Case" in FogBugz, setting the title of the Case to the text from the Collaborator Defect, and putting a link back to the 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 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;
Script Step 5: Logoff from FogBugz
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");
Script Step 6: Mark Collaborator Defect as "external"
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 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\"");
This step in the script works fine if you have configured Collaborator to work with MySQL. With any other database, the process is slightly more complicated - please contact technical support for more details.
Step 7: Test Script From Command Line
That is our whole script! Here it is in finished form: mirror-defect.pl (CTRL + click, or CMD + click to open in new window). Do not forget to replace the constants in the script (urls, users, passwords and so on) 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 Collaborator server.
Before you configure the 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 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\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 Collaborator Server http://localhost:8080
Connected as: Collaborator Administrator (admin).
D5678 marked as external
When you refresh your browser in Collaborator you should see the Defect has been marked as external, with the description "Case 91011".
Step 8: Set Up Bug-Tracking Integration Link
Using the 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 Collaborator the text "Case 91011" should be a hyperlink to Case 91011 in FogBugz.
Step 9: Invoke Script From Trigger
Make sure you have Step 7 working before you move on to this step. The last thing we need to do is tell the 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.
Finished
That is it! Now when anyone creates a Defect in 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.