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

1. Installing trigger scripts so that Perforce transmits changes to Manuscript
2. Getting Manuscript to provide links to P4Web, the Perforce web client

Setting up the repository in Manuscript

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

To setup the repository in Manuscript, go to Avatar Menu > 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 Manuscript. 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 Manuscript to provide links to your check-ins. You can change this setting later by clicking the Edit icon next to the repository on the Avatar Menu > Source Control page.

Diff and log links

In order to have Manuscript 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 Manuscript

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 Manuscript. 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 Manuscript 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 Manuscript 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:pathtoyourperl.exe C:pathtoyourlogBugDataP4.pl %changelist% %serverport% %client%"
    • Perforce Version 2004.2 – you must specify the type of trigger as “commit” *:FogBugzTrigger commit //... "C:pathtoyourperl.exe C:pathtoyourlogBugDataP4.pl %changelist% %serverport% %client%"
    • Perforce Version 2005.2 – you must specify the type of trigger as “change-commit” *:FogBugzTrigger change-commit //... "C:pathtoyourperl.exe C:pathtoyourlogBugDataP4.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 Manuscript 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 Manuscript. 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. Manuscript default, the Perforce script sends changelists, not individual files (so you will see only one line in Manuscript 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 Manuscript 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:pathtoyourlogBugDataP4.vbs %changelist% %serverport% %client%"
    • Perforce Version 2004.2 – you must specify the type of trigger as “commit” *:FogBugzTrigger commit //... "cscript.exe C:pathtoyourlogBugDataP4.vbs %changelist% %serverport% %client%"
    • Perforce Version 2005.2 – you must specify the type of trigger as “change-commit” *:FogBugzTrigger change-commit //... "cscript.exe C:pathtoyourlogBugDataP4.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.

Getting Manuscript 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 – Manuscript 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 (Manuscript For Your Server)

NOTE: This applies to Manuscript For Your Server only.

To submit changes to a Manuscript 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.

 

 

NOTE:  Manuscript is built on the engine of FogBugz, and you may still see some references to FogBugz under the hood.