Perforce Defect Tracking Integration Administrator's Guide

Contents

• 1. Introduction
• 2. Overview of the P4DTI
  • 2.1. Installation, configuration, and maintenance
  • 2.2. How the P4DTI works
• 3. Prerequisites for installing the P4DTI
  • 3.1. Required experience
  • 3.2. Perforce prerequisites
  • 3.3. TeamTrack prerequisites
  • 3.4. Bugzilla prerequisites
• 4. Installing the P4DTI
  • 4.1. Upgrading from an earlier version
  • 4.2. Windows installation
  • 4.3. Linux installation
  • 4.4. Solaris installation
• 5. Configuring the P4DTI, Perforce, and the defect tracker
  • 5.1. P4DTI configuration
  • 5.2. Perforce configuration
  • 5.3. TeamTrack configuration
  • 5.4. Bugzilla configuration
  • 5.5. Starting and stopping the replicator manually
  • 5.6. Setting up the replicator to start automatically
  • 5.7. Refreshing jobs in Perforce
• 6. Migrating your defect tracking data to the integrated system
• 7. Testing the P4DTI
  • 7.1. Testing your configuration
  • 7.2. Checking data consistency
• 8. Training and documentation
• 9. Maintaining the P4DTI
• 10. Uninstalling the P4DTI
• 11. Troubleshooting and error messages
  • 11.1. Troubleshooting
  • 11.2. Error messages
• Section A. References
• Section B. Document history
• Glossary

1. Introduction

This manual is the Perforce Defect Tracking Integration 1.0 Administrator's Guide. It explains how to install, configure, maintain, and administer the Perforce Defect Tracking Integration (P4DTI).

This document is intended for P4DTI administrators. Ordinary users of the defect tracker or Perforce should read the Perforce Defect Tracking Integration User's Guide. (For ideas on how to train your users on the P4DTI, see Section 8, "Training and documentation".)

This guide does not describe the basics of using the P4DTI, Perforce, or the defect tracker. Read the Perforce Defect Tracking Integration User's Guide to understand the P4DTI from a user's perspective.

2. Overview of the P4DTI

2.1. Installation, configuration, and maintenance

To install and run the P4DTI, you must:

1. Get and install the required software (Section 3).
2. Ensure you have met the procedural prerequisites for Perforce and your defect tracker (Section 3).
3. Download and install the P4DTI software (Section 4).
4. Configure the P4DTI software (Section 5).
5. Migrate defect tracking data from your defect tracker to the integrated system (Section 6).
6. Test the installation (Section 7).
7. Train the users (Section 8).
8. Go live (Section 9).
9. Maintain the installation (Section 9).

2.2. How the P4DTI works

The P4DTI works by taking over the job tracking system of Perforce and making the defect tracker's records appear as Perforce jobs. Perforce users can work with jobs more or less as described in the Perforce manuals, and their changes are reflected in the defect tracker. For more information on how Perforce handles jobs, see the Perforce Command Line User's Guide.

Perforce has a mechanism for linking jobs to changelists, to enable you to record the work done for a particular reason. The P4DTI makes these links appear in the defect tracker, making it easy to see what was done or is currently being done to resolve a defect.

The P4DTI replicator is a process that copies data between a defect tracker and a Perforce server to keep each one up to date with changes made in the other. This approach allows developers to do their routine defect resolution work entirely from their Perforce client, without using the defect tracker's interface. It also allows developers to relate their changes to defect tracking issues.

Figure 1 shows how the replicator communicates with the defect tracking server and the Perforce server.

The replicator maintains a one-to-one relationship between issues in the defect tracker's database and jobs in the Perforce repository. (An issue is a unit of work that the defect tracker tracks; some examples are bugs, change requests, and enhancement requests.) In other words, each issue has a corresponding job, and vice versa. The replicator keeps the contents of a configurable set of fields in the defect tracker's issues the same as the contents of the corresponding Perforce job, so that editing one edits the other.

