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
• 2.3. Limitations: will the P4DTI work for your organization?
• 3. Prerequisites for installing the P4DTI
• 3.1. Required experience
• 3.2. Perforce prerequisites
• 3.3. TeamTrack prerequisites
• 3.4. Bugzilla prerequisites
• 3.5. User accounts
• 4. Installing the P4DTI
• 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. Advanced configuration
• 6. Migrating your defect tracking data to the integrated system
• 6.1. Migrating from the defect tracker
• 6.2. Creating issues in Perforce
• 6.3. Migrating to the defect tracker from Perforce jobs
• 7. Testing the P4DTI
• 7.1. Taking a single step
• 7.2. Testing your configuration
• 7.3. Checking data consistency
• 8. Training and documentation
• 9. Maintaining the P4DTI
• 9.1. Maintaining the configuration
• 9.2. Refreshing jobs in Perforce
• 10. Uninstalling the P4DTI
• 11. Troubleshooting and error messages
• 11.1. Troubleshooting
• 11.2. Error messages by identifier
• 11.3. Other error messages
• A. References
• B. Document history
• C. Glossary
• D. Table of commands

1. Introduction

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

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

Perforce has a mechanism for linking jobs to changelists (the p4 fix command), 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 e-mail 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.

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

2.3. Limitations: will the P4DTI work for your organization?

If you're using TeamTrack and your workflow is very complex then the P4DTI may make mistakes when translating actions in Perforce into actions in TeamTrack.

(This is because TeamTrack supports operations that can't be represented in Perforce, such as a "transition" between two states in a workflow. When someone edits a job in Perforce, the P4DTI tries to guess which TeamTrack transition was meant by looking at the state you started with and the state you ended up in. However, if you have multiple transitions between the same two states, then it may guess wrongly. See section 3.3.2, item 6 for details of workflows that the P4DTI may have trouble with.)

If you have automation that makes very frequent changes to records in the defect tracker, then users may be unable to edit jobs from Perforce.

(This is because the P4DTI works by polling the databases every 10 seconds (by default). If there are many updates to the defect tracker in this period then the data in Perforce will be out of date; any attempt to edit out-of-date data is rejected by the P4DTI because that would introduce inconsistencies.)

3. Prerequisites for installing the P4DTI

3.1. Required 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

1. 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.
2. Perforce client software of version 2001.1 or later for every P4DTI user who uses Perforce, and for the P4DTI itself.
3. Perforce licenses for every defect tracker user who is going to work in Perforce.
4. A background user license for the replicator. This is a license for an automatic process, rather than a person. Perforce provides background licenses free of charge; contact Perforce Customer Service to get one.

3.2.2. Procedural prerequisites

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, "Configuring the P4DTI, Perforce, and the defect tracker".

3.5. User accounts

Create an account in each system for each user who needs to use the integrated system.
If you are using Bugzilla, create a Bugzilla account for every user in Perforce.
If you are using TeamTrack, then you must make sure that every Perforce user who needs to edit or fix defects has an account in TeamTrack. (If you're short of licenses, then there's no need for other TeamTrack users to have accounts in Perforce, or for Perforce users who don't do defect resolution to have accounts in TeamTrack.)
Make sure that each user has the same e-mail address in the defect tracker and in Perforce. The P4DTI uses e-mail address to match up users between the two systems.

(This is necessary in the Bugzilla integration where your e-mail address is used as your userid. In the TeamTrack integration this allows the P4DTI to work in organizations where users have been assigned different userids in the two systems.)

The P4DTI supports Bugzilla's "emailsuffix" feature (once you've applied the Bugzilla patch, section 5.4.1, and turned on the P4DTI extensions in Bugzilla, section 5.4.3), so if you have "emailsuffix" set to "@company.domain", then the user "joe" in Bugzilla will match a user in Perforce with the e-mail address "joe@company.domain".

• If someone changes a job in Perforce but the P4DTI can't find a matching user in the defect tracker, then the change to the job is disallowed (because the defect tracker requires that changes be made only by users with the right privileges).
• If two users in Perforce have the same e-mail address then theP4DTI chooses the first one it finds when matching a user from the defect tracker. This choice is likely to be incorrect.
• If two users in TeamTrack have the same e-mail address then theP4DTI chooses the first one it finds when matching a user from Perforce. This choice is likely to be incorrect.

Date: Tue, 2 Oct 2001 15:26:12 +0100 (BST)
From: p4dti-replicator0@company.domain
To: P4DTI administrator <p4dti-admin@company.domain>
Subject: (P4DTI-8669)  The P4DTI replicator has started.

(P4DTI-8658)  This is an automatically generated e-mail from the Perforce Defect
Tracking Integration replicator 'replicator0'.

(P4DTI-8669)  The P4DTI replicator has started.

(P4DTI-867X)  The following Perforce users do not correspond to defect tracker
users.  The correspondence is based on the e-mail addresses in the defect
tracker and Perforce user records.

(P4DTI-6302)  These Perforce users will appear in TeamTrack as the user (None).
It will not be possible to assign issues to these users.

  User   E-mail address
  -----------------------
  nickb  nickb@client

(P4DTI-8705)  The following defect tracker users do not correspond to Perforce
users.  The correspondence is based on the e-mail addresses in the defect
tracker and Perforce user records.

(P4DTI-6299)  These TeamTrack users will appear as themselves in Perforce even
though there is no such Perforce user.

  User  E-mail address
  ------------------------
  nb    nb@company.domain

(P4DTI-6379)  These Perforce users have duplicate e-mail addresses.  They may
have been matched with the wrong TeamTrack user.

  User  E-mail address
  ------------------------
  root  ndl@company.domain
  ndl   ndl@company.domain

(P4DTI-6368)  These TeamTrack users have duplicate e-mail addresses.  They may
have been matched with the wrong Perforce user.

  User   E-mail address
  ------------------------
  admin  rb@company.domain
  rb     rb@company.domain

Section 1 lists Perforce users that couldn't be matched to a user in the defect tracker (here TeamTrack). Here the user hasn't set their e-mail address in Perforce: they still have the default.

Section 2 lists defect tracker users that couldn't be matched to a user in Perforce.

Section 3 lists Perforce users with duplicate e-mail addresses. In this case, if a defect tracker user had the address <ndl@company.domain> then the P4DTI may have matched them wrongly. Give each Perforce user a distinct e-mail address.

Section 4 lists defect tracker users with duplicate e-mail addresses. Give each defect tracker user a distinct e-mail address.

4. Installing the P4DTI

The installation for p4dti for bugzilla on Win2000 is distributed as p4dti-bugzillawin-1.4.2.exe. Transfer this to the local machine and run "p4dti-bugzillawin-1.4.2."

Installing bugzilla on Win2000 to work with P4DTI  is a two step process. Bugzilla-2.14.1 is not supported by the Bugzilla team on Windows.  One needs to tweak the code to make it work. Further, the P4DTI changes for Bugzilla needs to be applied on top of Bugzilla.

The p4dti-kit-bugzillawin-1.4.2 contains bugzilla code that works with p4dti but contains only the minimal features. The complete bugzilla code can be downloaded from http://www.parrus.com/project/p4dti.

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

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 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).

