Ignite Global Support Home
How can we help?
  1. FogBugz Support
  2. Fogbugz
  3. FogBugz On-Demand
  4. Source Control

Integration with Perforce


Luis Fernandes
  • Updated
Follow
 

There are two aspects to setting up FogBugz-Perforce integration:

1. Installing either trigger scripts (FogBugz On Demand, FogBugz On Site) or the Perforce Defect Tracking Gateway (FogBugz For Your Server) so that Perforce transmits changes to FogBugz
2. Getting FogBugz to provide links to P4Web, the Perforce web client

Setting up the repository in FogBugz

The starting point for setting up source control integration is to create the repository in FogBugz. Start by logging into FogBugz as an administrator.

NOTE: If you are using FogBugz For Your Server and you are using the Perforce Defect Tracking Gateway (DTG), install and enable the Perforce DTG Integration plugin.

To setup the repository in FogBugz, go to Admin (or Gear icon) -> Source Control. Click Create New Repository. In the resulting dialog, select Perforce as the type and give the repository a display name. Click Next.

alt text

The resulting dialog contains a script for getting Perforce to transmit changes to FogBugz. Select the appropriate tab for the server Perforce runs on to use triggers, or DTG for the Perforce Defect Tracking Gateway (DTG). Download the script and follow the instructions below to set it up. Before you close the dialog, choose whether you want FogBugz to provide links to your check-ins. You can change this setting later by clicking the Edit icon next to the repository on the Admin -> Source Control page.

Diff and log links

In order to have FogBugz link to checked-in files directly from cases, you need to have P4Web installed. Once it is installed and working with your Perforce repository, set the path to it in the New Repository dialog and click OK to complete the setup.

Getting Perforce to transmit changes to FogBugz

We provide trigger scripts for Perforce in Perl or VBScript, depending on whether your Perforce server is running on Unix, where Perl is probably installed, or Windows, where VBScript is probably installed.

Instructions for Perl

Download and customize the trigger Perl script.

  1. Follow the instructions above to setup the Perforce repository in FogBugz. Download the logBugDataP4.pl script.
  2. Put it in the directory that contains your Perforce server executable (for example, c:Program FilesPerforce).
  3. Edit the file. Look for the variables $P4USERNAME and $P4PASSWORD and set them to the Perforce username and password you want to use.
    Perforce passwords cannot be accessed from trigger scripts, so the good folks at Perforce will give you a free “background” or “automation” user for this purpose. Please contact them at support@perforce.com to pursue this option. If you do NOT have Perforce passwords enabled, leave $P4PASSWORD blank.
  4. By default, the Perforce script sends changelists, not individual files (so you will see only one line in FogBugz for a changelist containing 40 files, instead of 40 lines). If you want to change this, look for the variable $CHANGELIST_ONLY and set it to 0.

Perforce will let you call an executable every time files are submitted (actually, just before the submission occurs). This is called a trigger. We want to use a trigger to call the logBugDataP4.pl file every time any files are submitted in Perforce. To do this, do the following:

  1. Type p4 triggers on the command line (or cmd window). A text file appears in your editor. (If it doesn’t, make sure the full path to p4 is in your path.)
  2. To add the FogBugz trigger you need to add a line to at the bottom of this file. The trigger looks slightly different depending on what version of Perforce you use:
    • Perforce Version 2003.2 – all triggers are of type “submit”, no need to specify type: FogBugzTrigger //... "C:\path\to\your\perl.exe C:\path\to\your\logBugDataP4.pl %changelist% %serverport% %client%"
    • Perforce Version 2004.2 – you must specify the type of trigger as “commit” *: FogBugzTrigger commit //... "C:\path\to\your\perl.exe C:\path\to\your\logBugDataP4.pl %changelist% %serverport% %client%"
    • Perforce Version 2005.2 – you must specify the type of trigger as “change-commit” *: FogBugzTrigger change-commit //... "C:\path\to\your\perl.exe C:\path\to\your\logBugDataP4.pl %changelist% %serverport% %client%"
    • Note that this new line has a tab at the beginning. Adjust the path to the Perl interpreter and the path to the logBugDataP4.pl file to make sure it points to logBugDataP4.pl on your server (wherever you put it). IMPORTANT: The paths in the trigger cannot contain any spaces. A path with spaces in it will generate an error like the following: Input Error: There is no file extension in "C:Program".
  3. Save this temporary file and exit the editor. The trigger is now added.