The replicator also copies Perforce's links between jobs and changelists (called "fixes") to the defect tracker's database, and makes them visible in the defect tracker's user interface. Replication of links from Perforce to the defect tracker makes it possible to track, record, and check a number of things; in particular, it makes it possible to track and record the changes made for each issue, and find out why a change was made in terms of issues.

The replicator polls the defect tracking server and the Perforce server at regular intervals to get a list of recent changes, and attempts to propagate these changes to the other system. If a defect tracker issue is changed at the same time as the corresponding Perforce job, the replicator sends an email with the overwritten Perforce job data to the following people:

• The person who changed the job in Perforce.
• The owner of the defect tracker issue.
• The P4DTI administrator.

Most defect trackers have an idea of workflow--a set of rules that control who can do what to which issues. The replicator enforces the defect tracker's workflow by rejecting changes to jobs in Perforce that are illegal in the defect tracker. When it comes across such a change, it undoes the change and sends an e-mail message to the user.

The defect tracker manages the defect tracker records (and therefore the job contents), while Perforce manages the changelists. Neither side controls the "fixes" relationship--the links between jobs and changelists.

Figure 1 shows how the replicator connects to the Perforce and defect tracker servers.

Figure 1. The replication architecture

3. Prerequisites for installing the P4DTI

3.1. Required experience

To administer the P4DTI, you must have the following experience:

• Perforce: You need at least two months of Perforce administration experience, including a working knowledge of Perforce's command line interface. Read both the Perforce Command Line User's Guide and the Perforce System Administrator's Guide.
• The Python programming language: You need to know how to use Python to assign values to variables, but you do not need to be an expert Python programmer. To acquire a basic familiarity with Python, read the Python tutorial at <http://www.python.org/doc/current/tut/tut.html>.
• The defect tracker: You must understand how to administer the defect tracker and how it is configured at your organization, or have someone with that knowledge on hand when installing, configuring, and testing the P4DTI.

3.2. Perforce prerequisites

3.2.1. Software prerequisites

Before installing the P4DTI, you must obtain and install the following software:

• Perforce server software of version 2000.2 or later. You can download server and client upgrades from the Perforce FTP server at <ftp://ftp.perforce.com/pub/perforce/>. Be sure to read the release notes (available from <http://www.perforce.com/>) before you install. Contact Perforce technical support if you need help.
• Perforce client software of version 2000.2 or later for every P4DTI user who will be running Perforce.
• Perforce licenses for every defect tracker user who is going to work in Perforce.
• A daemon license for the replicator. A daemon license is a license for an automatic process, rather than a person. Perforce provides daemon licenses free of charge; contact Perforce technical support to get one.

3.2.2. Procedural prerequisites

Before installing the P4DTI, you must do the following:

1. Back up your Perforce repository. For instructions, see the Perforce System Administrator's Guide.
2. Copy out of Perforce any jobs that you want to keep. The P4DTI takes over the jobs subsystem of Perforce and rewrites the Perforce jobspec, and you must delete all jobs from your Perforce repository as part of configuring the P4DTI. For more information, see Section 5.2.3, "Deleting Perforce jobs". You might want to enter any active jobs into the defect tracking system.
3. Determine the address and port number of your Perforce server. You will need this information when you configure the P4DTI in Section 5.

4. Installing the P4DTI

Note: You might want to practice installing and configuring the P4DTI using a test Perforce repository and a test defect tracking database before you try it with your real data. A copy of your real Perforce repository would be ideal; for instructions on how to make a copy of your repository, see the Perforce System Administrator's Guide.

The P4DTI can be installed on any machine that can communicate with the defect tracker's server and the Perforce server. To keep administration simple and reduce network traffic, install and run the P4DTI on the same machine as the defect tracker's server. The rest of this manual assumes that you do this.

4.1. Upgrading from an earlier version

For instructions on how to upgrade from an earlier version of the P4DTI, see the release notes.

4.2. Windows installation

The P4DTI is distributed as a self-extracting executable called p4dti-DT-RELEASE.exe (where DT is the defect tracker, such as "teamtrack", and RELEASE is the release number, such as "1.0.2").