5.1. P4DTI configuration

5.1.1. Essential configuration parameters

dt_name

Example: "TeamTrack"

Make sure that this variable is set to the appropriate value for your defect tracker.

administrator_address

Example: "p4dti-admin@company.domain"

The replicator sends error reports to this address. If this is None, then the replicator never sends e-mail.

p4_port

Example: "perforce.company.domain:1666"

p4_user

Example: "p4dti-replicator0"

For information about how the replicator logs in to Perforce, see section 5.2, "Perforce configuration". If you want to add more replicators later, incorporate the replicator identifier (rid) into this userid.

p4_password

Example: ""

For information about how the replicator logs in to Perforce, see section 5.2, "Perforce configuration".

replicator_address

Example: "p4dti-replicator0@company.domain"

To make it easier for users to get assistance, make this address an alias for the administrator e-mail address (administrator_address). If you are using Bugzilla, this e-mail address is also used for the replicator's Bugzilla account; see section 5.4.2, "Creating a Bugzilla user for the replicator".

smtp_server

Example: "smtp.company.domain"

If this is None, then the replicator never sends e-mail.

If you need to run the P4DTI without being connected to a network (for example, if you want to set it up on a laptop so that you can give a demonstration), set smtp_server=None so that the replicator doesn't try to send e-mail.

start_date

Example: "2001-02-10 00:00:00"

Issues modified after this date are replicated; issues unchanged after this date are ignored. Must be a string in the form "YYYY-MM-DD HH:MM:SS".

5.1.4. Other configuration parameters

changelist_url

This is used by the defect tracker to provide a link from a fix to a web page providing more information about the changelist that fixed the issue. Figure 6 shows how this works in Bugzilla.

The value must be a format string valid for passing to sprintf(); it must have one %d format specifier, for which the change number is substituted. (Note that because the value gets passed to sprintf(), you must double other percent signs.)

In order to use this feature, you must have a web application that can provide information about changelists. Applications suitable for this include:

P4Web. To allow any user to follow the link from the defect tracker to P4Web, you need to run it in "browse mode". See the P4Web documentation for details.

For P4Web, set changelist_url to something like "http://info.company.domain:8080/%d?ac=10".

Perfbrowse. For Perfbrowse, set changelist_url to something like "http://info.company.domain/cgi/perfbrowse.cgi?@describe+%d".

Figure 6. Effect of changelist_url and job_url

job_url

This is used by the defect tracker to provide a link from an issue to a web page providing more information about the job that corresponds to the issue. Figure 6 shows how this works in Bugzilla.

Example: "http://info.company.domain/cgi/perfbrowse.cgi?@job+%s"

The string is a format string valid for passing to sprintf(); it must have one %s format specifier, for which the job name is substituted. (Note that because it gets passed to sprintf(), you must double other percent signs.)

log_file

Example: "C:\\Program Files\\P4DTI-RELEASE\\p4dti.log"

The replicator generates log messages to record its actions. These log messages are sent to all of the following locations:

• The standard output of the replicator.
• The system log (under UNIX and Linux).
• The event log (under Windows, if use_windows_event_log is 1).
• The file specified by the log_file configuration parameter (unless it's None).

log_level

Example: message.INFO

This parameter must be one of these constants:
 

message.ERR	Errors.
message.WARNING	Warnings; that is, features of your system that the replicator can work around, but which you should pay attention to. For example, "Table 'PROJECTS' has two entries called 'Compiler'.".
message.NOTICE	Significant but expected events. For example, "Job 'BUG00001' overwritten by issue 'BUG00001'.".
message.INFO	Informational messages. For example, "Replicating issue '123' to job 'BUG000123'."
message.DEBUG	Debugging messages. For example, "Perforce command: 'p4 -G -u p4dti-replicator0 -p perforce:1666 job -o BUG00001'."

p4_client_executable

Example: "C:\\Program Files\\Perforce\\p4.exe"

This setting doesn't need to be an absolute path name if the directory is on the replicator user's path. On Windows this setting might be "C:\\Program Files\\Perforce\\p4.exe". On UNIX it might be just "p4".

The client executable named by this parameter must be of version 2000.2 or later (run the command p4 -V to check the client version), and it must be the same version as the Perforce server you are connecting to. If there's a mismatch between the Perforce client executable and the Perforce server, then you might see the error message (P4DTI-7087) Value for field 'Options' must be one of ....

p4_server_description

Example: "Hardware development group Perforce server"

poll_period

Example: 10

prepare_issue(issue, job)

See section 3, "Allowing users to create issues in Perforce" in the Perforce Defect Tracking Advanced Administrator's Guide for the full details.

replicate_p(issue)

See section 2, "Select the issues to replicate" in the Perforce Defect Tracking Advanced Administrator's Guide for the full details.

replicate_job_p(job)

See section 3, "Allowing users to create issues in Perforce" in the Perforce Defect Tracking Advanced Administrator's Guide for the full details.

rid

Example: "replicator0"

Must be 32 characters or less, start with a letter or underscore, and consist only of letters, numbers, and underscores.

The replicator identifier is used to distinguish between replicators when multiple replicators are being used to replicate issues from a defect tracker to different Perforce servers. If you have only one replicator, it doesn't matter what you use for the replicator identifier; "replicator0" is a good choice since it allows you to add more replicators later.

If you change the replicator identifier then your currently replicated defect tracker issues stop being replicated. The replicator believes they are being handled by another replicator.

sid

Example: "perforce0"

Must be 32 characters or less, start with a letter or underscore, and consist only of letters, numbers and underscores. You might want to use the hostname of your Perforce server, if it is stable.

use_deleted_selections

Example: 0

Warning: It is risky to set this to 0 because TeamTrack never really deletes a state or selection; it just marks it as deleted. So you may have issues in TeamTrack that use those deleted states and selections. If use_deleted_selections is 0 then these issues can't be replicated to Perforce. If this happens, you'll see errors like these:

(P4DTI-6255) No Perforce state corresponding to TeamTrack state 'spong'.

If this happens you can undelete the state in TeamTrack and restart the replicator. Or you can change the state of the issue in TeamTrack so that it can be replicated.

(P4DTI-7087) Value for field 'Severity' must be one of Critical/High/Medium/Low/(None).

If this happens you can undelete the selection in the Severity field in TeamTrack and restart the replicator. Or you can change the severity of the issue in TeamTrack so that it can be replicated.

use_perforce_jobnames

If this parameter is 1, the P4DTI lets Perforce choose the names of the jobs it creates when replicating issues from the defect tracker (so jobs will be named job000001, job000002 and so on). This means that the job name won't match the name of the corresponding issue in the defect tracker.

If this parameter is 0 (the default), the P4DTI tries to match the defect tracker's names for the issues it replicates. In the TeamTrack integration, jobs are called BUG00001, ENH00002, and so on.In the Bugzilla integration, jobs are called bug1, bug2, and so on.

Example: 1

If you change this setting, the P4DTI doesn't rename existing jobs, but new jobs get the style of name you requested.

5.1.5. Choosing 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.
• Note that Perforce has no protections for jobs. This means that any user of Perforce can read all fields of all the jobs. So if you have confidential information in issues, keep that information out of Perforce, for example by separating it out into a field that is not replicated.

5.2. Perforce configuration

1. Create a Perforce user for the replicator (section 5.2.1).
2. Install Perforce triggers to enforce workflow (optional; section 5.2.2).
3. 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

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.

5.2.2. Installing Perforce triggers to enforce workflow

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 the "priority" or "severity" is above a certain level, or that a manager has set the "approval" field. See the replicated_fields configuration parameter (for Bugzilla or TeamTrack).
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

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

It is possible to keep existing issues that are stored in Perforce jobs. Migration submits all the Perforce job data to the defect tracker, so that the issues can be replicated back to Perforce, and so appear in both systems. This requires more experience of Perforce and some Python programming. See section 4, "Migrating to the defect tracker from Perforce jobs", of the Perforce Defect Tracking Integration Advanced Administrator'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:

1. Update the Windows Registry (section 5.3.1).
2. Create a TeamTrack user for the replicator (section 5.3.2).
3. 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 do this, double-click the p4dti.reg file that comes with the P4DTI (it's installed in c:\program files\p4dti\p4dti.reg by default).

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 User product access radio button (see Figure 7).
6. On the Privileges tab, select the System tab and then select the "Connect using the API" check box (see Figure 8).
7. On the Privileges tab, select the Item tab.
8. In the pane at the left, select the base project.
9. In the pane at the right, select the "Submit New Items", "Update All Items" and "Transition All Items" check boxes (see Figure 9).
10. 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 7. New user: General tab
Figure 8. New user: Privileges tab, System tab
Figure 9. New user: Privileges tab, Item 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

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

2001-03-12 20:05:45 UTC  (P4DTI-6018)  Installing field 'P4DTI_RID' in the TS_CASES table.
2001-03-12 20:05:45 UTC  (P4DTI-6018)  Installing field 'P4DTI_SID' in the TS_CASES table.
2001-03-12 20:05:45 UTC  (P4DTI-6018)  Installing field 'P4DTI_JOBNAME' in the TS_CASES table.
2001-03-12 20:05:46 UTC  (P4DTI-603X)  Installed all new fields in the TS_CASES table.
2001-03-12 20:05:47 UTC  (P4DTI-6040)  Put 'LAST_CHANGE' parameter in replicator configuration with value '0'.
2001-03-12 20:05:47 UTC  (P4DTI-6040)  Put 'SERVER' parameter in replicator configuration with value '"{'sid': 'perforce0', 'description': 'Perforce server on sandpiper'}"'.
2001-03-12 20:05:47 UTC  (P4DTI-6040)  Put 'STATUS_VALUES' parameter in replicator configuration with value '"{'sid': 'perforce0', 'description': '_new/assigned/closed/verified/deferred'}"'.
2001-03-12 20:05:47 UTC  (P4DTI-6040)  Put 'CHANGELIST_URL' parameter in replicator configuration with value '"{'sid': 'perforce0', 'description': 'http://sandpiper.ravenbrook.com:8080/%d?ac=10'}"'.
2001-03-12 20:05:48 UTC  (P4DTI-8002)  Mailing 'P4DTI administrator <gdr+admin@ravenbrook.com>' re: '(P4DTI-8669)  The P4DTI replicator has started.'.
...

During its startup sequence, the replicator creates Perforce jobs corresponding to every defect tracker issue created or modified after the (start_date). It then polls for changes every poll_period seconds and replicates those changes. Figure 11 shows typical replicator log output when it is replicating a change.

2001-03-12 19:59:29 UTC  (P4DTI-8057)  Replicating job 'CHG00003' to issue 'CHG00003'.
2001-03-12 19:59:30 UTC  (P4DTI-824X)  -- Changed fields: {'SEVERITY': 46, 'VERSION': 53, 'STATE': 2, 'PRIORITY': 17}.
2001-03-12 19:59:30 UTC  (P4DTI-6007)  -- Transition: 3; User: rb.
2001-03-12 19:59:30 UTC  (P4DTI-8261)  -- Defect tracker made changes as a result of the update: {'Owner': 'gdr'}.

1. Select the command window in which the replicator is running.
2. Press Control-C and wait for the replicator to next poll (this takes up to poll_period seconds).

5.6. Setting up the replicator to start automatically

5.6.1. Running automatically on Unix

/etc/rc.d/init.d/p4dti start

/etc/rc.d/init.d/p4dti stop

5.6.2. Running automatically on Windows

To install the service, follow these steps from the operating system command line:

1. Go to the P4DTI installation directory.
2. Run the command:

python service.py

• Use the control panel to start the Services applet and scroll down until you find "P4DTI". Click on this once, then click "Start".
• Go to the P4DTI installation directory and run the command: python service.py start.
• When the machine reboots, the service starts automatically.

• Use the control panel to start the Services applet and scroll down until you find "P4DTI". Click on this once, then click "Stop".
• Go to the P4DTI installation directory and run the command: python service.py stop.
• When the machine is shut down, the service stops automatically.

python service.py remove

5.7. Advanced configuration

• Connecting a defect tracker to multiple Perforce servers.
• Working with an existing Perforce jobs database and an existing Perforce jobspec.
• Fine control over which defect tracker issues are replicated to Perforce.
• Fine control over which issue fields are replicated, and their names.
• Arbitrary translation of issue data between the defect tracker and Perforce.
• Queries based on combined defect tracker and Perforce data.
• Working with locally customized versions of Bugzilla.
• Redirection or fine control of logging.
• Arbitrary mappings between Perforce and defect tracker user names.
• Alternative policies for handling conflicts between defect tracker and Perforce changes to issues.

6. Migrating your defect tracking data to the integrated system

6.1. Migrating from the defect tracker

6.2. Allowing users to create issues in Perforce

6.3. Migrating to the defect tracker from Perforce jobs

7. Testing the P4DTI

7.1. Taking a single step

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

7.2. Testing your configuration

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.3. Checking data consistency

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

8. Training and documentation

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 2001.1 or later.
• Uninstall SourceBridge, if it's installed on their machines.
• Know not to edit the P4DTI-* fields in jobs.

9. Maintaining the P4DTI

9.1. Maintaining the configuration

You must also refresh Perforce jobs, as described in section 9.2, "Refreshing jobs in Perforce", after changing either:

1. the list of replicated fields (replicated_fields for Bugzilla or TeamTrack), or
2. the start date for replication (start_date).

9.2. Refreshing jobs in Perforce

• The Perforce jobs become corrupted.
• You change the set of replicated fields in the replicator's configuration. For details, see section 9.1, "Maintaining the configuration".
• You change the start date of replication in the replicator's configuration. For details, see section 9.1.

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.

10. Uninstalling the P4DTI

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. Stop the replicator by following the instructions in section 5.5, "Starting the replicator manually" (or section 5.6, "Setting up the replicator to start automatically").
3. Remove any hooks that you created in section 5.6, "Setting up the replicator to start automatically", such as Windows services, entries in /etc/rc.d, and so on.
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".
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. If you installed using the Linux RPM, as described in section 4.3, "Linux installation", uninstall using the command

rpm -e p4dti

Otherwise, delete the contents of the P4DTI installation directory. 

11. Troubleshooting and error messages

11.1. Troubleshooting

Look in the P4DTI log. If you find an error message, see if it is listed in section 11.2, "Error messages".

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.

See if there is any online support for your problem. Visit the P4DTI issue reports page <http://www.ravenbrook.com/project/p4dti/issue/>, choose your release and select the "Support information" report.

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

1. What you did immediately prior to the error's occurrence.
2. What you think should have happened.
3. What actually happened.
4. The P4DTI release you are using (look in the readme.txt that came with your P4DTI distribution to identify the release).
5. The Perforce release you are using. To determine your Perforce release, enter "p4 info" at the operating system command line.
6. 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.
7. A section of the P4DTI log that includes the error that you're reporting and some context around that error.
8. Copies of any related e-mail messages generated by the P4DTI.
9. A copy of your config.py file.

11.2. Error messages by identifier

(P4DTI-1058) Given '%s' when expecting a string or integer. 
(P4DTI-1069) Select '%s' of %s returns no rows. 
(P4DTI-107X) Select '%s' of %s expecting one row but returns %d. 
(P4DTI-1080) Trying to fetch a row from non-select '%s'. 
(P4DTI-1091) Select '%s' of %s returned an unfetchable row. 
(P4DTI-1105) Trying to fetch rows from non-select '%s'. 
(P4DTI-1116) Select '%s' of %s returned unfetchable rows. 
(P4DTI-1127) Select '%s' of %s expecting no more than one row but returns %d. 
(P4DTI-1138) Select '%s' of %s returns %d columns but %d values. 
(P4DTI-1160) Couldn't insert row in table '%s'. 
(P4DTI-1171) Couldn't update row in table '%s' where %s. 
(P4DTI-1229) Nothing in p4dti_replications table: database corrupted? 
(P4DTI-1273) Bugzilla's fielddefs table does not include '%s'.

(P4DTI-1207) Unknown or future P4DTI/Bugzilla schema version %s detected.

(P4DTI-123X) Bugzilla version %s is not supported by the P4DTI.

(P4DTI-2006) Configuration parameter '%s' must be 0 or 1. 
(P4DTI-2017) Configuration parameter '%s' (value '%s') is not a valid date. The right format is 'YYYY-MM-DD HH:MM:SS'. 
(P4DTI-2028) Configuration parameter '%s' (value '%s') is not a valid e-mail address. 
(P4DTI-2039) Configuration parameter '%s' must be a function. 
(P4DTI-204X) Configuration parameter '%s' must be an integer. 
(P4DTI-2050) Configuration parameter '%s' must be a list. 
(P4DTI-2061) Configuration parameter '%s' must be a list of %s. 
(P4DTI-2072) Configuration parameter '%s' must be a string. 
(P4DTI-2083) Configuration parameter '%s' must be None or a string. 
(P4DTI-2094) Configuration parameter '%s' (value '%s') must be from 1 to 32 characters long, start with a letter or number, and consist of letters, numbers and underscores only. 
(P4DTI-2108) Configuration parameter '%s' (value '%s') must contain exactly one %%d format specifier, any number of doubled percents, but no other format specifiers. 
(P4DTI-2119) Configuration parameter '%s' (value '%s') must contain exactly one %%s format specifier, any number of doubled percents, but no other format specifiers.

(P4DTI-3009) Two Bugzilla states '%s' and '%s' map to the same Perforce state '%s'.

The P4DTI chooses the names of states of Perforce jobs based on the status names in Bugzilla. It uses the following translation system:

• To avoid user confusion in the Perforce interface, the P4DTI translates all state names to lower case.
• Perforce job states can't contain spaces and various other characters, so the P4DTI translates spaces to underscores, and translates other special characters.
• If the closed_state parameter is not None, the P4DTI translates this status to "closed" and translates "CLOSED" to "bugzilla_closed".
• Perforce jobs can't have the state "new" or "ignore", because these states have special meaning to the Perforce server. The P4DTI prefixes a Bugzilla status which would translate to either of these with "bugzilla_", so (in particular) "NEW" translates to Perforce state "bugzilla_new".

(P4DTI-301X) You specified the closed_state '%s', but there's no such Bugzilla state.

(P4DTI-3020) The '%s' column of Bugzilla's 'bugs' table is not an enum type.

(P4DTI-3031) Configuration parameter 'bugzilla_directory' does not name a directory. 
(P4DTI-3042) Configuration parameter 'bugzilla_directory' does not name a directory containing a processmail script.

(P4DTI-3053) Bugzilla's table 'profiles' does not have a 'login_name' column. 
(P4DTI-3064) The 'login_name' column of Bugzilla's 'profiles' table does not have a 'text' type. 
(P4DTI-3075) Bugzilla's table 'bugs' does not have a '%s' column. 
(P4DTI-3086) The 'bug_status' column of Bugzilla's 'bugs' table is not an enum type. 
(P4DTI-3097) The 'resolution' column of Bugzilla's 'bugs' table is not an enum type. 
(P4DTI-3100) The 'resolution' column of Bugzilla's 'bugs' table does not have a 'FIXED' value.

(P4DTI-3111) Field '%s' specified in 'replicated_fields' is a system field: leave it out!

Remove the system fields from your list of replicated fields and start the P4DTI again.

(P4DTI-3122) Field '%s' appears twice in 'replicated_fields'.

(P4DTI-3133) Field '%s' specified in 'replicated_fields' list not in Bugzilla 'bugs' table.

(P4DTI-3144) Field '%s' specified in 'replicated_fields' list has type '%s': this is not yet supported by P4DTI. 
(P4DTI-3155) Field '%s' specified in 'replicated_fields' list has floating-point type: this is not yet supported by P4DTI.

Remove the field from your replicated_fields and start the replicator again.

If you really need this field to be replicated, see the advice for (P4DTI-4067).

(P4DTI-3166) You can't have a field called 'code' in the Perforce jobspec.

(P4DTI-3177) Too many fields to replicate: Perforce jobs can contain only 99 fields.

(P4DTI-4001) Two TeamTrack states '%s' and '%s' map to the same Perforce state '%s'.

• Perforce job states can't contain spaces and various other characters, so the P4DTI maps spaces to underscores, and translates other special characters.
• 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".

(P4DTI-4012) You specified the closed_state '%s', but there's no such TeamTrack state.

(P4DTI-4023) Couldn't get descriptions for TeamTrack system fields STATE, OWNER, and TITLE.

This could happen if you don't have a tTrack solution in your TeamTrack database. If so, create one.

(P4DTI-4034) Field '%s' specified in 'replicated_fields' list not in TeamTrack FIELDS table.

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.

(P4DTI-4045) Field '%s' specified in 'replicated_fields' list is a system field: leave it out!

(P4DTI-4056) Field '%s' appears twice in 'replicated_fields'.

(P4DTI-4067) Field '%s' has type %d: this is not supported by P4DTI.

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.

(P4DTI-4078) You can't have a field called 'code' in the Perforce jobspec.

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.

(P4DTI-4089) Too many fields to replicate: Perforce jobs can contain only 99 fields.

(P4DTI-5004) User %d isn't in the right bug group to edit bug %d.

Bugzilla bugs can be grouped into "bug groups", which restrict the ability of users to view or edit them. Perforce protections cannot express these bug groups, so the replicator must enforce the Bugzilla restrictions by rejecting changes made by users outside the necessary bug group.

Another possible cause is that the P4DTI has failed to find a Bugzilla user corresponding to the Perforce user. See section 3.5, "User accounts" for details of how users are mapped from one system to the other, and how to diagnose problems.

(P4DTI-5015) User %d doesn't have permission to change field '%s' of bug %d to %s.

Bugzilla has complex access controls which prohibit some users from making some changes to bugs. Perforce protections cannot express these controls so the replicator enforces these controls by rejecting changes to jobs which would not be permitted by Bugzilla.

Another possible cause is that the P4DTI has failed to find a Bugzilla user corresponding to the Perforce user. See section 3.5, "User accounts" for details of how users are mapped from one system to the other, and how to diagnose problems.

(P4DTI-5026) The P4DTI does not support marking bugs as DUPLICATE from Perforce.

When a bug is marked as a duplicate in Bugzilla, the number of the other bug is provided and a message identifying it is appended to the long description. The Perforce job interface provides no easy way of expressing this, so the replicator does not allow it.

(P4DTI-5037) Bugzilla does not allow a transition from status '%s' to '%s'.

It is difficult but possible to cause this error by making more than one change to the status in rapid succession (between two consecutive replicator polls). The replicator can't tell if that has happened, so has to reject the change anyway.

(P4DTI-5048) Cannot change Bugzilla field '%s'.

(P4DTI-5059) Can only append to Bugzilla field '%s'.

(P4DTI-506X) Updating non-existent Bugzilla field '%s'. 
(P4DTI-5092) No Perforce status corresponding to Bugzilla status '%s'. 
(P4DTI-5106) No Bugzilla status corresponding to Perforce status '%s'.

(P4DTI-5070) Bugzilla does not have a group called '%s'. 
(P4DTI-5081) Bugzilla's fielddefs table does not include '%s'.

(P4DTI-5117) Perforce field value '%s' could not be translated to a number for replication to Bugzilla.

(P4DTI-5128) Bugzilla P4DTI user '%s' has e-mail address matching Perforce user '%s', not Perforce P4DTI user '%s'.

(P4DTI-5139) Bugzilla P4DTI user '%s' is not a known Bugzilla user.

(P4DTI-514X) There is no Bugzilla user corresponding to Perforce user '%s'.

(P4DTI-5172) Can't create Bugzilla bug without short_desc field. 
(P4DTI-5183) Can't create Bugzilla bug with empty short_desc field. 
(P4DTI-5194) Can't create Bugzilla bug without product field. 
(P4DTI-5208) Can't create Bugzilla bug for non-existent product '%s'. 
(P4DTI-5219) Can't create Bugzilla bug for product '%s' with no components. 
(P4DTI-522X) Can't create Bugzilla bug without component field. 
(P4DTI-5230) Can't create Bugzilla bug: product '%s' has no component '%s'. 
(P4DTI-5241) Can't create Bugzilla bug for product '%s' with no versions. 
(P4DTI-5252) Can't create Bugzilla bug without version field. 
(P4DTI-5263) Can't create Bugzilla bug: product '%s' has no version '%s'. 
(P4DTI-5285) Can't create Bugzilla bug with invalid groupset '%s'. 
(P4DTI-530X) Can't create Bugzilla bug with bug_status '%s' and no resolution. 
(P4DTI-5310) Can't create Bugzilla bug with field '%s'. 
(P4DTI-5321) Can't create Bugzilla bug without reporter field.

Edit the Perforce job so that it can be translated to a new bug that does satisfy the constraint.

Change your translate_jobspec and prepare_issue functions so that they satisfy the constraint. Then

If you were migrating, re-run the migration starting from the job which couldn't be migrated [GDR 2001-11-14, 4.10].

Otherwise, restart the replicator (see section 5.5) and update the job so that it is replicated again (by running a command like p4 job -o JOBNAME | p4 job -i.

(P4DTI-5354) '%s' not a Bugzilla group.

(P4DTI-5376) User %d is disabled, so cannot edit bug %d.

(P4DTI-5387) User 0 cannot edit bug %d.

(P4DTI-5398) Can't create Bugzilla bug with reporter 0.

(P4DTI-5401) Can't change Bugzilla field '%s' to 0.

(P4DTI-6142) No transition from state '%s' to state '%s'.

Either change the state in a legal way, or modify the TeamTrack workflow so that there is a transition corresponding to the desired state change.

(P4DTI-6153) No login id in TeamTrack's USERS table corresponding to replicator's login id '%s'.

(P4DTI-6164) No LAST_CHANGE record for this replicator.

(P4DTI-6175) TeamTrack database version %d is not supported by the P4DTI. The minimum supported version is %d.

(P4DTI-6186) Incorrect date in Perforce: '%s' is not in the format 'YYYY/mm/dd HH:MM:SS'.

(P4DTI-6197) Incorrect time in Perforce: '%s' is not in the format 'H:MM:SS'.

(P4DTI-6211) No TeamTrack entity in table '%s' with id %d. 
(P4DTI-6233) No TeamTrack selection name for selection id '%d'. 
(P4DTI-6266) No state name for TeamTrack state %d.

(P4DTI-6222) No TeamTrack entity in table '%s' with name '%s'. 
(P4DTI-6244) No TeamTrack selection for field '%s' corresponding to Perforce selection '%s'. 
(P4DTI-6277) Perforce state '%s' is unknown. 
(P4DTI-6426) No TeamTrack state corresponding to Perforce state '%s'.

(P4DTI-6255) No Perforce state corresponding to TeamTrack state '%s'.

This can happen if you've added a state to the TeamTrack workflow. In that case you need to restart the replicator (see section 5.5).

It can also happen if you've set use_deleted_selections to 0 but there's an issue in a deleted state. See that configuration parameter for advice.

(P4DTI-6288) No TeamTrack state in project '%s' corresponding to Perforce state '%s'.

Set the job to a state that is legal for its project, or modify the TeamTrack workflow so that the desired state is legal in the project.

If you get this message frequently, this is a sign that your TeamTrack workflow is too complicated for people to follow accurately in Perforce. You should consider unifying the workflows for different projects, so that developers aren't confused about which states are legal for which jobs.

(Of course, it would be nice if Perforce only showed the states that are legal for the project to which the job belongs. But that requires Perforce to understand the full details of TeamTrack project, workflow and state definitions. Perforce does not have this capability.)

(P4DTI-6335) The TeamTrack field %s is append-only: you're not allowed to edit previous comments.

(P4DTI-6404) Can't submit new issue to TeamTrack: SUBMITTER %d is unknown.

A Perforce user couldn't be translated to a TeamTrack user. Fix the problem and try again. See section 3.5, "User accounts".

The replicator's guessing algorithm has failed (it looks in the P4DTI-user, Owner and User fields in the job, if any, takes the first user it finds, and translates that). If so, you'll need to supply a valid user in your prepare_issue function; then

If you were migrating, re-run the migration starting from the job which couldn't be migrated [GDR 2001-11-14, 4.10].

Otherwise, restart the replicator (see section 5.5) and update the job so that it is replicated again (by running a command like p4 job -o JOBNAME | p4 job -i.

(P4DTI-6415) Submitted new issue to TeamTrack with issue id %05d, but couldn't find it in the database.

(P4DTI-7043) Perforce client changelevel %d is not supported by P4DTI. Client must be at changelevel %d or above.

(P4DTI-7054) The command '%s' didn't report a recognizable version number. Check your setting for the 'p4_client_executable' parameter.

(P4DTI-7076) The Perforce client exited with error code %d. The server might be down; the server address might be incorrect; or your Perforce licence might have expired.

(P4DTI-7065) %s The Perforce client exited with error code %d. 
(P4DTI-7087) %s

(P4DTI-7098) The Perforce interface does not support the operating system '%s'.

(P4DTI-7101) Jobspec fields '%s' and '%s' have the same number %d.

(P4DTI-8341) The Perforce server changelevel %d is not supported by the P4DTI. See the P4DTI release notes for Perforce server versions supported by the P4DTI. 
(P4DTI-8352) The Perforce command 'p4 info' didn't report a recognisable version.

(P4DTI-8363) P4DTI fields not found in Perforce jobspec.

(P4DTI-8727) Issue '%s' should be replicated but is not. 
(P4DTI-8738) Issue '%s' should be replicated to job '%s' but that job either does not exist or is not replicated. 
(P4DTI-8749) Issue '%s' is replicated to job '%s' but that job is replicated to issue '%s'. 
(P4DTI-875X) Job '%s' would need the following set of changes in order to match issue '%s': %s. 
(P4DTI-8760) Job '%s' has associated filespec '%s' but there is no corresponding filespec for issue '%s'. 
(P4DTI-8771) Issue '%s' has associated filespec '%s' but there is no corresponding filespec for job '%s'. 
(P4DTI-8782) Change %s fixes job '%s' but there is no corresponding fix for issue '%s'. 
(P4DTI-8793) Change %d fixes issue '%s' but there is no corresponding fix for job '%s'. 
(P4DTI-8807) Change %s fixes job '%s' with status '%s', but change %d fixes issue '%s' with status '%s'. 
(P4DTI-8818) Job '%s' is marked as being replicated to issue '%s' but that issue is being replicated to job '%s'. 
(P4DTI-8829) Job '%s' is marked as being replicated to issue '%s' but that issue either doesn't exist or is not being replicated by this replicator. 
(P4DTI-8862) 1 inconsistency found. 
(P4DTI-8873) %d inconsistencies found. 
(P4DTI-8884) Asked for issue '%s' but got an error instead. 
(P4DTI-8895) Job '%s' has a date field in the wrong format: %s.

If polling doesn't make the databases consistent, then you can either make them consistent by editing the offending jobs, or by refreshing the Perforce jobs (section 9.2, "Refreshing jobs in Perforce").

If that doesn't work, contact Perforce support (see section 11.1, "Troubleshooting").

(P4DTI-891X) Error (%s): %s

(P4DTI-9060) Defect tracker '%s' does not support migration of Perforce users.

(P4DTI-913X) Error in P4DTI logger: %s

(P4DTI-9242) Expected translate_jobspec to return a dictionary, but instead it returned %s.

(P4DTI-10037) TeamTrack version %s is not supported by the P4DTI.

(P4DTI-10059) MySQLdb version '%s' (release '%s') detected. This release is incompatible with the P4DTI.

(P4DTI-1006X) MySQLdb version '%s' (release '%s') detected. This release is not supported by the P4DTI, but may work.

(P4DTI-10106) Fatal error in P4DTI service: %s.

(P4DTI-10172) An attempt to write a log message to standard output failed.

The remedy is to start the replicator with the startup script, as described in section 5.6.1, "Running automatically on Unix", or to redirect the standard output to somewhere safe, for example

python run.py > /dev/null

11.3. Other Error messages

Insecure $ENV{BASH_ENV} while running with -T switch at ./processmail line %d

_mysql.InternalError: (3, "Error writing file '%s' (Errcode: 28)")

_mysql.OperationalError: (1045, "Access denied for user: '%s@%s' (Using password: NO)")

_mysql.OperationalError: (1045, "Access denied for user: '%s@%s' (Using password: YES)")

_mysql.OperationalError: (1049, "Unknown database '%s'")

_mysql.OperationalError: (2003, "Can't connect to MySQL server on '%s' (111)")

• The MySQL server is down.
• The MySQL server is configured to serve on a different port number

_mysql.OperationalError: (2005, "Unknown MySQL Server Host '%s' (2)")

_mysql.OperationalError: (2006, 'MySQL server has gone away')

Perforce error: Can't create a new user - over licence quota

This might be because you changed the p4_user parameter but didn't delete the old userid.

Perforce error: Error detected at line %d. Value for field 'Options' must be one of noallwrite/allwrite,noclobber/clobber,nocompress/compress,unlocked/locked,nomodtime/modtime,normdir/rmdir.

Perforce error: Error detected at line %d. Value for field '%s' must be one of %s.

This can happen if you've added an option to a field in the defect tracker. In that case you need to restart the replicator (see section 5.5).

It can also happen if you've set use_deleted_selections to 0 but there's an issue with a deleted option. See that configuration parameter for advice.

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

socket.error: (10222, 'invalid argument')

socket.error: host not found

TeamShare API error: ERROR: (no message from the TeamShare API)

This might be because you are using TeamTrack version 5.0 or later, but you specified teamtrack_version = "4.5". Check your setting for the teamtrack_version parameter.

TeamShare API error: ERROR: Unable to find transition 0.

TeamShare API error: SERVER_ERROR: Authentication Failed. Invalid user id or password

TeamShare API error: SERVER_ERROR: Access Denied. You do not have API connect privileges.

TeamShare API error: SERVER_ERROR: Server error: -1.

Or your TeamTrack server may be running on a secure web server (its address starts https:). The P4DTI does not support TeamTrack on a secure web server.

TeamShare API error: SOCKET_CONNECT_FAILED: Socket Connect failed.

TeamShare API error: SOCKET_READ_ERROR: Authentication Failed. No user information.

Set up TeamTrack to accept authentication information from the HTTP header. In the TeamTrack Administrator, choose Options > Settings; choose the Server tab; click the "Accept Info From Browser/Header" checkbox. (Note that you do not have to turn off the "Accept Info From Form/URL/Cookie" checkbox. If both boxes are checked, TeamTrack tries to get the authentication information from a cookie first, and the HTTP header second.)

TeamShare API error: SOCKET_READ_ERROR: Socket error.

The replicator user may not have the "Connect using the API" privilege. Check the privileges for the replicator user: see section 5.3.2, "Creating a TeamTrack user for the replicator".

A. References

B. Document History

C. Glossary

D. Table of commands

This document is copyright © 2001 Perforce Software, Inc. All rights reserved.

Redistribution and use of this document in any form, with or without modification, is permitted provided that redistributions of this document retain the above copyright notice, this condition and the following disclaimer.

This document is provided by the copyright holders and contributors "as is" and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall the copyright holders and contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this document, even if advised of the possibility of such damage.