* Use “commit” or “change-commit” instead of “submit” or “change-submit” to make sure that the changelist number that is sent is the correct one. If you use “submit” and you have used a temporary changelist number, then someone else commits, you won’t send the updated number.

If you don’t see the checkin entries in the FogBugz case, here is some troubleshooting help:

Instructions for VBScript

Download and customize the trigger VBScript.

  1. Follow the instructions above to setup the Perforce repository in FogBugz. Download the logBugDataP4.vbs script.
  2. Put it in the directory that contains your Perforce server executable (for example, c:Program FilesPerforce).
  3. Edit the file. Look for the variables P4USERNAME and P4PASSWORD and set them to the Perforce username and password you want to use. Perforce passwords cannot be accessed from trigger scripts, so the good folks at Perforce will give you a free “background” or “automation” user for this purpose. Please contact them at support@perforce.com to pursue this option. If you do NOT have Perforce passwords enabled, leave P4PASSWORD blank.
  4. By default, the Perforce script sends changelists, not individual files (so you will see only one line in FogBugz for a changelist containing 40 files, instead of 40 lines). If you want to change this, look for the variable CHANGELIST_ONLY and set it to 0.

Perforce will let you call an executable every time files are submitted (actually, just before the submission occurs). This is called a trigger. We want to use a trigger to call the logBugDataP4.vbs file every time any files are submitted in Perforce. To do this, do the following:

  1. Type p4 triggers on the command line (cmd window). A text file appears in your editor. (If it doesn’t, make sure the full path to p4 is in your path.)
  2. To add the FogBugz trigger you need to add a line to at the bottom of this file. The trigger looks slightly different depending on what version of Perforce you use:
    • Perforce Version 2003.2 – all triggers are of type “submit”, no need to specify type: FogBugzTrigger //... "cscript.exe C:\path\to\your\logBugDataP4.vbs %changelist% %serverport% %client%"
    • Perforce Version 2004.2 – you must specify the type of trigger as “commit” *: FogBugzTrigger commit //... "cscript.exe C:\path\to\your\logBugDataP4.vbs %changelist% %serverport% %client%"
    • Perforce Version 2005.2 – you must specify the type of trigger as “change-commit” *: FogBugzTrigger change-commit //... "cscript.exe C:\path\to\your\logBugDataP4.vbs %changelist% %serverport% %client%"
    • Note that this new line has a tab at the beginning. Adjust the path to the logBugDataP4.vbs file to make sure it points to logBugDataP4.vbs on your server (wherever you put it). IMPORTANT: The paths in the trigger cannot contain any spaces. A path with spaces in it will generate an error like the following: Input Error: There is no file extension in "C:Program".
  3. Save this temporary file and exit the editor. The trigger is now added.

* Use “commit” or “change-commit” instead of “submit” or “change-submit” to make sure that the changelist number that is sent is the correct one. If you use “submit” and you have used a temporary changelist number, then someone else commits, you won’t send the updated number.

Instruction for Perforce DTG Integration (FogBugz For Your Server)

NOTE: Applies to FogBugz For Your Server only.

NOTE: We do not currently offer a 64-bit version of the DTG Integration Plugin. You should be able to use the 32-bit plugin on 64-bit machines, but make sure you use the 32-bit version of the DTG from Perforce. The 32-bit plugin will not work with the 64-bit DTG.

If you have a Windows server which can access your Perforce server, you can use the Perforce Defect Tracking Gateway (DTG) instead of setting up trigger scripts. If you do this, FogBugz cases will appear in Perforce as Perforce Jobs and you can apply changelists to them directly.

There are three essential components for setting up the DTG integration:

(1) The Perforce Defect Tracking Gateway (DTG) (installed on your server)