To install the P4DTI, run this executable on the machine where the defect tracker server is installed. The installer unpacks the P4DTI into C:\Program Files\P4DTI\ by default.

4.3. Linux installation

The P4DTI is distributed as a gzipped tar file called p4dti-DT-RELEASE.tar.gz (where DT is the defect tracker, such as "bugzilla", and RELEASE is the release number, such as "1.0.2").

To install the P4DTI, unpack this tar file on the defect tracker server machine, using the following command:

zcat p4dti-DT-RELEASE.tar.gz | tar xvf -

A Linux RPM is not available for this release, so you must determine where to put the files. You can put the files wherever you want.

4.4. Solaris installation

[Section not written yet.]

5. Configuring the P4DTI, Perforce, and the defect tracker

Work through the subsections in the order in which they appear. Do not attempt to run the P4DTI until you have reached the end of this section, or you might end up with a non-working installation.

To configure the P4DTI with Perforce and your defect tracker, you must:

1. Specify the location of servers and the data you want to appear in Perforce (Section 5.1).
2. Configure Perforce to accept information from the replicator and, optionally, install triggers to implement access controls (Section 5.2).
3. Enable P4DTI features, such as the ability to view or edit fixes and changelists from the defect tracker user interface (Section 5.3 for TeamTrack or Section 5.4 for Bugzilla).
4. Start the replicator (Section 5.5).
5. Set up the replicator to start automatically when the server machine is rebooted (Section 5.6).
6. Optionally, create jobs in Perforce (Section 5.7).

5.1. P4DTI configuration

To configure the P4DTI, you edit definitions of Python variables in the file config.py in the installation directory. Edit these definitions according to the notes in the following table. All variables in the file must have a value.

Table 1. Configuration variables in the config.py file

5.1.1. Choosing which fields to replicate

Here's some advice on which fields to replicate:

• Replicate any fields that the developers are required to fill in, or they won't be able to use Perforce to do their work.
• Replicate any other fields that the developers need to do their work; see the suggestions below.
• Don't replicate other fields--the less information developers need to enter, the better the quality of that information. Keeping the number of replicated fields low might mean modifying your workflows so that unnecessary fields can be omitted. For example, you might have a FIX_DESCRIPTION field for developers to explain what they did. Now that you're running the P4DTI, you don't need that field--you can look in the change comments of the associated changelists to find out what the developer did--so leave it out.

If you need to change the list of replicated fields after you've started using the P4DTI, see Section 9, "Maintaining the P4DTI".

5.2. Perforce configuration

To configure Perforce, you must:

• Create a Perforce user for the replicator (Section 5.2.1).
• Install Perforce triggers to enforce workflow (optional; Section 5.2.2).
• Delete all Perforce jobs, if you have not already done so (Section 5.2.3).

5.2.1. Creating a Perforce user for the replicator

Create a user in Perforce for the replicator; for instructions, see the Perforce System Administrator's Guide. The replicator user must have the following properties:

• The userid must be the same as the replicator Perforce userid (p4_user) that you specified in the P4DTI configuration.
• The e-mail address must match the replicator e-mail address (replicator_address).

• If you're using the Perforce protections, make the replicator a super user so that it can set the jobspec. For instructions, see the Perforce System Administrator's Guide. You'll need to add a line like

  super user p4dti-replicator0 * //...

  to the protections list.

For information on getting a license from Perforce Software for this extra user, see Section 3.2, "Perforce prerequisites".

5.2.2. Installing Perforce triggers to enforce workflow

You can use the P4DTI in combination with a Perforce trigger to enforce extra workflow restrictions. For example, if your organization assigns priorities to issues, you can prevent changes being made to areas of the repository unless they resolve at least one defect of priority 3 or higher.

The P4DTI comes with an example trigger script that you can adapt for your needs, installed as example_trigger.py in the default installation directory.

To enforce workflow restrictions, follow these steps:

1. Configure the P4DTI to replicate the defect tracker fields that you want to check. For example, you can check that, say, the "priority" or "severity" is above a certain level, or that a manager has set the "approval" field. See the list of replicated fields (replicated_fields) configuration parameter.
2. Adapt the trigger script for your needs. You must be able to do a small amount of Python programming to adapt the trigger script. The example script contains comments to help you.
3. Install the trigger script. For instructions on installing and managing trigger scripts, see the Perforce System Administrator's Guide.

5.2.3. Deleting Perforce jobs

You must delete all jobs from your Perforce installation. The P4DTI takes over the jobs subsystem of Perforce and rewrites the Perforce jobspec.

For instructions, see the Perforce Command Line User's Guide.

If you already use Perforce jobs and have significant tools that depend on your jobspec, the configuration options described in Section 5.1, "P4DTI configuration", might not be flexible enough to support your requirements. However, you might be able to write your own configuration and use your own jobspec. To write your own configuration, you must understand the P4DTI configuration architecture and be fluent in the Python programming language. See the Perforce Defect Tracking Integration Integrator's Guide for details of how to configure the P4DTI and guidance on developing your own configuration. Note that neither Perforce nor the manufacturer of your defect tracker can support a configuration that you write yourself.

5.3. TeamTrack configuration

To configure TeamTrack, you must:

• Update the Windows Registry (Section 5.3.1).
• Create a TeamTrack user for the replicator (Section 5.3.2).
• Provide field descriptions (Section 5.3.3).

5.3.1. Updating the Windows Registry

You need to add a TeamTrack value to the Windows Registry to tell TeamTrack that the P4DTI is present. To edit your Registry, follow these steps:

1. Run the Registry editor, regedit.
2. Select the key HKEY_LOCAL_MACHINE\Software\TeamShare\TeamTrack.
3. Choose Edit > New > String Value and create a value with the name VC Integration.
4. Choose Edit > Modify and enter "perforce".

Figure 2 shows the correct entry.

Figure 2. Registry keys for TeamTrack with the P4DTI

5.3.2. Creating a TeamTrack user for the replicator

You need to create a TeamTrack user for the replicator. This user corresponds to the replicator TeamTrack userid (teamtrack_user) parameter you set in Section 5.1, "P4DTI configuration".

To create a TeamTrack user for the replicator, follow these steps:

1. Run the TeamTrack Administrator. (Under Windows, choose Start > Programs > TeamShare > TeamTrack Administrator.)
2. Select the Users tab.
3. Click the Add button.
4. On the General tab, in the Login ID field, enter the replicator user name (see the replicator Teamtrack userid (teamtrack_user) parameter).
5. Click the Standard radio button (see Figure 3).
6. On the the Privileges tab, select the System tab and then select the "Connect using the API" check box (see Figure 4).
7. Click OK to add the user.

For information on getting a license from TeamShare for this extra user, see Section 3.3, "TeamTrack prerequisites".

Figure 3. New user: General tab

Figure 4. New user: Privileges tab

5.3.3. Providing field descriptions

The replicator uses TeamTrack issue field descriptions as the source for the Perforce job field descriptions. These job field descriptions appear in comments in every job form (if you're using the Perforce command line) and as tooltips for the fields in the job editing dialog (if you're using P4Win, the Perforce Windows GUI).

TeamTrack leaves field descriptions blank when you create a database, so you must provide descriptions of fields that your developers edit. For example, you might describe the TITLE field as "A one-sentence statement of the problem from the user's perspective", and the DESCRIPTION field as "A detailed description of the problem from the user's perspective, including how to reproduce it."

To enter field descriptions, follow these steps:

1. Run the TeamTrack Administrator. (Under Windows, choose Start > Programs > TeamShare > TeamTrack Administrator.)
2. Select the Workflows tab.
3. Select the Issue Workflow.
4. Click the Edit button.
5. Select the Default Fields tab.
6. Select the field you want to describe.
7. Click the Edit button.
8. Enter the description in the Description field.
9. Click OK to save your entries.
10. Repeat steps 6 to 9 until you're done.
11. Click the OK button.

