## Perforce Source Control Integration

How do we set up Perforce source control integration?

-

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

.1 Installing either trigger scripts or the Perforce Defect Tracking Gateway 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. If you will be using the Perforce Defect Tracking Gateway (DTG), install and enable the Perforce DTG Integration plugin.

To setup the repository in FogBugz, go to Admin | Source Control. Click Create New Repository. In the resulting dialog, select Perforce as the type and give the repository a display name. Click Next.

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 Perfoce 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 Files\Perforce).
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

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 Files\Perforce).
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

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

2. Run the setup program and follow the instructions provided.

(2) The FogBugz DTG Integration Plugin (installed in FogBugz)

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 Licensed FogBugz Users:

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

Setup for FogBugz On Demand Users:

1. In your FogBugz installation, navigate to Admin > Plugins
2. Click the link to the FogBugz Plugin Gallery
3. Find the Perforce DTG Integration and click "Install"
4. You should be redirected back to your FogBugz account, and asked to confirm if you want to install the plugin. Click "OK" to install.

(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 Files\Perforce\p4dtg)
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.

-