The Perforce DTG, created and supported by Perforce, provides a service that does the following:

  • Periodically query any configured defect tracking systems for case information, and then update or create an associated job in Perforce.
  • Periodically query Perforce for any new changesets, and send the information to the associated defect tracking system.

Note that by default, the Perforce DTG does not have any FogBugz integration.

Setup

  1. Download the DTG Setup program from the Perforce downloads page.
  2. Run the setup program and follow the instructions provided.

(2) The FogBugz DTG Integration Plugin (installed in FogBugz For Your Server)

DTG integration in FogBugz requires that the FogBugz plugin be installed. The plugin configures FogBugz to accept changesets from the Perforce DTG, and allows downloading the FogBugz – Perforce DTG link for step 3.

Setup for FogBugz For Your Server:

  1. Download the Perforce DTG Integration plugin .zip file from the FogBugz Plugin Gallery.
  2. In your FogBugz installation, navigate to Admin > Plugins
  3. Click “Upload Plugin”, and select the .zip file

(3) The FogBugz-P4DTG Link (installed on your server)

By default, the DTG does not have FogBugz support installed. To add FogBugz support, and configure the DTG to communicate with FogBugz, you must install the FogBugz-P4DTG Link.

Setup:

  1. Create a new Perforce repository
    1. In your FogBugz account, navigate to Admin > Source Control
    2. Click “Create New Repository”
    3. Select “Perforce” and select a name for the repository
    4. Click OK
  2. Install the FogBugz-P4DTG Link
    1. Click the edit link on the Perforce Repository
    2. Select the DTG tab
    3. Click the link to the Perforce DTG Integration Setup (Enter your Perforce server, user, and password, and FogBugz user and password; Select the fields you wish to copy to Perforce; Click OK)
    4. Download and run the setup program
    5. When prompted, enter the location of the Perforce DTG installed previously (typically C:Program FilesPerforcep4dtg)
    6. After installation is done, you’ll need to update your Perforce jobspec and configure the plugin (If you’re already logged in as a Perforce administrator, the setup program will launch the jobspec editor automatically. If not, you’ll need to log in as a Perforce administrator and enter p4 jobspec on the command line (cmd window), or type p4 jobspec -u [admin user name] -P [admin password]; Copy the lines given by the setup page in FogBugz into your jobspec; Save and close the window)
    7. Setup should automatically open the configuration editor. You can also find this program in [Your Perforce DTG install]p4dtg-config.exe.
    8. Check that each tab indicates that the configuration is correct, as described in the setup page
    9. On the final tab, click “Start Replication” to start the replication engine

Getting FogBugz to provide links to P4Web, the Perforce web client

In order to browse a Perforce repository, you need something that allows you to view file diffs and history logs from a web browser. With Perforce, you use P4Web, the Perforce Web Client.

Entering case numbers in Perforce

How you enter the case depends on how you’ve set up your Perforce – FogBugz integration.

Using Perforce Trigger Script

When you commit a change using Perforce, include a single line of the form BugzID: case number in the change specification after the other comments. For example:

alt text

Using Perforce DTG integration (FogBugz For Your Server)

NOTE: This applies to FogBugz For Your Server only.

To submit changes to a FogBugz case, simply apply a job fix to the changelist for the corresponding job.

You can do this from the command line by typing (where job000021 is the job that corresponds to your case)

p4 fix -c 324 job000021

Or from one of Perforce’s graphical tools by finding the option to add a job fix to a changelist and simply selecting the job(s) from a list:

alt text

Note that you’ll probably want to Filter the results to find the case that you want. Here are some useful filters for finding your cases:

  • Search for all cases with the word “Perforce” in them by filtering on: Perforce
  • Search for all cases assigned to you by filtering on: FB_Assigned_To=[Your Name]
  • Search for all active (not resolved or closed) cases assigned to you by filtering on: FB_Status=Active FB_Assigned_To=[Your Name]
  • Search for all active cases assigned to you with the word “Perforce” in them by filtering on: FB_Status=Active FB_Assigned_To=[Your Name] Perforce

You can use these filters from the command line or from the graphical tools.