5.5. Starting and stopping the replicator manually

To start the replicator, follow these steps from the operating system command line:

1. Go to the P4DTI installation directory.
2. Run the command python run.py.

The first time you start the replicator, it displays log output explaining how the replicator is setting up the defect tracker schema extensions, as shown in the following figure:

2000-12-08 15:27:25 UTC	P4DTI-00	replicator0	Reading SELECTIONS table to find type prefixes.
2000-12-08 15:27:25 UTC	P4DTI-00	replicator0	Reading USERS table.
2000-12-08 15:27:27 UTC	P4DTI-00	replicator0	Installing field 'P4DTI_RID' in the TS_CASES table.
2000-12-08 15:27:27 UTC	P4DTI-00	replicator0	Installing field 'P4DTI_SID' in the TS_CASES table.
2000-12-08 15:27:27 UTC	P4DTI-00	replicator0	Installing field 'P4DTI_JOBNAME' in the TS_CASES table.
2000-12-08 15:27:28 UTC	P4DTI-00	replicator0	Installing field 'P4DTI_ACTION' in the TS_CASES table.
2000-12-08 15:27:30 UTC	P4DTI-00	replicator0	Installed all new fields in the TS_CASES table.
2000-12-08 15:27:30 UTC	P4DTI-00	replicator0	Put 'LAST_CHANGE' parameter in replicator configuration with value '23'
2000-12-08 15:27:30 UTC	P4DTI-00	replicator0	Put 'SERVER' parameter in replicator configuration with value '"{'sid': 'perforce0', 'description': 'Perforce server 0'}"'
2000-12-08 15:27:31 UTC	P4DTI-00	replicator0	Put 'STATUS_VALUES' parameter in replicator configuration with value '"{'sid': 'perforce0', 'description': '_new/assigned/closed/verified/deferred/cleared/clogged/pumped'}"'
2000-12-08 15:27:31 UTC	P4DTI-00	replicator0	Put 'CHANGELIST_URL' parameter in replicator configuration with value '"{'sid': 'perforce0', 'description': None}"'
2000-12-08 15:27:45 UTC	P4DTI-00	replicator0	Reading USERS table.
2000-12-08 15:27:45 UTC	P4DTI-00	replicator0	Matched TeamTrack user 'pam' with Perforce user 'spam' by e-mail address 'gdr+pam@ravenbrook.com'.
2000-12-08 15:27:45 UTC	P4DTI-00	replicator0	Matched TeamTrack user 'john' with Perforce user 'scone' by e-mail address 'gdr+john@ravenbrook.com'.
2000-12-08 15:27:45 UTC	P4DTI-00	replicator0	Matched TeamTrack user 'fred' with Perforce user 'bedhead' by e-mail address 'gdr+fred@ravenbrook.com'.

After its startup sequence, the replicator polls for changes every 10 seconds and replicates those changes. After you start it for the first time, nothing happens until you make changes in the defect tracker or in Perforce. (To replicate all issues from the defect tracker to Perforce, follow the procedure in Section 5.7, "Refreshing jobs in Perforce".) Figure 6 shows typical replicator log output when it is replicating a change.

2000-12-08 15:59:12 UTC	P4DTI-00	replicator0	1 issue has changed
2000-12-08 15:59:12 UTC	P4DTI-00	replicator0	Set up issue '1' to replicate to job 'PRB00001'
2000-12-08 15:59:13 UTC	P4DTI-00	replicator0	Replicating issue 'PRB00001' to job 'PRB00001'
2000-12-08 15:59:15 UTC	P4DTI-00	replicator0	-- Changed fields: {'Engineer': 'fred', 'Resolution': '(None)', 'P4DTI-issue-id': '1', 'Owner': 'spam', 'Project': 'Pump', 'Description': 'I was just polishing the dome when my hand slipped.\012', 'Manager': 'spam', 'Priority': 'Urgent', 'How_Found': 'Normal_Use', 'Last_Modified_Date': '2000/12/08 15:59:05', 'P4DTI-rid': 'replicator0', 'Title': 'My oily rag fell into the chocolate pump', 'Workaround': '', 'Severity': 'High'}

To stop the replicator, follow these steps:

1. If the replicator is running in the background on UNIX or Linux, bring it to the foreground.
2. Press Control-C and wait for the replicator to next poll.

5.6. Setting up the replicator to start automatically

To set up the replicator to start automatically when the system boots, follow these steps:

[This section not written yet.]

5.7. Refreshing jobs in Perforce

The replicator only replicates issues that are created or modified after the replicator is first started. [This isn't true since the start_date parameter was introduced. RB 2001-02-13] Refreshing jobs replicates all issues from the defect tracker to Perforce and so can be used to initiate the replication of existing issues from the defect tracker to Perforce. You might want to create jobs in Perforce if:

• There aren't many issues in your defect tracker.
• Most of the issues in your defect tracker are open.

To create Perforce jobs that correspond to all the issues in your defect tracker, follow these steps from the operating system command line:

1. Stop the replicator.
2. Go to the P4DTI installation directory.
3. Run the command python refresh.py.
4. Start the replicator again by running the command python run.py.

Refreshing jobs deletes all the existing jobs in Perforce and replicates them from the defect tracker's database. This procedure is also useful if:

• The Perforce jobs become corrupted.
• You change the set of replicated fields in the replicator's configuration. For details, see Section 9, "Maintaining the P4DTI".

6. Migrating your defect tracking data to the integrated system

You do not need to take any special action to migrate defect tracking data from your defect tracker to the integrated system. The replicator starts replicating defect tracker issues as soon as it starts up. Only issues that are created or modified after the replicator is first started are replicated to Perforce.

7. Testing the P4DTI

7.1. Testing your configuration

Test the P4DTI configuration by creating a test issue and taking it through a complete life-cycle (that is, through the workflow) as described in the Perforce Defect Tracking Integration User's Guide. You might need to adapt the use cases described in the user's guide to your organization's workflow.

Test the P4DTI from both Perforce and the defect tracker. In Perforce, test the P4DTI using the interface that your developers are most likely to use. The main Perforce interfaces are:

• P4, the Perforce command line.
• P4Win, the Perforce GUI.
• The Perforce IDE integrations, if you use them.

7.2. Checking data consistency

To run the consistency checker and manage its output, follow these steps:

1. Change to the P4DTI installation directory.
2. Run the command python check.py.

Because the replicator only replicates issues that have changed since the replicator was first started, the consistency checker might report that a number of issues in the defect tracker are not replicated. This does not indicate an inconsistency in the data. To replicate all issues from the defect tracker to Perforce, follow the procedure in Section 5.7, "Refreshing jobs in Perforce".

You can also examine the database using a database application (for example, Microsoft Access or the mysql command) to ensure the Perforce data is in there.

8. Training and documentation

You might want to provide training for Perforce and defect tracker users before they adopt the P4DTI for everyday use. If so, consider preparing training materials that walk them through the workflow for an issue, using the procedures that are documented in the Perforce Defect Tracking Integration User's Guide.

Even if you don't have a formal training session for your users, ensure that they:

• Read the Perforce Defect Tracking Integration User's Guide.
• Upgrade their Perforce clients to version 2000.2 or later.
• Uninstall SourceBridge, if it's installed on their machines.
• Know not to edit the P4DTI-* fields in jobs.

9. Maintaining the P4DTI

You must stop and re-start the replicator as described in section 5.5, "Starting the replicator manually" after changing any of the configuration parameters described in section 5.1, "P4DTI configuration".

You must also stop and re-start the replicator after adding new users to your defect tracker or changing a user's userid or e-mail address. You might then need to edit jobs which mention that user in a field. The p4 jobs -e command can be used to search for text in the Perforce jobs.

After changing the list of replicated fields (replicated_fields), you must also refresh Perforce jobs, as described in Section 5.7, "Refreshing jobs in Perforce". Perforce uses the field number in the jobspec to find data, not the field name (for more information, see the Perforce System Administrator's Guide). If you change the list of replicated fields, then the field numbers change, which means that the fields of existing jobs in Perforce will be mixed up. Refreshing the jobs re-creates them from the defect tracker with the correct fields.

The TeamShare API used by the replicator to communicate with the TeamTrack server does not report the reasons for errors. This means that the P4DTI cannot tell why it can't replicate a change to a job from Perforce to TeamTrack. In general, the P4DTI assumes that it's because the user doens't have permission to modify the corresponding case, or because they've made a mistake or omitted information in filling out the job form. But sometimes there's a real error. If a user can't get a change through and you don't know why, check the Windows Application Log on the TeamTrack server machine using the Event Viewer. The Event Log usually contains more information about why things are going wrong. Note that TeamTrack doesn't report violations of privileges or invalid data in the Event Log.

10. Uninstalling the P4DTI

To uninstall the P4DTI, follow these steps:

1. Tell your staff. Ask them to stop using either Perforce jobs or the defect tracking, whichever you're not planning to use in future.
2. Remove any hooks that you created in Section 5.5, "Starting the replicator manually", such as Windows services, entries in /etc/rc.d, and so on.
3. Stop the replicator by pressing Control-C and waiting for the replicator to exit.
4. If you're using Bugzilla:
   1. Disable the Bugzilla extensions that were enabled in section 5.4.3, "Enabling the Bugzilla extensions".
   2. Delete the replicator's Bugzilla user that was created in section 5.4.2, "Creating a Bugzilla user for the replicator".
   3. optionally, restore the unpatched copy of Bugzilla made in section 5.4.1, "Patching Bugzilla".
5. If you're using TeamTrack:
   1. Delete the replicator's TeamTrack user that was created in section 5.3.2, "Creating a TeamTrack user for the replicator".
   2. Delete the registry key created in section 5.3.1, "Updating the Windows Registry".
6. Remove any Perforce triggers that were added in section 5.2.2, "Installing Perforce triggers to enforce workflow".
7. Delete the replicator's Perforce user created in section 5.2.1, "Creating a Perforce user for the replicator".
8. Delete the contents of the P4DTI installation directory.

11. Troubleshooting and error messages

11.1. Troubleshooting

To troubleshoot a problem with the P4DTI, follow these steps:

1. Look in the P4DTI log. If you find an error message, see if it is listed in Section 11.2, "Error messages".
2. Check your configuration against Section 5.1, "P4DTI configuration". Are the hostnames, userids, and passwords correct? Most problems with the P4DTI are caused by incorrect or inconsistent configuration.

3. If you can't solve the problem, contact Perforce support (for details, see http://www.perforce.com/perforce/support.html). Provide the following information:

   • What you did immediately prior to the error's occurrence.
   • What you think should have happened.
   • What actually happened.
   • The P4DTI release you are using.
   • The Perforce release you are using. To determine your Perforce release, enter "p4 info" at the operating system command line.
   • The name and release of the defect tracker you are using. To determine your TeamTrack release, click the information symbol in the top right of the page; include the Version, Browser, Web Server and Database entries in your problem report. To determine your Bugzilla release, check the top of a bug form.
   • A section of the P4DTI log that includes the error that you're reporting and some context around that error.
   • A copy of your config.py file.

11.2. Error messages

Field '%s' has type %d: this is not supported by P4DTI.

The P4DTI doesn't support all TeamTrack field types. One of the fields in your list of replicated fields (replicated_fields) has an unsupported type.

You can determine the list of supported types from the type_table in configure_teamtrack.py. The most notable unsupported type is "MULTIPLE_SELECTION", because Perforce does not provide any kind of multiple selection interface.

If you really need to have the field replicated, you have the following options:

• Change the set of fields in TeamTrack to avoid the type.
• Change your workflow to avoid needing that particular field from the Perforce interface.
• Submit a request to Perforce.
• Implement a new subclass of replicator.translator to handle the field type (for the existing translators, see dt_teamtrack.py). For instructions on how to extend the P4DTI, and how to contribute your extensions back to the community, see the Perforce Defect Tracking Integration Integrator's Guide.

Field '%s' specified in 'replicated_fields' list is a system field: leave it out!

Some fields are always replicated. For details, see the list of replicated fields (replicated_fields) parameter.

Remove the system fields from your list of replicated fields.

Field '%s' specified in 'replicated_fields' list not in TeamTrack FIELDS table.

You can specify a list of fields for the P4DTI to replicate into jobs; for details, see the list of replicated fields (replicated_fields) parameter. This error means that the P4DTI couldn't find one of the fields in the list. This problem might happen if you change the set of fields in TeamTrack.

Double-check the field names you specified as the replicated_fields. If you're changing fields in TeamTrack, see Section 9, "Maintaining the P4DTI", for important information.

Too many fields to replicate: Perforce jobs can contain only 99 fields.

Reduce the number of fields that you replicate by removing items from the list of replicated fields (replicated_fields).

Two defect tracker states '%s' and '%s' map to the same Perforce state '%s'.

The P4DTI chooses the names of states of Perforce jobs based on the state names in the defect tracker. It uses the following mapping system:

• Perforce job states can't contain spaces and various other characters, so the P4DTI maps spaces to underscores, and translates other special characters using an encoding similar to that used in URLs.
• To avoid user confusion in the Perforce interface, the P4DTI maps all state names to lower case, which means that you can't have defect tracker states which are only distinguished by differences in case. (But note that in TeamTrack, which has different issue workflows for different projects, it's OK to have states with the same name as long as they are in different projects.)
• Perforce jobs can't have the state "new" or "ignore", because these states have special meaning to the Perforce server. The P4DTI maps a defect tracker state "new" (or "New", "NEW", and so on) to Perforce state "_new" and a defect tracker state "ignore" to Perforce state "_ignore". This mapping system means that you also can't have states called " new" or " ignore" with an initial space (or " New", " Ignore", and so on) in the defect tracker at the same time as one called "new" or "ignore".

Resolve this problem by making the state names distinct in TeamTrack. Do not use spaces at the beginning of state names.

You can't have a field called 'code' in the Perforce jobspec.

Perforce uses the field "code" to pass internal status information to clients.

In TeamTrack, change the logical name of the field to something other than "code" by following these steps:

1. Run the TeamTrack Administrator. (Under Windows, choose Start > Programs > TeamShare > TeamTrack Administrator.)
2. Select the Workflow tab.
3. Select the workflow containing the field called "code".
4. Click the Edit button.
5. Select the Default Fields tab.
6. Select the "code" field.
7. Click the Edit button.
8. Change the Logical Field Name.
9. Click OK.
10. Click OK again.

You specified the closed_state '%s', but there's no such TeamTrack state.

You can specify a defect tracker state to map to the Perforce "closed" state, so that you can work around limitations in Perforce; for details, see the state mapping to "closed" (closed_state) parameter. The P4DTI checks that this state exists, so that you can be sure that it knows which one you mean. This error means that the P4DTI couldn't find the state you specified, which might happen if you change the state name in the defect tracker without changing the P4DTI configuration.

Double-check the state name you specified as the closed_state in config.py.

Perforce error: You don't have permission for this operation

You haven't given the replicator permission to edit the Perforce jobspec. The replicator needs to have superuser privileges in Perforce. For instructions, see Section 5.2.1, "Creating a Perforce user for the replicator".

A. References

B. Document History

Glossary

Copyright © 2000–2001 Ravenbrook Limited. This document is provided "as is", without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this document. You may make and distribute copies and derivative works of this document provided that (1) you do not charge a fee for this document or for its distribution, and (2) you retain as they appear all copyright and licence notices and document history entries, and (3) you append descriptions of your modifications to the document history.