<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-US" lang="en-US">
<head>
<title>Perforce Defect Tracking Integration Administrator's Guide</title>
</head>
<body bgcolor="#FFFFFF" text="#000000" link="#000099" vlink="#660066" alink="#FF0000">
<div align="center">
<p><i><a href="http://www.ravenbrook.com/project/p4dti/">Perforce Defect Tracking Integration Project</a></i></p>
<hr />
<h1>Perforce Defect Tracking Integration Administrator's Guide</h1>
<address>
<a href="mailto:rb@ravenbrook.com">Richard Brooksby</a>,
<a href="http://www.ravenbrook.com/">Ravenbrook Limited</a>,
2000-08-10
</address>
</div>
<h2><a id="section-Contents" name="section-Contents">Contents</a></h2>
<ul>
<li><a href="#section-1">1. Introduction</a></li>
<li>
<a href="#section-2">2. Overview of the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr></a>
<ul>
<li><a href="#section-2.1">2.1. Installation, configuration, and maintenance</a></li>
<li><a href="#section-2.2">2.2. How the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> works</a></li>
<li><a href="#section-2.3">2.3. Limitations: will the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> work for your organization?</a></li>
</ul>
</li>
<li>
<a href="#section-3">3. Prerequisites for installing the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr></a>
<ul>
<li><a href="#section-3.1">3.1. Required experience</a></li>
<li><a href="#section-3.2">3.2. Perforce prerequisites</a></li>
<li><a href="#section-3.3">3.3. TeamTrack prerequisites</a></li>
<li><a href="#section-3.4">3.4. Bugzilla prerequisites</a></li>
<li><a href="#section-3.5">3.5. User accounts</a></li>
</ul>
</li>
<li>
<a href="#section-4">4. Installing the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr></a>
<ul>
<li><a href="#section-4.1">4.1. Upgrading from an earlier version</a></li>
<li><a href="#section-4.2">4.2. Windows installation</a></li>
<li><a href="#section-4.3">4.3. Linux installation</a></li>
<li><a href="#section-4.4">4.4. Solaris installation</a></li>
</ul>
</li>
<li>
<a href="#section-5">5. Configuring the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>, Perforce, and the defect tracker</a>
<ul>
<li><a href="#section-5.1">5.1. <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> configuration</a></li>
<li><a href="#section-5.2">5.2. Perforce configuration</a></li>
<li><a href="#section-5.3">5.3. TeamTrack configuration</a></li>
<li><a href="#section-5.4">5.4. Bugzilla configuration</a></li>
<li><a href="#section-5.5">5.5. Starting and stopping the replicator manually</a></li>
<li><a href="#section-5.6">5.6. Setting up the replicator to start automatically</a></li>
<li><a href="#section-5.7">5.7. Advanced configuration</a></li>
</ul>
</li>
<li>
<a href="#section-6">6. Migrating your defect tracking data to the integrated system</a>
<ul>
<li><a href="#section-6.1">6.1. Migrating from the defect tracker</a></li>
<li><a href="#section-6.2">6.2. Creating issues in Perforce</a></li>
<li><a href="#section-6.3">6.3. Migrating to the defect tracker from Perforce jobs</a></li>
</ul>
</li>
<li>
<a href="#section-7">7. Testing the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr></a>
<ul>
<li><a href="#section-7.1">7.1. Taking a single step</a></li>
<li><a href="#section-7.2">7.2. Testing your configuration</a></li>
<li><a href="#section-7.3">7.3. Checking data consistency</a></li>
</ul>
</li>
<li><a href="#section-8">8. Training and documentation</a></li>
<li>
<a href="#section-9">9. Maintaining the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr></a>
<ul>
<li> <a href="#section-9.1">9.1. Maintaining the configuration</a> </li>
<li> <a href="#section-9.2">9.2. Refreshing jobs in Perforce</a> </li>
</ul>
</li>
<li><a href="#section-10">10. Uninstalling the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr></a></li>
<li>
<a href="#section-11">11. Troubleshooting and error messages</a>
<ul>
<li><a href="#section-11.1">11.1. Troubleshooting</a></li>
<li><a href="#section-11.2">11.2. Error messages by identifier</a></li>
<li><a href="#section-11.3">11.3. Other error messages</a></li>
</ul>
</li>
<li><a href="#section-A">A. References</a></li>
<li><a href="#section-B">B. Document history</a></li>
<li><a href="#section-C">C. Glossary</a></li>
<li><a href="#section-D">D. Table of commands</a></li>
</ul>
<h2><a id="section-1" name="section-1">1. Introduction</a></h2>
<p>This manual is the Perforce Defect Tracking Integration Administrator's Guide. It explains how to install, configure, maintain, and administer the Perforce Defect Tracking Integration (<abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>).</p>
<p> This document is intended for <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> administrators. Ordinary users of the defect tracker or Perforce should read the <a href="../ug/index.html"><cite>Perforce Defect Tracking Integration User's Guide</cite></a>. (For ideas on how to train your users on the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>, see <a href="#section-8">section 8, "Training and documentation"</a>.) </p>
<p> This guide does not describe the basics of using the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>, Perforce, or the defect tracker. Read the <a href="../ug/index.html"><cite>Perforce Defect Tracking Integration User's Guide</cite></a> to understand the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> from a user's perspective. </p>
<h2><a id="section-2" name="section-2">2. Overview of the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr></a></h2>
<h3><a id="section-2.1" name="section-2.1">2.1. Installation, configuration, and maintenance</a></h3>
<p>To install and run the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>, you must:</p>
<ol>
<li> Get and install the required software (<a href="#section-3">section 3</a>). </li>
<li> Ensure you have met the procedural prerequisites for Perforce and your defect tracker (<a href="#section-3">section 3</a>). </li>
<li> Download and install the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> software (<a href="#section-4">section 4</a>). </li>
<li> Configure the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> software (<a href="#section-5">section 5</a>). </li>
<li> Migrate defect tracking data from your defect tracker to the integrated system (<a href="#section-6">section 6</a>). </li>
<li> Test the installation (<a href="#section-7">section 7</a>). </li>
<li> Train the users (<a href="#section-8">section 8</a>). </li>
<li> Go live (<a href="#section-9">section 9</a>). </li>
<li> Maintain the installation (<a href="#section-9">section 9</a>). </li>
</ol>
<h3><a id="section-2.2" name="section-2.2">2.2. How the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> works</a></h3>
<p> The <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> 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 <cite><a href="http://www.perforce.com/perforce/doc.011/manuals/p4guide/">Perforce Command Line User's Guide</a></cite>. </p>
<p> Perforce has a mechanism for linking jobs to changelists (the <code class="command">p4 fix</code> command), to enable you to record the work done for a particular reason. The <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> 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. </p>
<p>The <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> 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. </p>
<p><a href="#figure-1">Figure 1</a> shows how the replicator communicates with the defect tracking server and the Perforce server.</p>
<p>The replicator maintains a one-to-one relationship between <dfn>issues</dfn> in the defect tracker's database and <dfn>jobs</dfn> in the Perforce repository. (An <dfn>issue</dfn> 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.</p>
<p>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. </p>
<p>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: </p>
<ul>
<li> The person who changed the job in Perforce. </li>
<li> The owner of the defect tracker issue. </li>
<li> The <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> administrator. </li>
</ul>
<p>Most defect trackers have an idea of <dfn>workflow</dfn>--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.</p>
<p> 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. </p>
<p> <a href="#figure-1">Figure 1</a> shows how the replicator connects to the Perforce and defect tracker servers. </p>
<div align="center">
<p> <a id="figure-1" name="figure-1">Figure 1</a>. The replication architecture </p>
<img src="replication.gif" alt="Diagram of the replication architecture" width="503" height="335" />
</div>
<h3><a id="section-2.3" name="section-2.3">2.3. Limitations: will the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> work for your organization?</a></h3>
<p> The <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>
won't work well for every organization. In particular, it has the
following limitations: </p>
<ul>
<li><p> If you're using TeamTrack and your workflow is very complex
then the <abbr title="Perforce Defect Tracking
Integration">P4DTI</abbr> may make mistakes when translating actions
in Perforce into actions in TeamTrack. </p>
<p> (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 <abbr
title="Perforce Defect Tracking Integration">P4DTI</abbr> 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 <a href="#note-workflows">section 3.3.2, item 6</a> for
details of workflows that the <abbr title="Perforce Defect Tracking
Integration">P4DTI</abbr> may have trouble with.) </p></li>
<li><p> 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. </p>
<p> (This is because the <abbr title="Perforce Defect Tracking
Integration">P4DTI</abbr> 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 <abbr
title="Perforce Defect Tracking Integration">P4DTI</abbr> because that
would introduce inconsistencies.) </p></li>
</ul>
<h2><a id="section-3" name="section-3">3. Prerequisites for installing the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr></a></h2>
<h3><a id="section-3.1" name="section-3.1">3.1. Required experience</a></h3>
<p>To administer the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>, you must have the following experience: </p>
<ul>
<li> Perforce: You need at least two months of Perforce administration experience, including a working knowledge of Perforce's command line interface. Read both the <cite><a href="http://www.perforce.com/perforce/doc.011/manuals/p4guide/">Perforce Command Line User's Guide</a></cite> and the <cite><a href="http://www.perforce.com/perforce/doc.011/manuals/p4sag/">Perforce System Administrator's Guide</a></cite>. </li>
<li> 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 <<a href="http://www.python.org/doc/current/tut/tut.html">http://www.python.org/doc/current/tut/tut.html</a>>. </li>
<li> 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 <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>. </li>
</ul>
<h3><a id="section-3.2" name="section-3.2">3.2. Perforce prerequisites</a></h3>
<h4><a id="section-3.2.1" name="section-3.2.1">3.2.1. Software prerequisites</a></h4>
<p> Before installing the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>, you must obtain and install the following software: </p>
<ol>
<li> Perforce server software of version 2000.2 or later. You can download server and client upgrades from the Perforce FTP server at <<a href="ftp://ftp.perforce.com/pub/perforce/">ftp://ftp.perforce.com/pub/perforce/</a>>. Be sure to read the release notes (available from <<a href="http://www.perforce.com/">http://www.perforce.com/</a>>) before you install. <a href="http://www.perforce.com/perforce/support.html">Contact Perforce technical support</a> if you need help. </li>
<li> Perforce client software of version 2001.1 or later for every <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> user who uses Perforce, and for the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> itself. </li>
<li> Perforce licenses for every defect tracker user who is going to work in Perforce. </li>
<li> A <i>background user license</i> for the replicator. This is a license for an automatic process, rather than a person. Perforce provides background licenses free of charge; <a href="http://www.perforce.com/perforce/contact.html">contact Perforce Customer Service</a> to get one. </li>
</ol>
<h4><a id="section-3.2.2" name="section-3.2.2">3.2.2. Procedural prerequisites</a></h4>
<p> Before installing the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>, you must do the following: </p>
<ol>
<li> Back up your Perforce repository. For instructions, see the <cite><a href="http://www.perforce.com/perforce/doc.011/manuals/p4sag/">Perforce System Administrator's Guide</a></cite>. </li>
<li> Copy out of Perforce any jobs that you want to keep. The <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> 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 <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>. For more information, see <a href="#section-5.2.3">section 5.2.3, "Deleting Perforce jobs"</a>. You might want to enter any active jobs into the defect tracking system. </li>
<li> Determine the address and port number of your Perforce server. You will need this information when you configure the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> in <a href="#section-5">section 5, "Configuring the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>, Perforce, and the defect tracker"</a>. </li>
</ol>
<p> 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 <a href="../aag/index.html#section-4">section 4, "Migrating to the defect tracker from Perforce jobs"</a>, of the <cite><a href="../aag/index.html">Perforce Defect Tracking Integration Advanced Administrator's Guide</a></cite>. </p>
<div class="teamtrack">
<h3><a id="section-3.3" name="section-3.3">3.3. TeamTrack prerequisites</a></h3>
<h4><a id="section-3.3.1" name="section-3.3.1">3.3.1. Software prerequisites</a></h4>
<p> Before installing the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>, you must obtain and install the following software: </p>
<ol>
<li> TeamTrack version 4.5, 5.0, or 5.5. <strong>Use of TeamTrack
versions before 5.5 is deprecated</strong>. TeamTrack is available
for download from TeamShare's web site <<a
href="http://www.teamshare.com/">http://www.teamshare.com/</a>>.
<strong>Note that TeamTrack 5.01 and 5.02 are not supported: you
should upgrade to TeamTrack 5.5.</strong> </li>
<li> TeamTrack licenses for every Perforce user who will create or own issues. </li>
<li> An extra TeamTrack license for the replicator. TeamShare provides licenses free of charge for this purpose. Contact your TeamShare sales representative to get one. </li>
<li> Python 2.0 for Windows, installed on the TeamTrack server
machine. Python 2.0 is available from <<a
href="http://www.ravenbrook.com/project/p4dti/import/2000-10-18/Python-2.0/BeOpen-Python-2_0.exe">http://www.ravenbrook.com/project/p4dti/import/2000-10-18/Python-2.0/BeOpen-Python-2_0.exe</a>>.
<strong>The TeamTrack integration will not work with Python versions
other than 2.0</strong>.</li>
<li> The Python interface to Windows, installed on the TeamTrack server machine. This is available from <<a href="http://www.ravenbrook.com/project/p4dti/import/2001/python-win32all-138/win32all-138.exe">http://www.ravenbrook.com/project/p4dti/import/2001/python-win32all-138/win32all-138.exe</a>>. You can omit this step if you don't plan to do either of the following:
<ul>
<li>log activity to the Windows Event Log; see the <a href="#config-use_windows_event_log"><code class="source">use_windows_event_log</code></a> configuration parameter </li>
<li>run the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> as a Windows service; see <a href="#section-5.6.2">section 5.6.2</a>.</li>
</ul>
</li>
</ol>
<h4><a id="section-3.3.2" name="section-3.3.2">3.3.2. Procedural prerequisites</a></h4>
<p> Before installing the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>, you must do the following: </p>
<ol>
<li> Back up your TeamTrack database. For instructions, see the <cite>TeamTrack Administrator Manual</cite> for your version of TeamTrack. </li>
<li> Obtain Administrator-level access to the TeamTrack server machine. </li>
<li> Ensure you have at least 5MB of free disk space for the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>, plus space for logs. </li>
<li> Ensure that your TeamTrack users do <em>not</em> have TeamShare's SourceBridge plug-in installed. SourceBridge prevents the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> from working properly. </li>
<li> Ensure that your TeamTrack server is not running on a secure web
server (that is, the URL to connect to TeamTrack starts with <code
class="source">http:</code>, not <code class="source">https:</code>).
The <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> does
not support TeamTrack running on a secure web server. </li>
<li> <a id="note-workflows" name="note-workflows">Check the
workflows</a> defined in your TeamTrack database to make sure that they
are compatible with the <abbr title="Perforce Defect Tracking
Integration">P4DTI</abbr>. In particular:
<ol type="a">
<li><p> Make sure you don't have two states with the same name in a
project. For example, when using the workflow in <a
href="#figure-2">figure 2</a>, there's no way for a developer using
Perforce to resolve the issue and assign it to the tester. The
developer would normally resolve the issue by changing the status field,
but in this workflow the status field doesn't change. Rename states so
that the workflow has unique state names. For example, in <a
href="#figure-2">figure 2</a>, name the second "Assigned" state
"Resolved". </p>
<div align="center">
<p> <a id="figure-2" name="figure-2">Figure 2</a>. Workflow with two
states with the same name </p>
<img src="workflow1.gif" alt="Workflow with two states with the same
name" width="485" height="52" />
</div></li>
<li><p> Make sure you don't have two transitions between the same two
states, in the same direction. For example, when using the workflow in
<a href="#figure-3">figure 3</a>, when the developer using Perforce
changes the state of the job from "assigned" to "resolved", the <abbr
title="Perforce Defect Tracking Integration">P4DTI</abbr> has no way to
work out which transition to apply. Simplify the workflow so that the
transition can be deduced from the start state and the end state. For
example, in <a href="#figure-3">figure 3</a> you could have a single
transition from "Assigned" to "Resolved" and require developers to
specify how they resolved the problem in a field in the defect. </p>
<div align="center">
<p> <a id="figure-3" name="figure-3">Figure 3</a>. Workflow with two
transitions between the same two states (in the same direction) </p>
<img src="workflow2.gif" alt="Workflow with two transitions between the
same two states (in the same direction)" width="486" height="98" />
</div></li>
<li><p> Make sure you don't have "Update" transitions (transitions from
a state to itself) that are necessary in your workflow. For example,
when using the workflow in <a href="#figure-4">figure 4</a>, there's no
way for the developer to cause the "Assign to tester" transition using
Perforce. The developer would normally resolve the issue by changing
the status field, but in this workflow the status field doesn't change.
Simplify the workflow so that it doesn't rely on "Update"
transitions. </p>
<div align="center">
<p> <a id="figure-4" name="figure-4">Figure 4</a>. Workflow with a
necessary "Update" transition </p>
<img src="workflow3.gif" alt="Workflow with a necessary
"Update" transition" width="349" height="103" />
</div></li>
</ol>
<p> In fact these problems only matter when the problematic part of the
workflow needs to be carried out in Perforce. As long as you know that
the problematic part of workflow is only carried out in TeamTrack, then
the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> will
work fine. </p>
</li>
<li> Ensure that the workflows defined in your TeamTrack database do not
require more than one transition in quick succession from Perforce. The
<abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> can't
infer more than one transition at once. To avoid this problem, design
your workflow only with only single steps in Perforce. This is usually
straightforward: developers using the Perforce interface only need to
transition issues from, for example, "assigned" to "closed", and not
through a series of states. </li>
<li> Ensure that your users have the same e-mail address in TeamTrack
and in Perforce; see <a href="#section-3.5">section 3.5, "Matching
users"</a>. </li>
</ol>
</div>
<div class="bugzilla">
<h3><a id="section-3.4" name="section-3.4">3.4. Bugzilla prerequisites</a></h3>
<h4><a id="section-3.4.1" name="section-3.4.1">3.4.1. Software prerequisites</a></h4>
<p> Before installing the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>, you must obtain and install the following software: </p>
<ol>
<li>
<p> Bugzilla 2.10, 2.12, 2.14, 2.14.1, 2.14.4 or 2.16.1. <strong>Use
of versions prior to 2.14.4 or 2.16.1 is deprecated. On Microsoft
Windows, only Bugzilla 2.14.4 is supported.</strong></p>
<p>You can download Bugzilla 2.14.4 from <<a href="http://www.ravenbrook.com/project/p4dti/import/2002-09-30/bugzilla-2.14.4/bugzilla-2.14.4.tar.gz">http://www.ravenbrook.com/project/p4dti/import/2002-09-30/bugzilla-2.14.4/bugzilla-2.14.4.tar.gz</a>>, or Bugzilla 2.16.1 from <<a href="http://www.ravenbrook.com/project/p4dti/import/2002-09-30/bugzilla-2.16.1/bugzilla-2.16.1.tar.gz">http://www.ravenbrook.com/project/p4dti/import/2002-09-30/bugzilla-2.16.1/bugzilla-2.16.1.tar.gz</a>>.</p>
<p>Installing Bugzilla on Microsoft Windows is a complex procedure requiring changes to the Bugzilla sources -- see <a href="http://www.ravenbrook.com/project/p4dti/import/2002-09-30/bugzilla-2.14.4/bugzilla-2.14.4/docs/html/win32.html">section 3.6, "Win32 Installation Notes"</a> of the Bugzilla Guide [<a href="http://www.ravenbrook.com/project/p4dti/import/2002-09-30/bugzilla-2.14.4/bugzilla-2.14.4/docs/html/">Bugzilla 2002-09-30</a>].</p>
<p><strong>Note:</strong> If you've changed your Bugzilla code, see <a
href="#section-5.4.1">section 5.4.1, "Patching Bugzilla"</a>.</p>
</li>
<li><p>MySQL 3.22.19 or later. You must be using Bugzilla with this
database manager. Note that Bugzilla itself may not work with MySQL
3.23.29.</p></li>
<li><p> Python 1.5.2 or later, installed on the P4DTI server machine.
On Microsoft Windows, you will require Python 2.0 or later.</p>
<p>An <abbr title="Red Hat Package Manager">RPM</abbr> of Python 1.5.2
for RedHat Linux 7.3 is available from <<a
href="http://www.ravenbrook.com/project/p4dti/import/1999-04-13/python-1.5.2/python-1.5.2-38.i386.rpm">http://www.ravenbrook.com/project/p4dti/import/1999-04-13/python-1.5.2/python-1.5.2-38.i386.rpm</a>>. An <abbr
title="Red Hat Package Manager">RPM</abbr> of Python 1.5.2 for RedHat
Linux 6.2 is available from <<a
href="http://www.ravenbrook.com/project/p4dti/import/1999-04-13/python-1.5.2/python-1.5.2-13.i386.rpm">http://www.ravenbrook.com/project/p4dti/import/1999-04-13/python-1.5.2/python-1.5.2-13.i386.rpm</a>>.</p>
<p>Python 2.0 for Microsoft Windows is available from <<a
href="http://www.ravenbrook.com/project/p4dti/import/2000-10-18/Python-2.0/BeOpen-Python-2_0.exe">http://www.ravenbrook.com/project/p4dti/import/2000-10-18/Python-2.0/BeOpen-Python-2_0.exe</a>>.</p>
<p>Python 1.5.2 sources are available from <<a
href="http://www.ravenbrook.com/project/p4dti/import/1999-04-13/python-1.5.2/python-1.5.2.tar.gz">http://www.ravenbrook.com/project/p4dti/import/1999-04-13/python-1.5.2/python-1.5.2.tar.gz</a>>.
If you build Python from the sources, note that the <abbr
title="Perforce Defect Tracking Integration">P4DTI</abbr> requires the
optional <code class="source">syslog</code> module.</p>
</li>
<li><p>The MySQLdb Python package, release 0.2.2 to 0.9.1, installed
on the P4DTI server machine. (MySQLdb releases before 0.2.2 are known
to be incompatible with the <abbr title="Perforce Defect Tracking
Integration">P4DTI</abbr>; MySQLdb releases after 0.9.1 haven't been
tested.)</p>
<p>An <abbr title="Red Hat Package Manager">RPM</abbr> of MySQLdb
0.9.1 for RedHat Linux 7.3 is available from <<a
href="http://www.ravenbrook.com/project/p4dti/import/2001-10-16/MySQL-python-0.9.1/MySQL-python-0.9.1-1.i386.rpm">http://www.ravenbrook.com/project/p4dti/import/2001-10-16/MySQL-python-0.9.1/MySQL-python-0.9.1-1.i386.rpm</a>>.
This RPM requires the Python mx RPM, available from <<a href="http://www.ravenbrook.com/project/p4dti/import/2001-12-20/egenix-mx-base-2.0.3/mx-2.0.3-1.i386.rpm">http://www.ravenbrook.com/project/p4dti/import/2001-12-20/egenix-mx-base-2.0.3/egenix-mx-base-2.0.3.tar.gz</a>>.</p>
<p>On Microsoft Windows, you need MySQL-Python 0.9.1 for Win32 and
Python 2.0. This is available from <<a
href="http://www.ravenbrook.com/project/p4dti/import/2001-10-16/MySQL-python-0.9.1/MySQL-python-0.9.1.win32-py2.0.exe">http://www.ravenbrook.com/project/p4dti/import/2001-10-16/MySQL-python-0.9.1/MySQL-python-0.9.1.win32-py2.0.exe</a>>. </p>
<p>MySQLdb 0.9.1 sources are available from <<a
href="http://www.ravenbrook.com/project/p4dti/import/2001-10-16/MySQL-python-0.9.1/MySQL-python-0.9.1.tar.gz">http://www.ravenbrook.com/project/p4dti/import/2001-10-16/MySQL-python-0.9.1/MySQL-python-0.9.1.tar.gz</a>>.
</p></li>
<li><p>(On Microsoft Windows only) The Python interface to Windows,
installed on the P4DTI server machine. This is available from <<a
href="http://www.ravenbrook.com/project/p4dti/import/2001/python-win32all-138/win32all-138.exe">http://www.ravenbrook.com/project/p4dti/import/2001/python-win32all-138/win32all-138.exe</a>>. You
can omit this step if you don't plan to do either of the following:
<ul> <li>log activity to the Windows Event Log; see the <a
href="#config-use_windows_event_log"><code
class="source">use_windows_event_log</code></a> configuration
parameter </li> <li>run the <abbr title="Perforce Defect Tracking
Integration">P4DTI</abbr> as a Windows service; see <a
href="#section-5.6.2">section 5.6.2</a>.</li> </ul></p> </li>
<li><p> (On Microsoft Windows only) A "patch" utility, required for
part of the installation procedure (see <a
href="#section-5.4.1">section 5.4.1, "Patching Bugzilla"</a>). Other
supported operating systems already include a patch utility. Various
packages of utilities for Microsoft Windows also include a patch
utility. If you do not have a patch utility, you can download one
from <<a
href="http://www.ravenbrook.com/project/p4dti/import/2001-11-13/UnxUtils/UnxUtils/usr/local/wbin/patch.exe">http://www.ravenbrook.com/project/p4dti/import/2001-11-13/UnxUtils/UnxUtils/usr/local/wbin/patch.exe</a>>.
This is version 2.5 of GNU patch, compiled for Windows, distributed as
part of the UnxUtils package under the GNU General Public License from
<<a
href="http://unxutils.sourceforge.net/">http://unxutils.sourceforge.net/</a>>.</p></li>
</ol>
<h4><a id="section-3.4.2" name="section-3.4.2">3.4.2. Procedural prerequisites</a></h4>
<p> Before installing the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>, you must do the following: </p>
<ol>
<li> Back up your Bugzilla database. For instructions, see the <cite><a href="http://www.mysql.com/documentation/mysql/">MySQL manual</a></cite> (under "Database Backups", section 21.2 at the time of writing). </li>
<li> Back up your Bugzilla code. As part of <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> installation, you must apply a patch to Bugzilla (for details, see <a href="#section-5.4.1">section 5.4.1, "Patching Bugzilla"</a>). A backup of your Bugzilla code is useful if you need to uninstall the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>. </li>
<li> Ensure that you have at least 2MB of free disk space on the Bugzilla server machine for the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>, plus space for logs. </li>
<li> Ensure that your users have the same e-mail address in Bugzilla and
in Perforce; see <a href="#section-3.5">section 3.5, "Matching
users"</a>. </li>
</ol>
</div>
<h3><a id="section-3.5" name="section-3.5">3.5. User accounts</a></h3>
<p> You must ensure that the <abbr title="Perforce Defect Tracking
Integration">P4DTI</abbr> can work out how users in the defect tracker
correspond to users in Perforce, as follows: </p>
<ol>
<li><p> Create an account in each system for each user who needs to use
the integrated system. </p>
<div class="bugzilla"><p> If you are using Bugzilla, create a Bugzilla
account for every user in Perforce. </p></div>
<div class="teamtrack"><p> 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.) </p></div></li>
<li><p> Make sure that each user has the same e-mail address in the
defect tracker and in Perforce. The <abbr title="Perforce Defect
Tracking Integration">P4DTI</abbr> uses e-mail address to match up users
between the two systems. </p>
<p> (This is necessary in the Bugzilla integration where your e-mail
address is used as your userid. In the TeamTrack integration this
allows the <abbr title="Perforce Defect Tracking
Integration">P4DTI</abbr> to work in organizations where users have been
assigned different userids in the two systems.) </p>
<div class="bugzilla"><p> The <abbr title="Perforce Defect Tracking
Integration">P4DTI</abbr> supports Bugzilla's "emailsuffix" feature
(once you've applied the Bugzilla patch, <a
href="#section-5.4.1">section 5.4.1</a>, and turned on the <abbr
title="Perforce Defect Tracking Integration">P4DTI</abbr> extensions in
Bugzilla, <a href="#section-5.4.3">section 5.4.3</a>), 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". </p></div></li>
</ol>
<p> There are three problems that can occur if the <abbr title="Perforce
Defect Tracking Integration">P4DTI</abbr> can't match up users properly:
</p>
<ul>
<li> If someone changes a job in Perforce but the <abbr title="Perforce
Defect Tracking Integration">P4DTI</abbr> 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). </li>
<li> If two users in Perforce have the same e-mail address then the
<abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> chooses
the first one it finds when matching a user from the defect tracker.
This choice is likely to be incorrect. </li>
<li> If two users in TeamTrack have the same e-mail address then the
<abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> chooses
the first one it finds when matching a user from Perforce. This choice
is likely to be incorrect. </li>
</ul>
<p> To help you prevent these problems, each time you start the <abbr
title="Perforce Defect Tracking Integration">P4DTI</abbr> it sends an
e-mail message to the administrator containing a report listing the
unmatched and duplicate users. An example report is shown in <a
href="#figure-5">figure 5</a>. Read reports you receive and fix the
problems. </p>
<div align="center">
<p> <a id="figure-5" name="figure-5">Figure 5. Example e-mail sent when
the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>
starts</a> </p>
<table border="1" cellpadding="5" cellspacing="0"><tr><td>
<table border="0" cellpadding="0" cellspacing="0">
<tr valign="top"><td></td>
<td><pre>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.</pre></td>
</tr><tr valign="top"><td><a name="para-3.5.1" id="para-3.5.1" href="#note-3.5.1">1</a> </td>
<td><pre>(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</pre></td></tr>
<tr valign="top"><td><a name="para-3.5.2" id="para-3.5.2" href="#note-3.5.2">2</a> </td>
<td><pre>(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</pre></td></tr>
<tr valign="top"><td><a name="para-3.5.3" id="para-3.5.3" href="#note-3.5.3">3</a> </td>
<td><pre>(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</pre></td></tr>
<tr valign="top"><td><a name="para-3.5.4" id="para-3.5.4" href="#note-3.5.4">4</a> </td>
<td><pre>(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</pre></td></tr>
</table></td></tr></table>
</div>
<p> Notes on <a href="#figure-5">figure 5</a>: </p>
<ol>
<li><p> <a id="note-3.5.1" name="note-3.5.1" href="#para-3.5.1">Section
1</a> 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. </p></li>
<li><p> <a id="note-3.5.2" name="note-3.5.2" href="#para-3.5.2">Section
2</a> lists defect tracker users that couldn't be matched to a user in
Perforce. </p></li>
<li><p> <a id="note-3.5.3" name="note-3.5.3" href="#para-3.5.3">Section
3</a> lists Perforce users with duplicate e-mail addresses. In this
case, if a defect tracker user had the address
<ndl@company.domain> then the <abbr title="Perforce Defect
Tracking Integration">P4DTI</abbr> may have matched them wrongly. Give
each Perforce user a distinct e-mail address. </p></li>
<li><p> <a id="note-3.5.4" name="note-3.5.4" href="#para-3.5.4">Section
4</a> lists defect tracker users with duplicate e-mail addresses. Give
each defect tracker user a distinct e-mail address. </p></li>
</ol>
<h2><a id="section-4" name="section-4">4. Installing the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr></a></h2>
<p> <strong>Note:</strong> You might want to practice installing and configuring the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> 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 <cite><a href="http://www.perforce.com/perforce/doc.011/manuals/p4sag/">Perforce System Administrator's Guide</a></cite>. </p>
<p> The <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> 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 <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> on the same machine as the defect tracker's server. The rest of this manual assumes that you do this. </p>
<h3><a id="section-4.1" name="section-4.1">4.1. Upgrading from an earlier version</a></h3>
<p> For instructions on how to upgrade from an earlier version of the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>, see the <code class="filename">readme.txt</code> file.</p>
<h3><a id="section-4.2" name="section-4.2">4.2. Windows installation</a></h3>
<p> The <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> is distributed as a self-extracting executable called <code class="filename">p4dti-<i><abbr title="Defect Tracker">DT</abbr></i>-<i>RELEASE</i>.exe</code> (where <i><abbr title="Defect Tracker">DT</abbr></i> is the defect tracker, such as "teamtrack", and <i>RELEASE</i> is the release number, such as "1.0.2"). </p>
<p> To install the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>, run this executable on the machine where the defect tracker server is installed. The installer unpacks the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> into <code class="directory">C:\Program Files\P4DTI-<i>RELEASE</i>\</code> by default. </p>
<h3><a id="section-4.3" name="section-4.3">4.3. Linux installation</a></h3>
<p> The <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> is distributed as an <abbr title="Red Hat Package Manager">RPM</abbr> called <code class="filename">p4dti-<i>RELEASE</i>-1.i386.rpm</code> where <i><abbr title="Defect Tracker">DT</abbr></i> is the defect tracker, such as "bugzilla", and <i>RELEASE</i> is the release number, such as "1.0.2"). </p>
<p> To install the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>, run the following command as root on the defect tracker server machine: </p>
<blockquote><code class="command">rpm -i p4dti-<i>RELEASE</i>-1.i386.rpm</code></blockquote>
<p> This installs the <abbr title="Perforce Defect Tracking
Integration">P4DTI</abbr> files into <code
class="filename">/opt/p4dti</code> and a startup script in the <code
class="filename">/etc/rc.d/init.d</code> directory. </p>
<p> If you prefer not to use RPMs, you can follow the procedure in <a href="#section-4.4">section 4.4, "Solaris installation"</a>. </p>
<h3><a id="section-4.4" name="section-4.4">4.4. Solaris installation</a></h3>
<p> The <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> is distributed as a gzipped tar file called <code class="filename">p4dti-<i><abbr title="Defect Tracker">DT</abbr></i>-<i>RELEASE</i>.tar.gz</code> (where <i><abbr title="Defect Tracker">DT</abbr></i> is the defect tracker, such as "bugzilla", and <i>RELEASE</i> is the release number, such as "1.0.2"). </p>
<p> To install the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>, unpack this tar file on the defect tracker server machine, using the following command: </p>
<blockquote><code class="command">gunzip -c p4dti-<i><abbr title="Defect Tracker">DT</abbr></i>-<i>RELEASE</i>.tar.gz | tar xvf -</code></blockquote>
<p> You must determine where to put the files. You can put the files wherever you want. </p>
<h2><a id="section-5" name="section-5">5. Configuring the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>, Perforce, and the defect tracker</a></h2>
<p> Work through the subsections in the order in which they appear. <strong>Do <em>not</em> attempt to run the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> until you have reached the end of this section, or you might end up with a non-working installation.</strong> </p>
<p> To configure the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> with Perforce and your defect tracker, you must: </p>
<ol>
<li> Specify the location of servers and the data you want to appear in Perforce (<a href="#section-5.1">section 5.1</a>). </li>
<li> Configure Perforce to accept information from the replicator and, optionally, install triggers to implement access controls (<a href="#section-5.2">section 5.2</a>). </li>
<li> Enable <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> features, such as the ability to view fixes and changelists from the defect tracker user interface (<a href="#section-5.3">section 5.3</a> for TeamTrack or <a href="#section-5.4">section 5.4</a> for Bugzilla). </li>
<li> Start the replicator (<a href="#section-5.5">section 5.5</a>). </li>
<li> Set up the replicator to start automatically when the server machine is rebooted (<a href="#section-5.6">section 5.6</a>). </li>
</ol>
<h3><a id="section-5.1" name="section-5.1">5.1. <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> configuration</a></h3>
<p> To configure the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>, you edit definitions of Python variables in the file <code class="filename">config.py</code> in the installation directory. Edit these definitions according to the notes below. All variables in the file must have a value. </p>
<h4><a id="section-5.1.1" name="section-5.1.1">5.1.1. Essential configuration parameters</a></h4>
<h4><a id="config-dt_name" name="config-dt_name"><code class="source">dt_name</code></a></h4>
<p> Description: The name of the defect tracking system you're integrating with. Either <code class="source">"TeamTrack"</code> or <code class="source">"Bugzilla"</code>. </p>
<p> Example: <code class="source">"TeamTrack"</code> </p>
<p> Make sure that this variable is set to the appropriate value for your defect tracker. </p>
<h4> <a id="config-administrator_address" name="config-administrator_address"><code class="source">administrator_address</code></a> </h4>
<p> Description: The e-mail address of the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> administrator. </p>
<p> Example: <code class="source">"p4dti-admin@company.domain"</code> </p>
<p> The replicator sends error reports to this address. If this is
<code class="source">None</code>, then the replicator never sends
e-mail.</p>
<h4> <a id="config-p4_port" name="config-p4_port"><code class="source">p4_port</code></a> </h4>
<p> Description: The address and port of the Perforce server with which the replicator communicates. </p>
<p> Example: <code class="source">"perforce.company.domain:1666"</code> </p>
<h4> <a id="config-p4_user" name="config-p4_user"><code class="source">p4_user</code></a> </h4>
<p> Description: The userid that the replicator uses to log in to the Perforce server. </p>
<p> Example: <code class="source">"p4dti-replicator0"</code> </p>
<p> For information about how the replicator logs in to Perforce, see <a href="#section-5.2">section 5.2, "Perforce configuration"</a>. If you want to add more replicators later, incorporate the replicator identifier (<a href="#config-rid">rid</a>) into this userid. </p>
<h4> <a id="config-p4_password" name="config-p4_password"><code class="source">p4_password</code></a> </h4>
<p> Description: The password the replicator uses to log in to the Perforce server. If there is no password, specify "" (empty quotes). </p>
<p> Example: <code class="source">""</code> </p>
<p> For information about how the replicator logs in to Perforce, see <a href="#section-5.2">section 5.2, "Perforce configuration"</a>. </p>
<h4> <a id="config-replicator_address" name="config-replicator_address"><code class="source">replicator_address</code></a> </h4>
<p> Description: The e-mail address from which the replicator sends e-mail. This address is used in the "From" field of e-mail that the replicator sends. </p>
<p> Example: <code class="source">"p4dti-replicator0@company.domain"</code> </p>
<p> To make it easier for users to get assistance, make this address an alias for the <a href="#config-administrator_address">administrator e-mail address (<code class="source">administrator_address</code>)</a>. If you are using Bugzilla, this e-mail address is also used for the replicator's Bugzilla account; see <a href="#section-5.4.2">section 5.4.2, "Creating a Bugzilla user for the replicator"</a>. </p>
<h4> <a id="config-smtp_server" name="config-smtp_server"><code class="source">smtp_server</code></a> </h4>
<p> Description: The address of the SMTP server that the replicator uses to send e-mail. </p>
<p> Example: <code class="source">"smtp.company.domain"</code> </p>
<p> If this is <code class="source">None</code>, then the replicator
never sends e-mail. </p>
<p> If you need to run the <abbr title="Perforce Defect Tracking
Integration">P4DTI</abbr> 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 <code class="source">smtp_server=None</code> so
that the replicator doesn't try to send e-mail. </p>
<h4> <a id="config-start_date" name="config-start_date"><code class="source">start_date</code></a> </h4>
<p> Description: The starting point in time for replication. </p>
<p> Example: <code class="source">"2001-02-10 00:00:00"</code> </p>
<p> Issues modified after this date are replicated; issues unchanged
after this date are ignored. Must be a string in the form <code
class="source">"YYYY-MM-DD HH:MM:SS"</code>. </p>
<div class="teamtrack">
<h4><a id="section-5.1.2" name="section-5.1.2">5.1.2. TeamTrack configuration parameters</a></h4>
<h4> <a id="config-teamtrack_version" name="config-teamtrack_version"><code class="source">teamtrack_version</code></a> </h4>
<p> Description: The major version of your TeamTrack server. Specify
<code class="source">"4.5"</code> for TeamTrack 4.5, or <code
class="source">"5.0"</code> for TeamTrack 5.0 or later. </p>
<p> Example: <code class="source">"5.0"</code> </p>
<h4> <a id="config-closed_state-TeamTrack" name="config-closed_state-TeamTrack"><code class="source">closed_state</code></a> </h4>
<p> Description: The TeamTrack that maps to the "closed" state in
Perforce. Specify <code class="source">None</code> if you want the
ordinary state mapping rules to apply. </p>
<p> (Note that you must write <code class="source">None</code>
literally, not the string <code class="source">"None"</code>, which
would mean the state called "None"). </p>
<p> Example: <code class="source">"Resolved"</code>. </p>
<p> Mapping the TeamTrack state that developers use most often to the
"closed" state in Perforce makes using the <abbr title="Perforce Defect
Tracking Integration">P4DTI</abbr> easier for the developers, because
the Perforce user interfaces make it easier to fix a job to "closed"
than any other state. However, if your workflow already has a state
called "Closed", then you can't use this feature; set <code
class="source">closed_state = None</code>. </p>
<h4> <a id="config-replicated_fields-TeamTrack" name="config-replicated_fields-TeamTrack"><code class="source">replicated_fields</code></a> </h4>
<p> Description: A list of the database names of TeamTrack fields that are replicated in Perforce. The fields <code>STATE</code>, <code>OWNER</code>, and <code>TITLE</code> are always replicated, so omit those fields when setting this variable. </p>
<p> Example: <code class="source">["DESCRIPTION", "PRIORITY", "SEVERITY"]</code> </p>
<p> For advice on which fields to replicate, and how to find out their database names, see <a href="#section-5.1.5">section 5.1.5, "Choosing which fields to replicate"</a>. </p>
<h4> <a id="config-teamtrack_server" name="config-teamtrack_server"><code class="source">teamtrack_server</code></a> </h4>
<p> Description: The TeamTrack server hostname and (optionally) port
with which the replicator communicates. </p>
<p> Example: <code class="source">"teamtrack.company.domain"</code> </p>
<p> If your TeamTrack server is reached on a path other than <code
class="source">/tmtrack/tmtrack.dll?</code> then you must specify the
full path to the server in this variable. For example, <code
class="source">"http://server.company.domain/infosystem/teamtrack/tmtrack.dll?"</code>. </p>
<p> (Note that <code class="source">"localhost"</code> won't work, even
if the TeamTrack server is on the local host.) </p>
<h4> <a id="config-teamtrack_user" name="config-teamtrack_user"><code class="source">teamtrack_user</code></a> </h4>
<p> Description: The user name that the replicator uses to log into TeamTrack. </p>
<p> Example: <code class="source">"P4DTI-replicator0"</code> </p>
<p> See <a href="#section-5.3.2">section 5.3.2, "Creating a TeamTrack user for the replicator"</a>. </p>
<h4> <a id="config-teamtrack_password" name="config-teamtrack_password"><code class="source">teamtrack_password</code></a> </h4>
<p> Description: The password that the replicator uses to log into TeamTrack. If there is no password, specify "" (empty quotes). </p>
<p> Example: <code class="source">""</code> </p>
<p> See <a href="#section-5.3.2">section 5.3.2, "Creating a TeamTrack user for the replicator"</a>. </p>
</div>
<div class="bugzilla">
<h4><a id="section-5.1.3" name="section-5.1.3">5.1.3. Bugzilla configuration parameters</a></h4>
<h4> <a id="config-closed_state-Bugzilla" name="config-closed_state-Bugzilla"><code class="source">closed_state</code></a> </h4>
<p> Description: The Bugzilla state that maps to the "closed" state in Perforce. Specify <code class="source">None</code> if you want the ordinary state mapping rules to apply. </p>
<p> (Note that you must write <code class="source">None</code>
literally, not the string <code class="source">"None"</code>, which
would mean the state called "None"). </p>
<p> Example: <code class="source">"RESOLVED"</code>. </p>
<p> Mapping the defect tracker state that developers use most often to
the "closed" state in Perforce makes using the <abbr title="Perforce
Defect Tracking Integration">P4DTI</abbr> easier for the developers,
because the Perforce user interfaces make it easier to fix a job to
"closed" than any other state. If you specify a <code
class="source">closed_state</code> then the "CLOSED" state in Bugzilla
maps to "bugzilla_closed" in Perforce. </p>
<h4><a id="config-replicated_fields-Bugzilla" name="config-replicated_fields-Bugzilla"><code class="source">replicated_fields</code></a></h4>
<p> Description: A list of the names of Bugzilla fields that are replicated in Perforce. The fields "bug_status", "short_desc", "assigned_to" and "resolution" are always replicated, so omit those fields when setting this variable. </p>
<p> Example: <code class="source">["longdesc", "priority", "bug_severity", "product"]</code> </p>
<p> For advice on which fields to replicate, see <a href="#section-5.1.5">section 5.1.5, "Choosing which fields to replicate"</a>. </p>
<h4> <a id="config-dbms_host" name="config-dbms_host"><code class="source">dbms_host</code></a> </h4>
<p> Description: The host on which the Bugzilla MySQL server is running. </p>
<p> Example: <code class="source">"localhost"</code> </p>
<p> Set this value to <code class="source">"localhost"</code> if the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> and the Bugzilla MySQL server run on the same machine. </p>
<h4> <a id="config-dbms_port" name="config-dbms_port"><code class="source">dbms_port</code></a> </h4>
<p> Description: The port number on the <a
href="#config-dbms_host">database host (<code
class="source">dbms_host</code>)</a>, on which the Bugzilla MySQL server
listens. </p>
<p> Example: <code class="source">3306</code> </p>
<p> MySQL normally listens on port 3306. Change this setting only if you have set up MySQL differently. Note that this parameter is expressed as a number, not as a string. </p>
<h4> <a id="config-dbms_database" name="config-dbms_database"><code class="source">dbms_database</code></a> </h4>
<p> Description: The name of the MySQL database in which Bugzilla stores its data. </p>
<p> Example: <code class="source">"bugs"</code> </p>
<p> Normally set to <code class="source">"bugs"</code> during Bugzilla installation (see the Bugzilla documentation for <a href="http://www.ravenbrook.com/project/p4dti/import/2000-05-09/bugzilla-2.10/bugzilla-2.10/README">2.10</a>, <a href="http://www.ravenbrook.com/project/p4dti/import/2001-04-27/bugzilla-2.12/bugzilla-2_12/docs/html/readme.unix.html#AEN379">2.12</a>, <a href="http://www.ravenbrook.com/project/p4dti/import/2001-08-29/bugzilla-2.14/bugzilla-2.14/docs/html/stepbystep.html#AEN768">2.14</a>, <a href="http://www.ravenbrook.com/project/p4dti/import/2002-01-05/bugzilla-2.14.1/bugzilla-2.14.1/docs/html/stepbystep.html#AEN768">2.14.1</a>, <a href="http://www.ravenbrook.com/project/p4dti/import/2002-09-30/bugzilla-2.14.4/bugzilla-2.14.4/docs/html/stepbystep.html#AEN768">2.14.4</a>, <a href="http://www.ravenbrook.com/project/p4dti/import/2002-09-30/bugzilla-2.16.1/bugzilla-2.16.1/docs/html/stepbystep.html#AEN741">2.16.1</a>). Change this setting only if you have set up Bugzilla differently. </p>
<h4> <a id="config-dbms_user" name="config-dbms_user"><code class="source">dbms_user</code></a> </h4>
<p> Description: The user name that the replicator uses to log in to MySQL to use the Bugzilla database. </p>
<p> Example: <code class="source">"bugs"</code> </p>
<p> Bugzilla normally logs in to MySQL as user <code class="source">"bugs"</code> (see the Bugzilla documentation for <a href="http://www.ravenbrook.com/project/p4dti/import/2000-05-09/bugzilla-2.10/bugzilla-2.10/README">2.10</a>, <a href="http://www.ravenbrook.com/project/p4dti/import/2001-04-27/bugzilla-2.12/bugzilla-2_12/docs/html/readme.unix.html#AEN379">2.12</a>, <a href="http://www.ravenbrook.com/project/p4dti/import/2001-08-29/bugzilla-2.14/bugzilla-2.14/docs/html/stepbystep.html#AEN768">2.14</a>, <a href="http://www.ravenbrook.com/project/p4dti/import/2002-01-05/bugzilla-2.14.1/bugzilla-2.14.1/docs/html/stepbystep.html#AEN768">2.14.1</a>, <a href="http://www.ravenbrook.com/project/p4dti/import/2002-09-30/bugzilla-2.14.4/bugzilla-2.14.4/docs/html/stepbystep.html#AEN768">2.14.4</a>, <a href="http://www.ravenbrook.com/project/p4dti/import/2002-09-30/bugzilla-2.16.1/bugzilla-2.16.1/docs/html/stepbystep.html#AEN741">2.16.1</a>). Change this setting only if you have configured Bugzilla differently, or if you want to set up the replicator to log in as a different user. </p>
<h4> <a id="config-dbms_password" name="config-dbms_password"><code class="source">dbms_password</code></a> </h4>
<p> Description: The password that the replicator uses to log in to MySQL to use the Bugzilla database. </p>
<p> Example: <code class="source">""</code> </p>
<p> Bugzilla normally logs in with no password (see the Bugzilla documentation for <a href="http://www.ravenbrook.com/project/p4dti/import/2000-05-09/bugzilla-2.10/bugzilla-2.10/README">2.10</a>, <a href="http://www.ravenbrook.com/project/p4dti/import/2001-04-27/bugzilla-2.12/bugzilla-2_12/docs/html/readme.unix.html#AEN379">2.12</a>, <a href="http://www.ravenbrook.com/project/p4dti/import/2001-08-29/bugzilla-2.14/bugzilla-2.14/docs/html/stepbystep.html#AEN768">2.14</a>, <a href="http://www.ravenbrook.com/project/p4dti/import/2002-01-05/bugzilla-2.14.1/bugzilla-2.14.1/docs/html/stepbystep.html#AEN768">2.14.1</a>, <a href="http://www.ravenbrook.com/project/p4dti/import/2002-09-30/bugzilla-2.14.4/bugzilla-2.14.4/docs/html/stepbystep.html#AEN768">2.14.4</a>, <a href="http://www.ravenbrook.com/project/p4dti/import/2002-09-30/bugzilla-2.16.1/bugzilla-2.16.1/docs/html/stepbystep.html#AEN741">2.16.1</a>). Change this setting if you have configured Bugzilla differently, or you want to set up the replicator to log in as a different user and use a password. </p>
<h4> <a id="config-bugzilla_directory" name="config-bugzilla_directory"><code class="source">bugzilla_directory</code></a> </h4>
<p> Description: The directory in which Bugzilla is installed, or <code class="source">None</code> if you don't want e-mail processed. </p>
<p> Example: <code class="source">"/home/httpd/html/bugzilla"</code> </p>
<p> Bugzilla sends e-mail to its users when it notices that a bug has been changed. If the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> is running on the Bugzilla server, it is able to use Bugzilla's <code class="filename">processmail</code> script to promptly send e-mail in the same way. This configuration parameter allows the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> to locate <code class="filename">processmail</code>. Set it to <code class="source">None</code> if the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> is not running on the Bugzilla server or if you don't want the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> to send these e-mail messages. </p>
</div>
<h4><a id="section-5.1.4" name="section-5.1.4">5.1.4. Other configuration parameters</a></h4>
<p> These parameters support advanced or rarely-used features. Most
organizations can leave these parameters at their default values, at
least to start with, and then set them later if necessary. </p>
<h4> <a id="config-changelist_url" name="config-changelist_url"><code class="source">changelist_url</code></a> </h4>
<p> Description: A format string used to build a URL for a changelist.
Specify <code class="source">None</code> if there are no URLs for
changelists. </p>
<p> 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. <a href="#figure-6">Figure 6</a> shows how this works in
Bugzilla. </p>
<p> The value must be a format string valid for passing to <code
class="source">sprintf()</code>; it must have one <code
class="source">%d</code> format specifier, for which the change number
is substituted. (Note that because the value gets passed to <code
class="source">sprintf()</code>, you must double other percent signs.)
</p>
<p> In order to use this feature, you must have a web application that
can provide information about changelists. Applications suitable for
this include: </p>
<ul>
<li><p> <a
href="http://www.perforce.com/perforce/products/p4web.html">P4Web</a>.
To allow any user to follow the link from the defect tracker to P4Web,
you need to run it in "browse mode". See the <a
href="http://www.perforce.com/perforce/doc.011/manuals/p4web/index.html">P4Web
documentation</a> for details. </p>
<p> For P4Web, set <code class="source">changelist_url</code> to
something like <code
class="source">"http://info.company.domain:8080/%d?ac=10"</code>.</p></li>
<li><p><a
href="http://public.perforce.com:8080/@ra%3Ds@/public/perforce/utils/perfbrowse/">Perfbrowse</a>.
For Perfbrowse, set <code class="source">changelist_url</code> to
something like <code
class="source">"http://info.company.domain/cgi/perfbrowse.cgi?@describe+%d"</code>.
</p></li>
</ul>
<div align="center">
<p> <a id="figure-6" name="figure-6">Figure 6</a>. Effect of <a
href="#config-changelist_url"><code
class="source">changelist_url</code></a> and <a
href="#config-job_url"><code class="source">job_url</code></a> </p>
<img src="changelist_url.gif" alt="Figure showing the effect of the
changelist_url and job_url configuration parameters on the fixes table
in Bugzilla." width="507" height="324" />
</div>
<h4> <a id="config-job_url" name="config-job_url"><code class="source">job_url</code></a> </h4>
<p> Description: A format string used to build a URL for job descriptions. Specify <code class="source">None</code> if there is no URL for job descriptions. </p>
<p> 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. <a href="#figure-6">Figure 6</a> shows how this works in
Bugzilla. </p>
<p> Example: <code class="source">"http://info.company.domain/cgi/perfbrowse.cgi?@job+%s"</code> </p>
<p> The string is a format string valid for passing to <code class="source">sprintf()</code>; it must have one <code class="source">%s</code> format specifier, for which the job name is substituted. (Note that because it gets passed to <code class="source">sprintf()</code>, you must double other percent signs.) </p>
<h4> <a id="config-log_file" name="config-log_file"><code class="source">log_file</code></a> </h4>
<p> Description: The name of the replicator's log file. If <code
class="source">None</code>, messages aren't logged to any file. (Note
that you must write <code class="source">None</code> literally, not the
string <code class="source">"None"</code>, which would mean the file
called "None"). </p>
<p> Example: <code class="source">"C:\\Program Files\\P4DTI-<i>RELEASE</i>\\p4dti.log"</code> </p>
<p> The replicator generates log messages to record its actions. These log messages are sent to all of the following locations: </p>
<ul>
<li> The standard output of the replicator. </li>
<li> The system log (under UNIX and Linux, if <a href="#config-use_system_log"><code class="source">use_system_log</code></a> is 1). </li>
<li> The event log (under Microsoft Windows, if <a href="#config-use_windows_event_log"><code class="source">use_windows_event_log</code></a> is 1). </li>
<li> The file specified by the <code class="source">log_file</code> configuration parameter (unless it's <code class="source">None</code>). </li>
</ul>
<h4> <a id="config-log_level" name="config-log_level"><code class="source">log_level</code></a> </h4>
<p> Description: The minimum priority level of messages to log.
Messages with this priority or a higher priority appear in the
replicator's log.</p>
<p> Example: <code class="source">message.INFO</code> </p>
<p> This parameter must be one of these constants: </p>
<table>
<tr valign="top">
<td><code class="source">message.ERR</code></td>
<td>Errors.</td>
</tr>
<tr valign="top">
<td><code class="source">message.WARNING</code></td>
<td>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'.".</td>
</tr>
<tr valign="top">
<td><code class="source">message.NOTICE</code></td>
<td>Significant but expected events. For example, "Job 'BUG00001' overwritten by issue 'BUG00001'.".</td>
</tr>
<tr valign="top">
<td><code class="source">message.INFO</code></td>
<td>Informational messages. For example, "Replicating issue '123' to job 'BUG000123'."</td>
</tr>
<tr valign="top">
<td><code class="source">message.DEBUG</code></td>
<td>Debugging messages. For example, "Perforce command: 'p4 -G -u p4dti-replicator0 -p perforce:1666 job -o BUG00001'."</td>
</tr>
</table>
<h4> <a id="config-p4_client_executable" name="config-p4_client_executable"><code class="source">p4_client_executable</code></a> </h4>
<p> Description: The location of the Perforce client executable. </p>
<p> Example: <code class="source">"C:\\Program Files\\Perforce\\p4.exe"</code> </p>
<p> 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 <code class="source">"C:\\Program Files\\Perforce\\p4.exe"</code>. On UNIX it might be just <code class="source">"p4"</code>. </p>
<p> The client executable named by this parameter must be of version
2000.2 or later (run the command <code class="command">p4 -V</code> 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 <a href="#message-Perforce-Error-2">(P4DTI-7087)
Value for field 'Options' must be one of ...</a>. </p>
<h4> <a id="config-p4_server_description" name="config-p4_server_description"><code class="source">p4_server_description</code></a> </h4>
<p> Description: A description of the Perforce server. This might be used by the defect tracker to show which Perforce server an issue is replicated to. </p>
<p> Example: <code class="source">"Hardware development group Perforce server"</code> </p>
<h4> <a id="config-poll_period" name="config-poll_period"><code class="source">poll_period</code></a> </h4>
<p> Description: The period of time between the end of one poll of the
servers and the start of the next, in seconds. </p>
<p> Example: <code class="source">10</code> </p>
<h4> <a id="config-prepare_issue" name="config-prepare_issue"><code
class="source">prepare_issue(issue, job)</code></a> </h4>
<p> Description: A function that prepares a new issue for submission to
the defect tracker by providing values for all the required fields. </p>
<p> See <a href="../aag/index.html#section-3">section 3,
"Allowing users to create issues in Perforce"</a> in the <a
href="../aag/index.html"><cite>Perforce Defect Tracking
Advanced Administrator's Guide</cite></a> for the full details. </p>
<h4> <a id="config-replicate_p" name="config-replicate_p"><code class="source">replicate_p(issue)</code></a> </h4>
<p> Description: A function that selects which issues to start
replicating. Normally, the <abbr title="Perforce Defect Tracking
Integration">P4DTI</abbr> replicates all issues created or modified
after the <code class="source"><a
href="#config-start_date">start_date</a></code>, but you can modify this
function to further restrict the issues. </p>
<p> See <a href="../aag/index.html#section-2">section 2,
"Select the issues to replicate"</a> in the <a
href="../aag/index.html"><cite>Perforce Defect Tracking
Advanced Administrator's Guide</cite></a> for the full details. </p>
<h4> <a id="config-replicate_job_p" name="config-replicate_job_p"><code class="source">replicate_job_p(job)</code></a> </h4>
<p> Description: A function that selects which jobs in Perforce to
replicate. Normally, the <abbr title="Perforce Defect Tracking
Integration">P4DTI</abbr> ignores jobs created in Perforce, but you can
provide this function to allow users to create jobs in Perforce and have
them replicated to the defect tracker. </p>
<p> See <a href="../aag/index.html#section-3">section 3,
"Allowing users to create issues in Perforce"</a> in the <a
href="../aag/index.html"><cite>Perforce Defect Tracking
Advanced Administrator's Guide</cite></a> for the full details. </p>
<h4> <a id="config-rid" name="config-rid"><code class="source">rid</code></a> </h4>
<p> Description: The replicator identifier. </p>
<p> Example: <code class="source">"replicator0"</code> </p>
<p> Must be 32 characters or less, start with a letter or underscore, and consist only of letters, numbers, and underscores. </p>
<p> 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; <code class="source">"replicator0"</code> is a good choice since it allows you to add more replicators later. </p>
<p> 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. </p>
<h4> <a id="config-sid" name="config-sid"><code class="source">sid</code></a> </h4>
<p> Description: The Perforce server identifier. </p>
<p> Example: <code class="source">"perforce0"</code> </p>
<p> 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. </p>
<h4> <a id="config-use_deleted_selections" name="config-use_deleted_selections"><code class="source">use_deleted_selections</code></a> </h4>
<p> Description: If this is 1, deleted TeamTrack states and selections
appear as options for corresponding fields in Perforce. If this is
<code class="source">0</code>, they don't appear in the Perforce jobspec
or in drop-down menus in P4Win. </p>
<p> Example: <code class="source">0</code> </p>
<p> Warning: It is risky to set this to <code class="source">0</code> 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 <code class="source">use_deleted_selections</code> is
<code class="source">0</code> then these issues can't be replicated to Perforce. If
this happens, you'll see errors like these: </p>
<ul>
<li><p><a href="#message-P4DTI-6255">(P4DTI-6255) No Perforce state
corresponding to TeamTrack state 'spong'.</a></p>
<p> 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. </p></li>
<li><p><a href="#message-Perforce-Error-3">(P4DTI-7087) Value for field
'Severity' must be one of Critical/High/Medium/Low/(None).</a></p>
<p> 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. </p></li>
</ul>
<h4> <a id="config-use_perforce_jobnames" name="config-use_perforce_jobnames"><code class="source">use_perforce_jobnames</code></a> </h4>
<p> Description: Determines whether the replicator uses Perforce-style
jobnames. </p>
<p> If this parameter is 1, the <abbr title="Perforce Defect Tracking
Integration">P4DTI</abbr> 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. </p>
<p> If this parameter is 0 (the default), the <abbr title="Perforce
Defect Tracking Integration">P4DTI</abbr> tries to match the defect
tracker's names for the issues it replicates. <span
class="teamtrack">In the TeamTrack integration, jobs are called
BUG00001, ENH00002, and so on.</span> <span class="bugzilla">In the
Bugzilla integration, jobs are called bug1, bug2, and so on.</span>
</p>
<p> Example: <code class="source">1</code> </p>
<p> If you change this setting, the <abbr title="Perforce Defect
Tracking Integration">P4DTI</abbr> doesn't rename existing jobs, but new
jobs get the style of name you requested. </p>
<h4> <a id="config-use_windows_event_log" name="config-use_windows_event_log"><code class="source">use_windows_event_log</code></a> </h4>
<p>(Windows only)</p>
<p>Description: The replicator logs activity to the Windows event
log if (and only if) this is 1. </p>
<p> Example: <code class="source">1</code> </p>
<p> If you set this to 1, you must make sure to install the Python
interface to Windows (item 5 in <a href="#section-3.3.1">section
3.3.1</a>, "Software prerequisites"). </p>
<p> Regardless of the setting of this parameter, the replicator also
logs activity to to the standard output and to the <a
href="#config-log_file">log file (<code
class="source">log_file</code>)</a>. </p>
<p> The replicator can generate very many log messages. So if you set
this parameter to 1, either specify "Overwrite events as needed" in the
Windows Event Viewer on the machine running the replicator, or else set
the <a href="#config-log_level"><code
class="source">log_level</code></a> to a restrictive value like <code
class="source">message.LOG_WARNING</code>. </p>
<h4> <a id="config-use_system_log" name="config-use_system_log"><code
class="source">use_system_log</code></a> </h4>
<p>(Unix/Linux only).</p>
<p> Description: The replicator logs activity to the Unix or Linux
system log (syslog) if (and only if) this is 1. </p>
<p> Example: <code class="source">1</code> </p>
<p> Regardless of the setting of this parameter, the replicator also
logs activity to to the standard output and to the <a
href="#config-log_file">log file (<code
class="source">log_file</code>)</a>. </p>
<h4><a id="section-5.1.5" name="section-5.1.5">5.1.5. Choosing which fields to replicate</a></h4>
<p> Here's some advice on which fields to replicate: </p>
<ul>
<li> Replicate any fields that the developers are required to fill in, or they won't be able to use Perforce to do their work. </li>
<li> Replicate any other fields that the developers need to do their work; see the suggestions below.</li>
<li> 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 <code>FIX_DESCRIPTION</code> field for developers to explain what they did. Now that you're running the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>, 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. </li>
<li> 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. </li>
</ul>
<div class="teamtrack">
<p> If you're using TeamTrack's sample database, you might want to replicate the following fields: </p>
<ul>
<li> <code>DESCRIPTION</code>, so that developers can understand what the problem is. </li>
<li> <code>SEVERITY</code>, so that developers can prioritize their work. </li>
<li> <code>PRIORITY</code>, so that developers can prioritize their work. </li>
</ul>
<p> To find out the database name of a TeamTrack field, follow these steps: </p>
<ol>
<li>Run the TeamTrack administrator. (Under Windows, choose Start > Programs > TeamShare > TeamTrack Administrator.) </li>
<li>Select the <span class="gui">Projects</span> tab.</li>
<li>Select a project from the list (but not the base project).</li>
<li>Click the <span class="gui">Edit</span> button.</li>
<li>Select the <span class="gui">Default Fields</span> tab.</li>
<li>Select the desired field from the list.</li>
<li>Click the <span class="gui">Edit</span> button.</li>
<li>Look in the <span class="gui">Database Field Name</span> field in the dialog.</li>
</ol>
<p> <a href="#table-1">Table 1</a> shows the field types in TeamTrack
and indicates which ones may be replicated by the <abbr title="Perforce
Defect Tracking Integration">P4DTI</abbr>. </p>
<div align="center">
<p> <a id="table-1" name="table-1">Table 1.</a> Supported field types in
TeamTrack </p>
<table border="1" cellspacing="0" cellpadding="5">
<tr valign="top">
<th>Field type</th>
<th>Field contents</th>
<th>Replicable by <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>?</th>
</tr>
<tr valign="top">
<td><code class="source">NUMERIC</code></td>
<td>Numeric field, integer or floating-point</td>
<td>Yes</td>
</tr>
<tr valign="top">
<td><code class="source">TEXT</code></td>
<td>Text field up to 255 characters</td>
<td>Yes</td>
</tr>
<tr valign="top">
<td><code class="source">MEMO</code></td>
<td>Memo field</td>
<td>Yes</td>
</tr>
<tr valign="top">
<td><code class="source">DATETIME</code></td>
<td>Date/Time field</td>
<td>Yes</td>
</tr>
<tr valign="top">
<td><code class="source">SELECTION</code></td>
<td>Drop down selection field, one selectable</td>
<td>Yes</td>
</tr>
<tr valign="top">
<td><code class="source">BINARY</code></td>
<td>Binary (two-state) field</td>
<td>Yes</td>
</tr>
<tr valign="top">
<td><code class="source">STATE</code></td>
<td>The system-defined state field</td>
<td>Yes</td>
</tr>
<tr valign="top">
<td><code class="source">USER</code></td>
<td>A drop down selection field containing user names</td>
<td>Yes</td>
</tr>
<tr valign="top">
<td><code class="source">PROJECT</code></td>
<td>System-defined project field</td>
<td>Yes</td>
</tr>
<tr valign="top">
<td><code class="source">SUMMATION</code></td>
<td>Calculated summation fields</td>
<td>No</td>
</tr>
<tr valign="top">
<td><code class="source">MULTIPLE_SELECTION</code></td>
<td>Multi-select selection field</td>
<td>No</td>
</tr>
<tr valign="top">
<td><code class="source">CONTACT</code></td>
<td>Contact selection field</td>
<td>No</td>
</tr>
<tr valign="top">
<td><code class="source">COMPANY</code></td>
<td>Company selection field</td>
<td>Yes</td>
</tr>
<tr valign="top">
<td><code class="source">INCIDENT</code></td>
<td>Incident selection field</td>
<td>No</td>
</tr>
<tr valign="top">
<td><code class="source">PRODUCT</code></td>
<td>Product selection field</td>
<td>Yes</td>
</tr>
<tr valign="top">
<td><code class="source">SERVICEAGREEMENT</code></td>
<td>Service Agreement</td>
<td>Yes</td>
</tr>
<tr valign="top">
<td><code class="source">FOLDER</code></td>
<td>Folder link selection field</td>
<td>No</td>
</tr>
<tr valign="top">
<td><code class="source">KEYWORDLIST</code></td>
<td>Keyword multi-select field</td>
<td>No</td>
</tr>
<tr valign="top">
<td><code class="source">PRODUCTLIST</code></td>
<td>Product multi-select field</td>
<td>No</td>
</tr>
<tr valign="top">
<td><code class="source">PROBLEM</code></td>
<td>Problem selection field.</td>
<td>No</td>
</tr>
<tr valign="top">
<td><code class="source">RESOLUTION</code></td>
<td>Resolution selection field</td>
<td>No</td>
</tr>
<tr valign="top">
<td><code class="source">MERCHANDISE</code></td>
<td>Merchandise selection field</td>
<td>No</td>
</tr>
<tr valign="top">
<td><code class="source">RELATIONAL</code></td>
<td>Relational selection field</td>
<td>No</td>
</tr>
<tr valign="top">
<td><code class="source">SUBRELATIONAL</code></td>
<td>Sub-relational selection field</td>
<td>No</td>
</tr>
<tr valign="top">
<td><code class="source">SYSTEM</code></td>
<td>System field</td>
<td>No</td>
</tr>
<tr valign="top">
<td><code class="source">MULTIPLE_RELATIONAL</code></td>
<td>Multiple relational selection field.</td>
<td>No</td>
</tr>
</table>
</div>
<p> Attachments such as notes are stored in separate tables in TeamTrack
and are not replicated by the <abbr title="Perforce Defect Tracking
Integration">P4DTI</abbr>. If you need to have supplementary
information replicated to Perforce, use a memo field like "Additional
Notes". In TeamTrack you can turn any memo field into a "journal" field
which consists of a list of entries, each headed with the date of the
entry and the name of user who added it. </p>
</div>
<div class="bugzilla">
<p> If you're using Bugzilla, you might want to replicate the following fields: </p>
<ul>
<li> "longdesc", so that developers can understand what the problem is. </li>
<li> "bug_severity", so that developers can prioritize their work. </li>
<li> "priority", so that developers can prioritize their work. </li>
<li> "target_milestone", if you use target milestones, so that developers can prioritize their work. </li>
<li> "product", so that developers can categorize their work. </li>
<li> "component", so that developers can categorize their work. </li>
<li> "version", so that developers can categorize their work. </li>
<li> "op_sys", for additional developer information. </li>
<li> "rep_platform", for additional developer information. </li>
<li> "status_whiteboard", for additional developer information. </li>
<li> "keywords", for additional developer information. </li>
</ul>
<p> If you're using Bugzilla, the replicator rejects the following types of changes from within Perforce: </p>
<ul>
<li> Any changes to the following types of field:
<ul>
<li> Fields that cannot be changed in Bugzilla, such as "creation_ts",
"delta_ts", and "lastdiffed". </li>
<li> Fields that can only be changed in Bugzilla in very restricted ways, such as "groupset", "product", "version", "component", "target_milestone", and "everconfirmed". </li>
<li> Fields that, when changed in Bugzilla, have complex side-effects that the replicator can't sensibly reproduce, such as "votes" and "keywords". </li>
</ul>
</li>
<li> Changes that do anything to the "longdesc" field other than
appending to it. This field can be used for long descriptions of the
bug. When a Bugzilla user adds a comment to a bug, it appears at the
end of this field. Perforce users can also only modify this field by
appending to it; any text that they append is replicated to Bugzilla
as a new comment. </li>
<li> Invalid changes to fields that must contain Bugzilla users, such
as "assigned_to", "reporter", and "qacontact". These fields may
contain a Perforce user name, if the Perforce user corresponds to a
Bugzilla user, or a Bugzilla user's e-mail address. The "qacontact"
field may also contain "None". If a Perforce user changes one of
these fields to some other string, the replicator rejects the
change. </li>
</ul>
<p> The following table lists the field names for Bugzilla 2.10, 2.12, 2.14, 2.14.1, 2.14.4, and 2.16.1. If you have modified Bugzilla, your field names may differ. To display the set of Bugzilla field names, type <code class="command">mysqlshow bugs bugs</code> at a shell prompt.</p>
<div align="center">
<p> <a id="table-2" name="table-2">Table 2</a>. Bugzilla field names </p>
<table border="1" cellspacing="0" cellpadding="5">
<tr align="left" valign="top">
<th>Field name</th>
<th>Name on Bugzilla form</th>
<th>Replication policy</th>
</tr>
<tr valign="top">
<td>bug_id</td>
<td>Bug #</td>
<td>always, read only</td>
</tr>
<tr valign="top">
<td>bug_status</td>
<td>Status</td>
<td>always, read/write</td>
</tr>
<tr valign="top">
<td>assigned_to</td>
<td>Assigned To</td>
<td>always, read/write, user</td>
</tr>
<tr valign="top">
<td>short_desc</td>
<td>Summary</td>
<td>always, read/write</td>
</tr>
<tr valign="top">
<td>resolution</td>
<td>Resolution</td>
<td>always, read/write</td>
</tr>
<tr valign="top">
<td>bug_file_loc</td>
<td>URL</td>
<td>read/write</td>
</tr>
<tr valign="top">
<td>bug_severity</td>
<td>Severity</td>
<td>read/write</td>
</tr>
<tr valign="top">
<td>op_sys</td>
<td>OS</td>
<td>read/write</td>
</tr>
<tr valign="top">
<td>priority</td>
<td>Priority</td>
<td>read/write</td>
</tr>
<tr valign="top">
<td>rep_platform</td>
<td>Platform</td>
<td>read/write</td>
</tr>
<tr valign="top">
<td>reporter</td>
<td>Reporter</td>
<td>read/write, user</td>
</tr>
<tr valign="top">
<td>qa_contact</td>
<td>QA Contact</td>
<td>read/write, user or None</td>
</tr>
<tr valign="top">
<td>status_whiteboard</td>
<td>Status Whiteboard</td>
<td>read/write</td>
</tr>
<tr valign="top">
<td>reporter_accessible</td>
<td>Reporter checkbox</td>
<td>read/write</td>
</tr>
<tr valign="top">
<td>assignee_accessible</td>
<td>Assignee checkbox</td>
<td>read/write</td>
</tr>
<tr valign="top">
<td>qacontact_accessible</td>
<td>QA Contact checkbox</td>
<td>read/write</td>
</tr>
<tr valign="top">
<td>cclist_accessible</td>
<td>CC List checkbox</td>
<td>read/write</td>
</tr>
<tr valign="top">
<td>longdesc</td>
<td>Description</td>
<td>append only</td>
</tr>
<tr valign="top">
<td>groupset</td>
<td>-</td>
<td>read only</td>
</tr>
<tr valign="top">
<td>creation_ts</td>
<td>Opened</td>
<td>read only</td>
</tr>
<tr valign="top">
<td>delta_ts</td>
<td>-</td>
<td>read only</td>
</tr>
<tr valign="top">
<td>product</td>
<td>Product</td>
<td>read only</td>
</tr>
<tr valign="top">
<td>version</td>
<td>Version</td>
<td>read only</td>
</tr>
<tr valign="top">
<td>component</td>
<td>Component</td>
<td>read only</td>
</tr>
<tr valign="top">
<td>target_milestone</td>
<td>Target Milestone</td>
<td>read only</td>
</tr>
<tr valign="top">
<td>votes</td>
<td>Votes</td>
<td>read only</td>
</tr>
<tr valign="top">
<td>keywords</td>
<td>Keywords</td>
<td>read only</td>
</tr>
<tr valign="top">
<td>lastdiffed</td>
<td>-</td>
<td>read only</td>
</tr>
<tr valign="top">
<td>everconfirmed</td>
<td>-</td>
<td>read only</td>
</tr>
</table>
</div>
<p> The following fields are displayed on the Bugzilla bug form but are kept in separate database tables and cannot be replicated: </p>
<ul>
<li> "Cc" </li>
<li> "Attachments" </li>
<li> "Depends on" </li>
<li> "Blocks" </li>
</ul>
</div>
<p> If you need to change the list of replicated fields after you've started using the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>, see <a href="#section-9">section 9, "Maintaining the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>"</a>. </p>
<h3><a id="section-5.2" name="section-5.2">5.2. Perforce configuration</a></h3>
<p> To configure Perforce, you must: </p>
<ol>
<li> Create a Perforce user for the replicator (<a href="#section-5.2.1">section 5.2.1</a>). </li>
<li> Install Perforce triggers to enforce workflow (optional; <a href="#section-5.2.2">section 5.2.2</a>). </li>
<li> Delete all Perforce jobs, if you have not already done so (<a href="#section-5.2.3">section 5.2.3</a>). </li>
</ol>
<h4><a id="section-5.2.1" name="section-5.2.1">5.2.1. Creating a Perforce user for the replicator</a></h4>
<p> Create a user in Perforce for the replicator; for instructions, see the <cite><a href="http://www.perforce.com/perforce/doc.011/manuals/p4sag/">Perforce System Administrator's Guide</a></cite>. The replicator user must have the following properties: </p>
<ul>
<li><p> The userid must be the same as the <a
href="#config-p4_user">replicator Perforce userid (<code
class="source">p4_user</code>)</a> that you specified in the <abbr
title="Perforce Defect Tracking Integration">P4DTI</abbr> configuration.
</p></li>
<li><p> The e-mail address must match the <a href="#config-replicator_address">replicator e-mail address (<code class="source">replicator_address</code>)</a>. </p></li>
<li> <p>If you're using the Perforce protections, make the replicator a super user so that it can set the jobspec. For instructions, see the <cite><a href="http://www.perforce.com/perforce/doc.011/manuals/p4sag/">Perforce System Administrator's Guide</a></cite>. You'll need to add a line like </p>
<blockquote><code class="command">super user p4dti-replicator0 * //...</code></blockquote>
<p> to the protections list. </p> </li>
</ul>
<p> For information on getting a license from Perforce Software for this extra user, see <a href="#section-3.2">section 3.2, "Perforce prerequisites"</a>. </p>
<h4><a id="section-5.2.2" name="section-5.2.2">5.2.2. Installing Perforce triggers to enforce workflow</a></h4>
<p> You can use the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> in combination with a Perforce <dfn>trigger</dfn> 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. </p>
<p> The <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> comes with an example trigger script that you can adapt for your needs, installed as <code class="filename">example_trigger.py</code> in the default installation directory. </p>
<p> To enforce workflow restrictions, follow these steps: </p>
<ol>
<li> Configure the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> 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 <code class="source">replicated_fields</code> configuration parameter (for <a href="#config-replicated_fields-Bugzilla">Bugzilla</a> or <a href="#config-replicated_fields-TeamTrack">TeamTrack</a>). </li>
<li> 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. </li>
<li> Install the trigger script. For instructions on installing and managing trigger scripts, see the <cite><a href="http://www.perforce.com/perforce/doc.011/manuals/p4sag/">Perforce System Administrator's Guide</a></cite>. </li>
</ol>
<h4><a id="section-5.2.3" name="section-5.2.3">5.2.3. Deleting Perforce jobs</a></h4>
<p> You must delete all jobs from your Perforce installation. The <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> takes over the jobs subsystem of Perforce and rewrites the Perforce jobspec. </p>
<p> For instructions, see the <cite><a href="http://www.perforce.com/perforce/doc.011/manuals/p4guide/">Perforce Command Line User's Guide</a></cite>. </p>
<p> 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 <a href="../aag/index.html#section-4">section 4, "Migrating to the defect tracker from Perforce jobs"</a>, of the <cite><a href="../aag/index.html">Perforce Defect Tracking Integration Advanced Administrator's Guide</a></cite>. </p>
<p> If you already use Perforce jobs and have significant tools that depend on your jobspec, the configuration options described in <a href="#section-5.1">section 5.1, "<abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> configuration"</a>, 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 <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> configuration architecture and be fluent in the Python programming language. See the <cite>Perforce Defect Tracking Integration Integrator's Guide</cite> for details of how to configure the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> 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. </p>
<div class="teamtrack">
<h3><a id="section-5.3" name="section-5.3">5.3. TeamTrack configuration</a></h3>
<p> To configure TeamTrack, you must: </p>
<ol>
<li> Update the Windows Registry (<a href="#section-5.3.1">section 5.3.1</a>). </li>
<li> Create a TeamTrack user for the replicator (<a href="#section-5.3.2">section 5.3.2</a>). </li>
<li> Provide field descriptions (<a href="#section-5.3.3">section 5.3.3</a>). </li>
</ol>
<h4><a id="section-5.3.1" name="section-5.3.1">5.3.1. Updating the Windows Registry</a></h4>
<p> You need to add a TeamTrack value to the Windows Registry to tell TeamTrack that the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> is present. To do this, double-click the <code class="filename">p4dti.reg</code> file that comes with the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> (it's installed in <code class="filename">c:\program files\p4dti\p4dti.reg</code> by default). </p>
<h4><a id="section-5.3.2" name="section-5.3.2">5.3.2. Creating a TeamTrack user for the replicator</a></h4>
<p> You need to create a TeamTrack user for the replicator. This user corresponds to the <a href="#config-teamtrack_user">replicator TeamTrack userid (<code class="source">teamtrack_user</code>)</a> parameter you set in <a href="#section-5.1">section 5.1, "<abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> configuration"</a>. </p>
<p> To create a TeamTrack user for the replicator, follow these steps: </p>
<ol>
<li> Run the TeamTrack Administrator. (Under Windows, choose Start > Programs > TeamShare > TeamTrack Administrator.) </li>
<li> Select the <span class="gui">Users</span> tab.</li>
<li> Click the <span class="gui">Add</span> button.</li>
<li> On the <span class="gui">General</span> tab, in the Login ID field, enter the replicator user name (see the <a href="#config-teamtrack_user">replicator Teamtrack userid (<code class="source">teamtrack_user</code>)</a> parameter). </li>
<li> Click the <span class="gui">User</span> product access radio button (see <a href="#figure-7">Figure 7</a>). </li>
<li> On the <span class="gui">Privileges</span> tab, select the <span class="gui">System</span> tab and then select the "<span class="gui">Connect using the <abbr title="Application Programmer Interface">API</abbr></span>" check box (see <a href="#figure-8">Figure 8</a>). </li>
<li> On the <span class="gui">Privileges</span> tab, select the <span
class="gui">Item</span> tab. </li>
<li> In the pane at the left, select the base project. </li>
<li> In the pane at the right, select the "<span class="gui">Submit New
Items</span>", "<span class="gui">Update All Items</span>" and "<span
class="gui">Transition All Items</span>" check boxes (see <a
href="#figure-9">Figure 9</a>). </li>
<li> Click <span class="gui">OK</span> to add the user. </li>
</ol>
<p> For information on getting a license from TeamShare for this extra user, see <a href="#section-3.3">section 3.3, "TeamTrack prerequisites"</a>. </p>
<div align="center">
<p> <a id="figure-7" name="figure-7">Figure 7</a>. New user: General tab </p>
<img src="tt-new-user-general.gif" alt="Screen shot showing the general tab for creating a new user in TeamTrack Administrator" width="556" height="455" />
</div>
<div align="center">
<p> <a id="figure-8" name="figure-8">Figure 8</a>. New user: Privileges tab, System tab </p>
<img src="tt-new-user-privileges.gif" alt="Screen shot showing the System tab on the Privileges tab for creating a new user in TeamTrack Administrator" width="556" height="455" />
</div>
<div align="center">
<p> <a id="figure-9" name="figure-9">Figure 9</a>. New user: Privileges tab, Item tab </p>
<img src="tt-new-user-privileges-2.gif" alt="Screen shot showing the Item tab on the Privileges tab for creating a new user in TeamTrack Administrator" width="556" height="455" />
</div>
<h4><a id="section-5.3.3" name="section-5.3.3">5.3.3. Providing field descriptions</a></h4>
<p> 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). </p>
<p> 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 <code>TITLE</code> field as "A one-sentence statement of the problem from the user's perspective", and the <code>DESCRIPTION</code> field as "A detailed description of the problem from the user's perspective, including how to reproduce it." </p>
<p> To enter field descriptions, follow these steps: </p>
<ol>
<li> Run the TeamTrack Administrator. (Under Windows, choose Start > Programs > TeamShare > TeamTrack Administrator.) </li>
<li> Select the <span class="gui">Workflows</span> tab.</li>
<li> Select the <span class="gui">Issue Workflow</span>. </li>
<li> Click the <span class="gui">Edit</span> button. </li>
<li> Select the <span class="gui">Default Fields</span> tab.</li>
<li> Select the field you want to describe. </li>
<li> Click the <span class="gui">Edit</span> button. </li>
<li> Enter the description in the <span class="gui">Description</span> field. </li>
<li> Click <span class="gui">OK</span> to save your entries. </li>
<li> Repeat steps 6 to 9 until you're done. </li>
<li> Click the <span class="gui">OK</span> button. </li>
</ol>
</div>
<div class="bugzilla">
<h3><a id="section-5.4" name="section-5.4">5.4. Bugzilla configuration</a></h3>
<p> To configure Bugzilla, you must: </p>
<ol>
<li> Patch Bugzilla (<a href="#section-5.4.1">section 5.4.1</a>). </li>
<li> Create a Bugzilla user for the replicator (<a href="#section-5.4.2">section 5.4.2</a>). </li>
<li> Enable the <abbr title="Perforce Defect Tracking
Integration">P4DTI</abbr> extensions in Bugzilla (<a
href="#section-5.4.3">section 5.4.3</a>). </li>
</ol>
<h4><a id="section-5.4.1" name="section-5.4.1">5.4.1. Patching Bugzilla</a></h4>
<p> You need to make some minor modifications to the Bugzilla code so
that users can see Perforce information on Bugzilla bug forms, and so
that the <abbr title="Perforce Defect Tracking
Integration">P4DTI</abbr> can access the values of Bugzilla
configuration parameters. These modifications are distributed as
patch files for the supported versions of Bugzilla. </p>
<p> The patch utility distributed with some versions of Solaris can
not handle the form of patch file distributed with the P4DTI. We
recommend using the GNU patch utility.</p>
<p> Microsoft Windows does not come with a patch utility. For
information on obtaining a patch utility for Windows, see <a
href="#section-3.4.1">section 3.4.1, "Software Prerequisites"</a>.</p>
<p> If you have modified Bugzilla at your site, you might still be
able to apply the patch successfully. Changes to the database schema,
the permissions rules, or the workflow rules are likely to cause the
<abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> to
malfunction. You might need to modify the <abbr title="Perforce
Defect Tracking Integration">P4DTI</abbr> if you have changed these
parts of Bugzilla. </p>
<p> The patch for all Bugzilla versions changes the following Bugzilla
files: </p>
<ul>
<li> <code class="filename">bug_form.pl</code>, adding a Perforce
section to the bug form. </li>
<li> <code class="filename">defparams.pl</code>, adding a parameter to
control whether or not the Perforce section appears. </li>
<li> <code class="filename">doeditparams.cgi</code>, creating and
maintaining a database table containing Bugzilla's configuration
parameters. </li>
</ul>
<p> The patches for Bugzilla 2.14, 2.14.1, and 2.14.4 also change this
file: </p>
<ul>
<li> <code class="filename">globals.pl</code>, deleting unsafe
environment variables so that the <code
class="filename">processmail</code> script can be run by the <abbr
title="Perforce Defect Tracking Integration">P4DTI</abbr>. </li>
</ul>
<p> The patch for Bugzilla 2.16.1 also adds this file: </p>
<ul>
<li> <code class="filename">template/en/custom/bug/edit.html.tmpl</code>,
adding the Perforce section to the bug form template. </li>
</ul>
<p> These changes are small and self-contained. If your changes do not
affect these files or only affect them in minor ways, the patch should
operate correctly. If the patch program fails because of your Bugzilla
modifications, it might still be possible to introduce the changes by
hand. If you cannot apply the patch, the replicator might still work,
but the extensions listed in <a href="#section-5.4.3">section 5.4.3</a>
will not be available. </p>
<p> To apply the patch, follow these steps: </p>
<ol>
<li> Make a copy of your Bugzilla code so that you can uninstall the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> if necessary. </li>
<li> Go to your Bugzilla installation directory. </li>
<li> Enter the following command:
<blockquote>
<code class="command">patch -p1 < <i>p4dti-install-dir</i>/bugzilla-<i>bugzilla-version</i>-patch</code>
</blockquote>
(where <i>p4dti-install-dir</i> is your <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> installation directory) and <i>bugzilla-version</i> is your version of Bugzilla (2.10, 2.12, 2.14, 2.14.1, 2.14.4, or 2.16.1).</li>
<li> Check the output of the patch program carefully to ensure it succeeded. </li>
</ol>
<h4><a id="section-5.4.2" name="section-5.4.2">5.4.2. Creating a Bugzilla user for the replicator</a></h4>
<p> You need to create a Bugzilla user for the replicator. The replicator uses e-mail addresses to work out which Perforce user corresponds to which Bugzilla user. A Perforce user that does not correspond to a Bugzilla user is translated to the replicator's Bugzilla user, except for user fields (for example, "AssignedTo") in jobs. The replicator rejects a change when there is no Bugzilla user corresponding to a changed user field. </p>
<p> To create a Bugzilla user for the replicator, follow these steps: </p>
<ol>
<li> In a Web browser, go to <<span class="url">http://<i>your-bugzilla-path</i>/editusers.cgi</span>>. </li>
<li> Log in if prompted. </li>
<li> Click <span class="gui">Submit</span> to display the user list. </li>
<li> At the bottom of the user list, click "<span class="gui">Add a new user</span>". </li>
<li> In the "Login name" field, enter the <a href="#config-replicator_address">replicator e-mail address (<code class="source">replicator_address</code>)</a>. </li>
<li> In the "Real name" field, enter a name like "Perforce defect tracking integration". </li>
<li> Enter a password. </li>
<li> In the "Disable text" field, enter something like "This user can access Bugzilla only as the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> replicator process" to prevent access through the Bugzilla user interface. </li>
<li> Click <span class="gui">Add</span> to create the user. </li>
</ol>
<h4><a id="section-5.4.3" name="section-5.4.3">5.4.3. Enabling the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> extensions in Bugzilla</a></h4>
<p> After patching the Bugzilla code, you need to enable the <abbr
title="Perforce Defect Tracking Integration">P4DTI</abbr>
extensions in Bugzilla. There are two extensions: </p>
<ul>
<li><p> Bugzilla's bug form includes information about the
corresponding job in Perforce, and a table of fixes. </p></li>
<li><p> Bugzilla saves its configuration parameters in its database,
making it possible for the <abbr title="Perforce Defect Tracking
Integration">P4DTI</abbr> to support the "emailsuffix"
feature. </p></li>
</ul>
<p> To enable the extensions, follow these steps: </p>
<ol>
<li> In a Web browser, go to <<span class="url">http://<i>your-bugzilla-path</i>/editparams.cgi</span>>. </li>
<li> Log in as the Bugzilla administrator if prompted. </li>
<li> Set the "p4dti" parameter to "on" (if it is not already
on). </li>
<li> Click "<span class="gui">Submit changes</span>" to enable the
extensions. </li>
</ol>
<p> To disable the Perforce section in the Bugzilla bug form, set the
"p4dti" parameter to "off". Note that this does not control the
replicator; it merely affects the display of replicated
information.</p>
</div>
<h3><a id="section-5.5" name="section-5.5">5.5. Starting and stopping the replicator manually</a></h3>
<p> To start the replicator, follow these steps from the operating system command line: </p>
<ol>
<li> Go to the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> installation directory. </li>
<li> Run the command <code class="command">python run.py</code>. </li>
</ol>
<p> 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 <a href="#figure-10">the following figure</a>: </p>
<div align="center">
<p> <a id="figure-10" name="figure-10">Figure 10</a>. Example replicator log output on startup (TeamTrack integration) </p>
<table border="1" cellspacing="0" cellpadding="5"><tr><td><pre>
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.'.
...</pre></td></tr></table>
</div>
<p> Each log entry consists of the date of the entry, a message
identifier, and the message text. You can use the message identifier of
an error message to look it up in <a href="#section-11.2">section 11.2,
"Error messages by identifier"</a>. </p>
<p> During its startup sequence, the replicator creates Perforce jobs corresponding to every defect tracker issue created or modified after the (<code class="source"><a href="#config-start_date">start_date</a></code>). It then polls for changes every <code class="source"><a href="#config-poll_period">poll_period</a></code> seconds and replicates those changes. <a href="#figure-11">Figure 11</a> shows typical replicator log output when it is replicating a change. </p>
<div align="center">
<p> <a id="figure-11" name="figure-11">Figure 11</a>. Example replicator log output on replication (TeamTrack integration) </p>
<table border="1" cellspacing="0" cellpadding="5"><tr><td><pre>
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'}.</pre></td></tr></table>
</div>
<p> To stop the replicator on Windows, follow these steps: </p>
<ol>
<li>Select the command window in which the replicator is running.</li>
<li>Press Control-C and wait for the replicator to next poll (this takes
up to <a href="#config-poll_period"><code
class="source">poll_period</code></a> seconds).</li>
</ol>
<p> To stop the replicator on Unix systems, kill the
replicator process. If it's running in a shell, bring it to the
foreground and type Control-C. If not, find out the process id of the
replicator process and run the command <code class="command">kill -TERM
<i>replicator-process-id</i></code>. </p>
<h3><a id="section-5.6" name="section-5.6">5.6. Setting up the replicator to start automatically</a></h3>
<p> The <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>
can be run as a daemon on Unix and as an NT service on Windows. Check
that the replicator <a href="#section-5.5">starts manually</a> and runs
correctly, before leaving it to run automatically. </p>
<h4><a id="section-5.6.1" name="section-5.6.1">5.6.1. Running automatically on Unix</a></h4>
<p> If you installed the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> using the Linux <abbr title="Red Hat Package Manager">RPM</abbr> as described in <a href="#section-4.3">section 4.3, "Linux installation"</a>, a startup script is automatically created in <code class="filename">/etc/rc.d/init.d</code> directory, so that the replicator starts as a daemon when the machine is booted. Alternatively you can start the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> daemon manually by calling the startup script yourself:</p>
<blockquote><code class="command">/etc/rc.d/init.d/p4dti start</code></blockquote>
<p> The replicator halts automatically when the system is shut down.
You can stop the replicator daemon manually using the stop script: </p>
<blockquote><code class="command">/etc/rc.d/init.d/p4dti stop</code></blockquote>
<p> On Solaris or other Unixes (and on Linux if you did not use the <abbr title="Red Hat Package Manager">RPM</abbr> installer), you might want to adapt the Linux startup script. It is in the file named <code class="filename">startup-script</code> in the installation directory. </p>
<h4><a id="section-5.6.2" name="section-5.6.2">5.6.2. Running automatically on Windows</a></h4>
<p> On Windows, you can choose to install the <abbr title="Perforce
Defect Tracking Integration">P4DTI</abbr> as a service. The replicator
then starts when the machine is booted. You need not be logged on to
the machine for the service to run or to stay running. </p>
<p> To install the service, follow these steps from the operating system command line: </p>
<ol>
<li> Go to the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> installation directory. </li>
<li> Run the command:
<blockquote><code class="command">python service.py</code></blockquote>
</li>
</ol>
<p> Once the service has been installed, it can be started in any of the following ways:</p>
<ul>
<li>Use the control panel to start the Services applet and scroll down until you find "P4DTI". Click on this once, then click "Start".</li>
<li>Go to the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> installation directory and run the command: <code class="command">python service.py start</code>.</li>
<li>When the machine reboots, the service starts automatically.</li>
</ul>
<p> Once the service is running, it can be halted in any of the following ways. Note that you need not halt the service the same way that you started it.</p>
<ul>
<li>Use the control panel to start the Services applet and scroll down until you find "P4DTI". Click on this once, then click "Stop".</li>
<li>Go to the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> installation directory and run the command: <code class="command">python service.py stop</code>.</li>
<li>When the machine is shut down, the service stops automatically.</li>
</ul>
<p> To uninstall the service, go to the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> installation directory and run the command:</p>
<blockquote><code class="command">python service.py remove</code></blockquote>
<h3><a id="section-5.7" name="section-5.7">5.7. Advanced configuration</a></h3>
<p> Not all of the flexibility of the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> is available using the configuration options described in this section. Advanced configuration of the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> is possible, but beyond the scope of this manual. Here are some of the things that are possible with advanced configuration: </p>
<ul>
<li> Connecting a defect tracker to multiple Perforce servers. </li>
<li> Working with an existing Perforce jobs database and an existing Perforce jobspec. </li>
<li> Fine control over which defect tracker issues are replicated to Perforce. </li>
<li> Fine control over which issue fields are replicated, and their names. </li>
<li> Arbitrary translation of issue data between the defect tracker and Perforce. </li>
<li> Queries based on combined defect tracker and Perforce data. </li>
<li> Working with locally customized versions of Bugzilla. </li>
<li> Redirection or fine control of logging. </li>
<li> Arbitrary mappings between Perforce and defect tracker user names. </li>
<li> Alternative policies for handling conflicts between defect tracker and Perforce changes to issues. </li>
</ul>
<p> <a href="http://www.perforce.com/perforce/support.html">Contact Perforce technical support</a> if you need any of these facilities. </p>
<h2><a id="section-6" name="section-6">6. Migrating your defect tracking data to the integrated system</a></h2>
<h3><a id="section-6.1" name="section-6.1">6.1. Migrating from the defect tracker</a></h3>
<p> 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 <code class="source"><a href="#config-start_date">start_date</a></code> are replicated to Perforce. </p>
<h3><a id="section-6.2" name="section-6.2">6.2. Allowing users to create issues in Perforce</a></h3>
<p> See <a href="../aag/index.html#section-3">section 3,
"Allowing users to create issues in Perforce"</a> in the <a
href="../aag/index.html"><cite>Perforce Defect Tracking
Advanced Administrator's Guide</cite></a>. </p>
<h3><a id="section-6.3" name="section-6.3">6.3. Migrating to the defect tracker from Perforce jobs</a></h3>
<p> See <a href="../aag/index.html#section-4">section 4,
"Migrating to the defect tracker from Perforce jobs"</a> in the <a
href="../aag/index.html"><cite>Perforce Defect Tracking
Advanced Administrator's Guide</cite></a>. </p>
<h2><a id="section-7" name="section-7">7. Testing the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr></a></h2>
<h3><a id="section-7.1" name="section-7.1">7.1. Taking a single step</a></h3>
<p> When you're testing your <abbr title="Perforce Defect Tracking
Integration">P4DTI</abbr> configuration, you might need to tell the
<abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> take a
single step; that is, to poll the defect tracker and Perforce for
changes, replicate those changes, then stop. If you need to do this:
</p>
<ol>
<li>Change to the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> installation directory.</li>
<li>Run the command <code class="command">python poll.py</code>. </li>
</ol>
<h3><a id="section-7.2" name="section-7.2">7.2. Testing your configuration</a></h3>
<p> Test the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> configuration by creating a test issue and taking it through a complete life-cycle (that is, through the workflow) as described in the <a href="../ug/index.html"><cite>Perforce Defect Tracking Integration User's Guide</cite></a>. You might need to adapt the use cases described in the user's guide to your organization's workflow. </p>
<p> Test the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> from both Perforce and the defect tracker. In Perforce, test the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> using the interface that your developers are most likely to use. The main Perforce interfaces are: </p>
<ul>
<li> P4, the Perforce command line. </li>
<li> P4Win, the Perforce GUI. </li>
<li> The Perforce IDE integrations, if you use them. </li>
</ul>
<h3><a id="section-7.3" name="section-7.3">7.3. Checking data consistency</a></h3>
<p> To run the consistency checker and manage its output, follow these steps: </p>
<ol>
<li>Change to the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> installation directory.</li>
<li>Run the command <code class="command">python check.py</code>. </li>
</ol>
<p> You can also examine the database using a database application (for example, Microsoft Access or the <code class="command">mysql</code> command) to ensure the Perforce data is in there. </p>
<h2><a id="section-8" name="section-8">8. Training and documentation</a></h2>
<p> You might want to provide training for Perforce and defect tracker users before they adopt the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> 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 <a href="../ug/index.html"><cite>Perforce Defect Tracking Integration User's Guide</cite></a>. </p>
<p> Even if you don't have a formal training session for your users, ensure that they: </p>
<ul>
<li> Read the <a href="../ug/index.html"><cite>Perforce Defect Tracking Integration User's Guide</cite></a>. </li>
<li> Upgrade their Perforce clients to version 2001.1 or later. </li>
<li> Uninstall SourceBridge, if it's installed on their machines. </li>
<li> Know not to edit the P4DTI-* fields in jobs. </li>
</ul>
<h2><a id="section-9" name="section-9">9. Maintaining the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr></a></h2>
<h3><a id="section-9.1" name="section-9.1">9.1. Maintaining the configuration</a></h3>
<p> You must stop and restart the replicator as described in <a href="#section-5.5">section 5.5, "Starting the replicator manually"</a> after changing any of the configuration parameters described in <a href="#section-5.1">section 5.1, "<abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> configuration"</a>. </p>
<p> You must also refresh Perforce jobs, as described in <a href="#section-9.2">section 9.2, "Refreshing jobs in Perforce"</a>, after changing either: </p>
<ol>
<li> the list of replicated fields (<code class="source">replicated_fields</code> for <a href="#config-replicated_fields-Bugzilla">Bugzilla</a> or <a href="#config-replicated_fields-TeamTrack">TeamTrack</a>), or </li>
<li> the <a href="#config-start_date">start date for replication (<code class="source">start_date</code>)</a>. </li>
</ol>
<p> Perforce uses the field number in the jobspec to find data, not the field name (for more information, see the <cite><a href="http://www.perforce.com/perforce/doc.011/manuals/p4sag/">Perforce System Administrator's Guide</a></cite>). 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. </p>
<h3><a id="section-9.2" name="section-9.2">9.2. Refreshing jobs in Perforce</a></h3>
<p> Refreshing jobs updates all jobs in Perforce by replicating them
from the defect tracker's database. This procedure is necessary if: </p>
<ul>
<li> The Perforce jobs become corrupted. </li>
<li> You change the set of replicated fields in the replicator's configuration. For details, see <a href="#section-9.1">section 9.1, "Maintaining the configuration"</a>. </li>
<li> You change the start date of replication in the replicator's configuration. For details, see <a href="#section-9.1">section 9.1</a>. </li>
</ul>
<p> To refresh the Perforce jobs, follow these steps from the operating system command line: </p>
<ol>
<li> Stop the replicator. </li>
<li> Go to the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> installation directory. </li>
<li> Run the command <code class="command">python refresh.py</code>. </li>
<li> Start the replicator again by running the command <code class="command">python run.py</code>. </li>
</ol>
<h2><a id="section-10" name="section-10">10. Uninstalling the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr></a></h2>
<p> To uninstall the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>, follow these steps: </p>
<ol>
<li> Tell your staff. Ask them to stop using either Perforce jobs or the defect tracking, whichever you're not planning to use in future. </li>
<li> Stop the replicator by following the instructions in <a href="#section-5.5">section 5.5, "Starting the replicator manually"</a> (or <a href="#section-5.6">section 5.6, "Setting up the replicator to start automatically"</a>). </li>
<li> Remove any hooks that you created in <a href="#section-5.6">section 5.6, "Setting up the replicator to start automatically"</a>, such as Windows services, entries in <code class="filename">/etc/rc.d</code>, and so on. </li>
<li> If you're using Bugzilla:
<ol type="a">
<li> Disable the Bugzilla extensions that were enabled in <a href="#section-5.4.3">section 5.4.3, "Enabling the Bugzilla extensions"</a>. </li>
<li> Delete the replicator's Bugzilla user that was created in <a href="#section-5.4.2">section 5.4.2, "Creating a Bugzilla user for the replicator"</a>. </li>
<li> optionally, restore the unpatched copy of Bugzilla made in <a href="#section-5.4.1">section 5.4.1, "Patching Bugzilla"</a>. </li>
</ol>
</li>
<li> If you're using TeamTrack:
<ol type="a">
<li> Delete the replicator's TeamTrack user that was created in <a href="#section-5.3.2">section 5.3.2, "Creating a TeamTrack user for the replicator"</a>. </li>
</ol>
</li>
<li> Remove any Perforce triggers that were added in <a href="#section-5.2.2">section 5.2.2, "Installing Perforce triggers to enforce workflow"</a>. </li>
<li> Delete the replicator's Perforce user created in <a href="#section-5.2.1">section 5.2.1, "Creating a Perforce user for the replicator"</a>. </li>
<li> If you installed using the Linux <abbr title="Red Hat Package Manager">RPM</abbr>, as described in <a href="#section-4.3">section 4.3, "Linux installation"</a>, uninstall using the command
<blockquote><code class="source">rpm -e p4dti</code></blockquote>
Otherwise, delete the contents of the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> installation directory. </li>
<!--
<li> If you're using Bugzilla, run <code class="source">r.dt.bugzilla.drop_p4dti_tables()</code> to delete the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> tables from the database, and restore the backup copy of Bugzilla that you made before you installed the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> (see <a href="#section-3.4.2">section 3.4.2, "Procedural prerequisites"</a>). </li>
-->
</ol>
<h2><a id="section-11" name="section-11">11. Troubleshooting and error messages</a></h2>
<h3><a id="section-11.1" name="section-11.1">11.1. Troubleshooting</a></h3>
<p>To troubleshoot a problem with the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>, follow these steps:</p>
<ol>
<li><p> Look in the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> log. If you find an error message, see if it is listed in <a href="#section-11.2">section 11.2, "Error messages"</a>. </p></li>
<li><p> Check your configuration against <a href="#section-5.1">section 5.1, "<abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> configuration"</a>. Are the hostnames, userids, and passwords correct? Most problems with the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> are caused by incorrect or inconsistent configuration. </p></li>
<li><p> See if there is any online support for your problem. Visit the
P4DTI issue reports page <<a
href="http://www.ravenbrook.com/project/p4dti/issue/">http://www.ravenbrook.com/project/p4dti/issue/</a>>,
choose your release and select the "Support information" report. </p></li>
<li><p> If you can't solve the problem, contact Perforce support (for details, see <<a
href="http://www.perforce.com/perforce/support.html">http://www.perforce.com/perforce/support.html</a>>). Provide the following information: </p>
<ol type="a">
<li> What you did immediately prior to the error's occurrence. </li>
<li> What you think should have happened. </li>
<li> What actually happened. </li>
<li> The <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> release you are using (look in the <code class="filename">readme.txt</code> that came with your <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> distribution to identify the release). </li>
<li>The Perforce release you are using. To determine your Perforce release, enter "<code class="command">p4 info</code>" at the operating system command line. </li>
<li>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. </li>
<li> A section of the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> log that includes the error that you're reporting and some context around that error. </li>
<li> Copies of any related e-mail messages generated by the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>. </li>
<li> A copy of your <code class="filename">config.py</code> file. </li>
</ol>
</li>
</ol>
<h3><a id="section-11.2" name="section-11.2">11.2. Error messages by identifier</a></h3>
<p> This isn't a complete list, but it covers the errors that have been seen in testing, or which are reasonably likely to come up, or which need some explanation. If you see a message not covered in this section or <a href="#section-11.3">section 11.3, "Other error messages"</a> and which is not self-explanatory, please contact Perforce support (see <a href="#section-11.1">section 11.1, "Troubleshooting"</a>).</p>
<h4><a id="message-P4DTI-1058" name="message-P4DTI-1058"> (P4DTI-1058) Given '%s' when expecting a string or integer. </a><br />
<a id="message-P4DTI-1069" name="message-P4DTI-1069"> (P4DTI-1069) Select '%s' of %s returns no rows. </a><br />
<a id="message-P4DTI-107X" name="message-P4DTI-107X"> (P4DTI-107X) Select '%s' of %s expecting one row but returns %d. </a><br />
<a id="message-P4DTI-1080" name="message-P4DTI-1080"> (P4DTI-1080) Trying to fetch a row from non-select '%s'. </a><br />
<a id="message-P4DTI-1091" name="message-P4DTI-1091"> (P4DTI-1091) Select '%s' of %s returned an unfetchable row. </a><br />
<a id="message-P4DTI-1105" name="message-P4DTI-1105"> (P4DTI-1105) Trying to fetch rows from non-select '%s'. </a><br />
<a id="message-P4DTI-1116" name="message-P4DTI-1116"> (P4DTI-1116) Select '%s' of %s returned unfetchable rows. </a><br />
<a id="message-P4DTI-1127" name="message-P4DTI-1127"> (P4DTI-1127) Select '%s' of %s expecting no more than one row but returns %d. </a><br />
<a id="message-P4DTI-1138" name="message-P4DTI-1138"> (P4DTI-1138) Select '%s' of %s returns %d columns but %d values. </a><br />
<a id="message-P4DTI-1160" name="message-P4DTI-1160"> (P4DTI-1160) Couldn't insert row in table '%s'. </a><br />
<a id="message-P4DTI-1171" name="message-P4DTI-1171"> (P4DTI-1171) Couldn't update row in table '%s' where %s. </a><br />
<a id="message-P4DTI-1229" name="message-P4DTI-1229"> (P4DTI-1229) Nothing in p4dti_replications table: database corrupted? </a><br />
<a id="message-P4DTI-1273" name="message-P4DTI-1273"> (P4DTI-1273) Bugzilla's fielddefs table does not include '%s'.</a>
</h4>
<p> The replicator has had an unexpected difficulty in accessing the Bugzilla database. Possibly there is a problem with MySQL or MySQLdb. Possibly you are running a version of Bugzilla which is incompatible with the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>, or have customized Bugzilla in such a way that the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> has become confused. Please contact Perforce support (see <a href="#section-11.1">section 11.1, "Troubleshooting"</a>). </p>
<h4><a id="message-P4DTI-1207" name="message-P4DTI-1207"> (P4DTI-1207) Unknown or future P4DTI/Bugzilla schema version %s detected.</a></h4>
<p> It looks as though you've been running with a later release of the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> and then downgraded to an older release. We don't support downgrading; use the most recent release. </p>
<h4><a id="message-P4DTI-123X" name="message-P4DTI-123X"> (P4DTI-123X) Bugzilla version %s is not supported by the P4DTI.</a></h4>
<p> The <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>
doesn't support your version of Bugzilla. Upgrade to a supported
release (see <a href="#section-3.4.1">section 3.4.1</a>). </p>
<h4><a id="message-P4DTI-2006" name="message-P4DTI-2006"> (P4DTI-2006) Configuration parameter '%s' must be 0 or 1. </a><br />
<a id="message-P4DTI-2017" name="message-P4DTI-2017"> (P4DTI-2017) Configuration parameter '%s' (value '%s') is not a valid date. The right format is 'YYYY-MM-DD HH:MM:SS'. </a><br />
<a id="message-P4DTI-2028" name="message-P4DTI-2028"> (P4DTI-2028) Configuration parameter '%s' (value '%s') is not a valid e-mail address. </a><br />
<a id="message-P4DTI-2039" name="message-P4DTI-2039"> (P4DTI-2039) Configuration parameter '%s' must be a function. </a><br />
<a id="message-P4DTI-204X" name="message-P4DTI-204X"> (P4DTI-204X) Configuration parameter '%s' must be an integer. </a><br />
<a id="message-P4DTI-2050" name="message-P4DTI-2050"> (P4DTI-2050) Configuration parameter '%s' must be a list. </a><br />
<a id="message-P4DTI-2061" name="message-P4DTI-2061"> (P4DTI-2061) Configuration parameter '%s' must be a list of %s. </a><br />
<a id="message-P4DTI-2072" name="message-P4DTI-2072"> (P4DTI-2072) Configuration parameter '%s' must be a string. </a><br />
<a id="message-P4DTI-2083" name="message-P4DTI-2083"> (P4DTI-2083) Configuration parameter '%s' must be None or a string. </a><br />
<a id="message-P4DTI-2094" name="message-P4DTI-2094"> (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. </a><br />
<a id="message-P4DTI-2108" name="message-P4DTI-2108"> (P4DTI-2108) Configuration parameter '%s' (value '%s') must contain exactly one %%d format specifier, any number of doubled percents, but no other format specifiers. </a><br />
<a id="message-P4DTI-2119" name="message-P4DTI-2119"> (P4DTI-2119) Configuration parameter '%s' (value '%s') must contain exactly one %%s format specifier, any number of doubled percents, but no other format specifiers. </a></h4>
<p> Preliminary checking of the parameters set in <code class="filename">config.py</code> has found a problem. Correct the named parameter and start the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> again. </p>
<h4><a id="message-P4DTI-3009" name="message-P4DTI-3009"> (P4DTI-3009) Two Bugzilla states '%s' and '%s' map to the same Perforce state '%s'. </a></h4>
<p>You are running a version of Bugzilla with different bug statuses from those in Bugzilla 2.10, 2.12, 2.14, 2.14.1, 2.14.4, or 2.16.1. The <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> has attempted to choose a sensible translation of these bug statuses to Perforce job states, but has failed. You may be able to fix this by changing the <a href="#config-closed_state-Bugzilla"><code class="source">closed_state</code></a> parameter. Otherwise you must modify your Bugzilla configuration.</p>
<p> The <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> chooses the names of states of Perforce jobs based on the status names in Bugzilla. It uses the following translation system: </p>
<ul>
<li> To avoid user confusion in the Perforce interface, the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> translates all state names to lower case.</li>
<li> Perforce job states can't contain spaces and various other
characters, so the <abbr title="Perforce Defect Tracking
Integration">P4DTI</abbr> translates spaces to underscores, and
translates other special characters. </li>
<li> If the <a href="#config-closed_state-Bugzilla"><code class="source">closed_state</code></a> parameter is not None, the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> translates this status to "closed" and translates "CLOSED" to "bugzilla_closed".</li>
<li> Perforce jobs can't have the state "new" or "ignore", because these states have special meaning to the Perforce server. The <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> prefixes a Bugzilla status which would translate to either of these with "bugzilla_", so (in particular) "NEW" translates to Perforce state "bugzilla_new".</li>
</ul>
<p>For instance, if the <a href="#config-closed_state-Bugzilla"><code
class="source">closed_state</code></a> parameter is <code
class="source">"RESOLVED"</code>, the <abbr title="Perforce Defect
Tracking Integration">P4DTI</abbr> uses the following translation table
for the default Bugzilla statuses:</p>
<div align="center">
<table border="1" cellspacing="0" cellpadding="5">
<tr align="left" valign="top">
<th>Bugzilla status</th>
<th>Perforce state</th>
</tr>
<tr align="left" valign="top">
<td>UNCONFIRMED</td>
<td>unconfirmed</td>
</tr>
<tr align="left" valign="top">
<td>NEW</td>
<td>bugzilla_new</td>
</tr>
<tr align="left" valign="top">
<td>ASSIGNED</td>
<td>assigned</td>
</tr>
<tr align="left" valign="top">
<td>RESOLVED</td>
<td>closed</td>
</tr>
<tr align="left" valign="top">
<td>VERIFIED</td>
<td>verified</td>
</tr>
<tr align="left" valign="top">
<td>CLOSED</td>
<td>bugzilla_closed</td>
</tr>
<tr align="left" valign="top">
<td>REOPENED</td>
<td>reopened</td>
</tr>
</table>
</div>
<p>Alternatively, if the <a href="#config-closed_state-Bugzilla"><code
class="source">closed_state</code></a> parameter is <code
class="source">"CLOSED"</code> or <code class="source">None</code>, the
<abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> uses the
following translation table for the default Bugzilla statuses:</p>
<div align="center">
<table border="1" cellspacing="0" cellpadding="5">
<tr align="left" valign="top">
<th>Bugzilla status</th>
<th>Perforce state</th>
</tr>
<tr align="left" valign="top">
<td>UNCONFIRMED</td>
<td>unconfirmed</td>
</tr>
<tr align="left" valign="top">
<td>NEW</td>
<td>bugzilla_new</td>
</tr>
<tr align="left" valign="top">
<td>ASSIGNED</td>
<td>assigned</td>
</tr>
<tr align="left" valign="top">
<td>RESOLVED</td>
<td>resolved</td>
</tr>
<tr align="left" valign="top">
<td>VERIFIED</td>
<td>verified</td>
</tr>
<tr align="left" valign="top">
<td>CLOSED</td>
<td>closed</td>
</tr>
<tr align="left" valign="top">
<td>REOPENED</td>
<td>reopened</td>
</tr>
</table>
</div>
<h4><a id="message-P4DTI-301X" name="message-P4DTI-301X"> (P4DTI-301X) You specified the closed_state '%s', but there's no such Bugzilla state. </a></h4>
<p> Check the <a href="#config-closed_state-Bugzilla"><code class="source">closed_state</code></a> parameter. It must be a valid Bugzilla state. </p>
<h4><a id="message-P4DTI-3020" name="message-P4DTI-3020"> (P4DTI-3020) The '%s' column of Bugzilla's 'bugs' table is not an enum type. </a></h4>
<p> The <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> is incompatible with the version of Bugzilla which you are running. You are running a very old version of Bugzilla, or have customized Bugzilla. </p>
<h4><a id="message-P4DTI-3031" name="message-P4DTI-3031"> (P4DTI-3031) Configuration parameter 'bugzilla_directory' does not name a directory. </a><br />
<a id="message-P4DTI-3042" name="message-P4DTI-3042"> (P4DTI-3042) Configuration parameter 'bugzilla_directory' does not name a directory containing a processmail script. </a></h4>
<p> Check the <a href="#config-bugzilla_directory"><code class="source">bugzilla_directory</code></a> parameter. It must either be <code class="source">None</code> or a string naming the Bugzilla installation directory. </p>
<p> If you're running Bugzilla under Windows, check that you've followed the instructions in <a href="http://www.ravenbrook.com/project/p4dti/import/2002-09-30/bugzilla-2.14.4/bugzilla-2.14.4/docs/html/win32.html">section 3.6, "Win32 Installation Notes"</a> of the Bugzilla Guide [<a href="http://www.ravenbrook.com/project/p4dti/import/2002-09-30/bugzilla-2.14.4/bugzilla-2.14.4/docs/html/">Bugzilla 2002-09-30</a>]. </p>
<h4><a id="message-P4DTI-3053" name="message-P4DTI-3053"> (P4DTI-3053) Bugzilla's table 'profiles' does not have a 'login_name' column. </a><br />
<a id="message-P4DTI-3064" name="message-P4DTI-3064">(P4DTI-3064) The 'login_name' column of Bugzilla's 'profiles' table does not have a 'text' type. </a><br />
<a id="message-P4DTI-3075" name="message-P4DTI-3075"> (P4DTI-3075) Bugzilla's table 'bugs' does not have a '%s' column. </a><br />
<a id="message-P4DTI-3086" name="message-P4DTI-3086"> (P4DTI-3086) The 'bug_status' column of Bugzilla's 'bugs' table is not an enum type. </a><br />
<a id="message-P4DTI-3097" name="message-P4DTI-3097"> (P4DTI-3097) The 'resolution' column of Bugzilla's 'bugs' table is not an enum type. </a><br />
<a id="message-P4DTI-3100" name="message-P4DTI-3100"> (P4DTI-3100) The 'resolution' column of Bugzilla's 'bugs' table does not have a 'FIXED' value. </a></h4>
<p> The <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> is incompatible with the version of Bugzilla which you are running. You are running a very old version of Bugzilla, or have customized Bugzilla. </p>
<h4><a id="message-P4DTI-3111" name="message-P4DTI-3111"> (P4DTI-3111) Field '%s' specified in 'replicated_fields' is a system field: leave it out! </a></h4>
<p> Some fields are always replicated. For details, see the <a href="#config-replicated_fields-Bugzilla"><code class="source">replicated_fields</code></a> parameter. </p>
<p> Remove the system fields from your list of replicated fields and start the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> again. </p>
<h4><a id="message-P4DTI-3122" name="message-P4DTI-3122"> (P4DTI-3122) Field '%s' appears twice in 'replicated_fields'. </a></h4>
<p> Each replicated field must only appear once in the <a href="#config-replicated_fields-Bugzilla"><code class="source">replicated_fields</code></a> parameter. Remove the duplicate and start the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> again. </p>
<h4><a id="message-P4DTI-3133" name="message-P4DTI-3133"> (P4DTI-3133) Field '%s' specified in 'replicated_fields' list not in Bugzilla 'bugs' table. </a></h4>
<p> The <a href="#config-replicated_fields-Bugzilla"><code class="source">replicated_fields</code></a> parameter specifies a field which is not in Bugzilla. </p>
<h4><a id="message-P4DTI-3144" name="message-P4DTI-3144"> (P4DTI-3144) Field '%s' specified in 'replicated_fields' list has type '%s': this is not yet supported by P4DTI. </a><br />
<a id="message-P4DTI-3155" name="message-P4DTI-3155"> (P4DTI-3155) Field '%s' specified in 'replicated_fields' list has floating-point type: this is not yet supported by P4DTI. </a></h4>
<p> The <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> doesn't support all Bugzilla field types. One of the fields in your <a href="#config-replicated_fields-Bugzilla"><code class="source">replicated_fields</code></a> parameter has an unsupported type. </p>
<p> Remove the field from your <a href="#config-replicated_fields-Bugzilla"><code class="source">replicated_fields</code></a> and start the replicator again. </p>
<p> If you really need this field to be replicated, see the advice for <a href="#message-P4DTI-4067">(P4DTI-4067)</a>. </p>
<h4><a id="message-P4DTI-3166" name="message-P4DTI-3166"> (P4DTI-3166) You can't have a field called 'code' in the Perforce jobspec. </a></h4>
<p>You are running a version of Bugzilla with different bug fields
from those in Bugzilla 2.10, 2.12, 2.14, 2.14.1, 2.14.4, or 2.16.1,
and are trying to replicate a field called "code". Perforce doesn't
allow a job field called "code". Remove the "code" field from the <a
href="#config-replicated_fields-Bugzilla"><code
class="source">replicated_fields</code></a> parameter or modify your
Bugzilla configuration to rename the field.</p>
<h4><a id="message-P4DTI-3177" name="message-P4DTI-3177"> (P4DTI-3177) Too many fields to replicate: Perforce jobs can contain only 99 fields. </a></h4>
<p> Reduce the number of fields that you replicate by removing items from the <a href="#config-replicated_fields-Bugzilla"><code class="source">replicated_fields</code></a> parameter. </p>
<h4><a id="message-P4DTI-4001" name="message-P4DTI-4001"> (P4DTI-4001) Two TeamTrack states '%s' and '%s' map to the same Perforce state '%s'. </a></h4>
<p> The <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> chooses the names of states of Perforce jobs based on the state names in TeamTrack. It uses the following mapping system: </p>
<ul>
<li> Perforce job states can't contain spaces and various other
characters, so the <abbr title="Perforce Defect Tracking
Integration">P4DTI</abbr> maps spaces to underscores, and translates
other special characters. </li>
<li> To avoid user confusion in the Perforce interface, the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> 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.) </li>
<li> Perforce jobs can't have the state "new" or "ignore", because these states have special meaning to the Perforce server. The <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> 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". </li>
</ul>
<p> Resolve this problem by making the state names distinct in TeamTrack. Do not use spaces at the beginning of state names. </p>
<h4><a id="message-P4DTI-4012" name="message-P4DTI-4012"> (P4DTI-4012) You specified the closed_state '%s', but there's no such TeamTrack state. </a></h4>
<p> See <a href="#message-P4DTI-301X">(P4DTI-301X)</a>. </p>
<h4><a id="message-P4DTI-4023" name="message-P4DTI-4023"> (P4DTI-4023) Couldn't get descriptions for TeamTrack system fields STATE, OWNER, and TITLE. </a></h4>
<p> You may be using a version of TeamTrack with a release of the <abbr
title="Perforce Defect Tracking Integration">P4DTI</abbr> that doesn't
support it. If so, upgrade to a <abbr title="Perforce Defect Tracking
Integration">P4DTI</abbr> release that supports your version of
TeamTrack. </p>
<p> This could happen if you don't have a tTrack solution in your TeamTrack database. If so, create one. </p>
<h4><a id="message-P4DTI-4034" name="message-P4DTI-4034"> (P4DTI-4034) Field '%s' specified in 'replicated_fields' list not in TeamTrack FIELDS table. </a></h4>
<p> You can specify a list of fields for the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> to replicate into jobs; for details, see the <a href="#config-replicated_fields-TeamTrack"><code class="source">replicated_fields</code></a> parameter. This error means that the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> couldn't find one of the fields in the list. This problem might happen if you change the set of fields in TeamTrack. </p>
<p> Double-check the field names you specified as the <code class="source">replicated_fields</code>. If you're changing fields in TeamTrack, see <a href="#section-9">section 9, "Maintaining the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>"</a>, for important information. </p>
<h4><a id="message-P4DTI-4045" name="message-P4DTI-4045"> (P4DTI-4045) Field '%s' specified in 'replicated_fields' list is a system field: leave it out! </a></h4>
<p> See <a href="#message-P4DTI-3111">(P4DTI-3111)</a>. </p>
<h4><a id="message-P4DTI-4056" name="message-P4DTI-4056"> (P4DTI-4056) Field '%s' appears twice in 'replicated_fields'. </a></h4>
<p> See <a href="#message-P4DTI-3122">(P4DTI-3122)</a>. </p>
<h4><a id="message-P4DTI-4067" name="message-P4DTI-4067"> (P4DTI-4067) Field '%s' has type %d: this is not supported by P4DTI. </a></h4>
<p> The <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> doesn't support all TeamTrack field types. One of the fields in your <a href="#config-replicated_fields-TeamTrack"><code class="source">replicated_fields</code></a> parameter has an unsupported type. </p>
<p> You can determine the list of supported types from the <code class="source">type_table</code> in <code class="filename">configure_teamtrack.py</code>. The most notable unsupported type is "MULTIPLE_SELECTION", because Perforce does not provide any kind of multiple selection interface. </p>
<p> If you really need to have the field replicated, you have the following options: </p>
<ul>
<li> Change the set of fields in TeamTrack to avoid the type. </li>
<li> Change your workflow to avoid needing that particular field from the Perforce interface. </li>
<li> Submit a request to Perforce. </li>
<li> Implement a new subclass of <code class="source">replicator.translator</code> to handle the field type (for the existing translators, see <code class="filename">dt_teamtrack.py</code>). For instructions on how to extend the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>, and how to contribute your extensions back to the community, see the <cite>Perforce Defect Tracking Integration Integrator's Guide</cite>. </li>
</ul>
<h4><a id="message-P4DTI-4078" name="message-P4DTI-4078"> (P4DTI-4078) You can't have a field called 'code' in the Perforce jobspec. </a></h4>
<p> Perforce uses the field "code" to pass internal status information to clients. </p>
<p> In TeamTrack, change the logical name of the field to something other than "code" by following these steps: </p>
<ol>
<li> Run the TeamTrack Administrator. (Under Windows, choose Start > Programs > TeamShare > TeamTrack Administrator.) </li>
<li>Select the Workflow tab.</li>
<li>Select the workflow containing the field called "code".</li>
<li>Click the Edit button.</li>
<li>Select the Default Fields tab.</li>
<li>Select the "code" field.</li>
<li>Click the Edit button.</li>
<li>Change the Logical Field Name.</li>
<li>Click OK.</li>
<li>Click OK again. </li>
</ol>
<h4><a id="message-P4DTI-4089" name="message-P4DTI-4089"> (P4DTI-4089) Too many fields to replicate: Perforce jobs can contain only 99 fields. </a></h4>
<p> See <a href="#message-P4DTI-3177">(P4DTI-3177)</a>. </p>
<h4><a id="message-P4DTI-5004" name="message-P4DTI-5004"> (P4DTI-5004) User %d isn't in the right bug group to edit bug %d. </a></h4>
<p> A Perforce user has made a change to a bug which Bugzilla would not allow them to edit. </p>
<p> 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. </p>
<p> Another possible cause is that the <abbr title="Perforce Defect
Tracking Integration">P4DTI</abbr> has failed to find a Bugzilla user
corresponding to the Perforce user. See <a href="#section-3.5">section
3.5, "User accounts"</a> for details of how users are mapped from one
system to the other, and how to diagnose problems. </p>
<h4><a id="message-P4DTI-5015" name="message-P4DTI-5015"> (P4DTI-5015) User %d doesn't have permission to change field '%s' of bug %d to %s. </a></h4>
<p> A Perforce user has made a change which Bugzilla would not have permitted them to make. </p>
<p> 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. </p>
<p> Another possible cause is that the <abbr title="Perforce Defect
Tracking Integration">P4DTI</abbr> has failed to find a Bugzilla user
corresponding to the Perforce user. See <a href="#section-3.5">section
3.5, "User accounts"</a> for details of how users are mapped from one
system to the other, and how to diagnose problems. </p>
<h4><a id="message-P4DTI-5026" name="message-P4DTI-5026"> (P4DTI-5026) The P4DTI does not support marking bugs as DUPLICATE from Perforce. </a></h4>
<p> A Perforce user has changed a job's status to "duplicate". </p>
<p> 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. </p>
<h4><a id="message-P4DTI-5037" name="message-P4DTI-5037"> (P4DTI-5037) Bugzilla does not allow a transition from status '%s' to '%s'. </a></h4>
<p> A Perforce user has changed the 'status' field of a bug in a way not permitted by Bugzilla. For instance, moving a bug directly from UNCONFIRMED to CLOSED. These transitions are not allowed in Bugzilla, and the replicator enforces that prohibition by rejecting such a change. </p>
<p> 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. </p>
<h4><a id="message-P4DTI-5048" name="message-P4DTI-5048"> (P4DTI-5048) Cannot change Bugzilla field '%s'. </a></h4>
<p> A Perforce user has made a change to a field which the replicator treats as read-only. See <a href="#section-5.1.5">section 5.1.5, "Choosing which fields to replicate"</a>. </p>
<h4><a id="message-P4DTI-5059" name="message-P4DTI-5059"> (P4DTI-5059) Can only append to Bugzilla field '%s'. </a></h4>
<p> A Perforce user has changed the long description text in some way other than appending to it. See <a href="#section-5.1.5">section 5.1.5, "Choosing which fields to replicate"</a>. </p>
<h4> <a id="message-P4DTI-506X" name="message-P4DTI-506X"> (P4DTI-506X) Updating non-existent Bugzilla field '%s'. </a><br />
<a id="message-P4DTI-5092" name="message-P4DTI-5092"> (P4DTI-5092) No Perforce status corresponding to Bugzilla status '%s'. </a><br />
<a id="message-P4DTI-5106" name="message-P4DTI-5106"> (P4DTI-5106) No Bugzilla status corresponding to Perforce status '%s'. </a></h4>
<p> These errors indicate a serious configuration error; someone's changed configure_bugzilla.py and broken it. </p>
<h4> <a id="message-P4DTI-5070" name="message-P4DTI-5070"> (P4DTI-5070) Bugzilla does not have a group called '%s'. </a><br />
<a id="message-P4DTI-5081" name="message-P4DTI-5081"> (P4DTI-5081) Bugzilla's fielddefs table does not include '%s'. </a></h4>
<p> The <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> is incompatible with the version of Bugzilla which you are running. You are running a very old version of Bugzilla, or have customized Bugzilla. </p>
<h4><a id="message-P4DTI-5117" name="message-P4DTI-5117"> (P4DTI-5117) Perforce field value '%s' could not be translated to a number for replication to Bugzilla. </a></h4>
<p> A Perforce user has set a field, which corresponds to a numeric field in Bugzilla, to something which couldn't be converted to a number. </p>
<h4><a id="message-P4DTI-5128" name="message-P4DTI-5128"> (P4DTI-5128) Bugzilla P4DTI user '%s' has e-mail address matching Perforce user '%s', not Perforce P4DTI user '%s'. </a></h4>
<p> The replicator Perforce user (<a href="#config-p4_user"><code class="source">p4_user</code></a> parameter) has an e-mail address that does not match the <a href="#config-replicator_address"><code class="source">replicator_address</code></a> parameter. See <a href="#section-5.2.1">section 5.2.1, "Creating a Perforce user for the replicator"</a>. </p>
<h4><a id="message-P4DTI-5139" name="message-P4DTI-5139"> (P4DTI-5139) Bugzilla P4DTI user '%s' is not a known Bugzilla user. </a></h4>
<p> There is no Bugzilla user whose e-mail address matches the <a href="#config-replicator_address"><code class="source">replicator_address</code></a> parameter. See <a href="#section-5.4.2">section 5.4.2, "Creating a Bugzilla user for the replicator"</a>. </p>
<h4><a id="message-P4DTI-514X" name="message-P4DTI-514X"> (P4DTI-514X) There is no Bugzilla user corresponding to Perforce user '%s'. </a></h4>
<p> You have changed a user field in a job to a Perforce user who does not have a Bugzilla user record. The replicator is unable to replicate that field back to Bugzilla. </p>
<h4> <a id="message-P4DTI-5172" name="message-P4DTI-5172"> (P4DTI-5172) Can't create Bugzilla bug without short_desc field. </a><br />
<a id="message-P4DTI-5183" name="message-P4DTI-5183"> (P4DTI-5183) Can't create Bugzilla bug with empty short_desc field. </a><br />
<a id="message-P4DTI-5194" name="message-P4DTI-5194"> (P4DTI-5194) Can't create Bugzilla bug without product field. </a><br />
<a id="message-P4DTI-5208" name="message-P4DTI-5208"> (P4DTI-5208) Can't create Bugzilla bug for non-existent product '%s'. </a><br />
<a id="message-P4DTI-5219" name="message-P4DTI-5219"> (P4DTI-5219) Can't create Bugzilla bug for product '%s' with no components. </a><br />
<a id="message-P4DTI-522X" name="message-P4DTI-522X"> (P4DTI-522X) Can't create Bugzilla bug without component field. </a><br />
<a id="message-P4DTI-5230" name="message-P4DTI-5230"> (P4DTI-5230) Can't create Bugzilla bug: product '%s' has no component '%s'. </a><br />
<a id="message-P4DTI-5241" name="message-P4DTI-5241"> (P4DTI-5241) Can't create Bugzilla bug for product '%s' with no versions. </a><br />
<a id="message-P4DTI-5252" name="message-P4DTI-5252"> (P4DTI-5252) Can't create Bugzilla bug without version field. </a><br />
<a id="message-P4DTI-5263" name="message-P4DTI-5263"> (P4DTI-5263) Can't create Bugzilla bug: product '%s' has no version '%s'. </a><br />
<a id="message-P4DTI-5285" name="message-P4DTI-5285"> (P4DTI-5285) Can't create Bugzilla bug with invalid groupset '%s'. </a><br />
<a id="message-P4DTI-530X" name="message-P4DTI-530X"> (P4DTI-530X) Can't create Bugzilla bug with bug_status '%s' and no resolution. </a><br />
<a id="message-P4DTI-5310" name="message-P4DTI-5310"> (P4DTI-5310) Can't create Bugzilla bug with field '%s'. </a><br />
<a id="message-P4DTI-5321" name="message-P4DTI-5321"> (P4DTI-5321) Can't create Bugzilla bug without reporter field. </a></h4>
<p> The <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>
has tried to create a new bug in Bugzilla but the new bug doesn't
satisfy a Bugzilla constraint. There are two solutions: </p>
<ul>
<li><p> Edit the Perforce job so that it can be translated to a new
bug that does satisfy the constraint. </p></li>
<li><p> Change your <a
href="../aag/index.html#config-translate_jobspec"><code
class="source">translate_jobspec</code></a> and <a
href="../aag/index.html#config-prepare_issue"><code
class="source">prepare_issue</code></a> functions so that they satisfy
the constraint. Then </p>
<ul>
<li><p> If you were migrating, re-run the migration starting from
the job which couldn't be migrated [<a title="Perforce Defect
Tracking Integration Advanced Administrator's Guide"
href="../aag/index.html#section-4.10">GDR
2001-11-14, 4.10</a>]. </p></li>
<li><p> Otherwise, restart the replicator (see <a
href="#section-5.5">section 5.5</a>) and update the job so that it
is replicated again (by running a command like <code
class="command">p4 job -o <i>JOBNAME</i> | p4 job
-i</code>. </p></li>
</ul></li>
</ul>
<h4><a id="message-P4DTI-5354" name="message-P4DTI-5354"> (P4DTI-5354) '%s' not a Bugzilla group. </a></h4>
<p> An entry in <a
href="../aag/index.html#config-migrated_user_groups"><code
class="source">migrated_user_groups</code></a> is not a Bugzilla group.
Fix the parameter and re-run migration of users [<a title="Perforce
Defect Tracking Integration Advanced Administrator's Guide"
href="../aag/index.html#section-4.4">GDR
2001-11-14, 4.4</a>]. </p>
<h4><a id="message-P4DTI-5376" name="message-P4DTI-5376"> (P4DTI-5376) User %d is disabled, so cannot edit bug %d. </a></h4>
<h4><a id="message-P4DTI-5387" name="message-P4DTI-5387"> (P4DTI-5387) User 0 cannot edit bug %d. </a></h4>
<h4><a id="message-P4DTI-5398" name="message-P4DTI-5398"> (P4DTI-5398) Can't create Bugzilla bug with reporter 0. </a></h4>
<p>The P4DTI has attempted to create a new Bugzilla bug (either as
part of migration of pre-existing jobs or when replicating a
newly-created job), and was unable to deduce the reporting user. See
<a href="../aag/index.html#section-3">section 3,
"Allowing users to create ussies in Perforce"</a> and <a
href="../aag/index.html#section-4">section 4,
"Migrating to the defect tracker from Perforce jobs"</a> , of the
<cite><a href="../aag/index.html">Perforce Defect
Tracking Integration Advanced Administrator's
Guide</a></cite>. </p>
<h4><a id="message-P4DTI-5401" name="message-P4DTI-5401"> (P4DTI-5401) Can't change Bugzilla field '%s' to 0. </a></h4>
<p>A user in Perforce has changed one of the required user fields
("Reporter" or "Assigned_To") to "None". This value is only permitted
in the optional user field ("QA_Contact").</p>
<h4><a id="message-P4DTI-5423" name="message-P4DTI-5423"> (P4DTI-5423) Perforce P4DTI user '%s' is not a known Perforce user.</a></h4>
<p>The <a href="#config-p4_user">replicator Perforce user</a> is not
known to the Perforce server.</p>
<h4><a id="message-P4DTI-5434" name="message-P4DTI-5434"> (P4DTI-5434) Perforce P4DTI user '%s' has the same e-mail address '%s' as these other Perforce users: %s.</a></h4>
<p>The <a href="#config-p4_user">replicator Perforce user</a> has the
same e-mail address as one or more other Perforce users.</p>
<h4><a id="message-P4DTI-5456" name="message-P4DTI-5456"> (P4DTI-5456) Bugzilla P4DTI user e-mail address '%s' belongs to several Bugzilla users: %s.</a></h4>
<p>Several Bugzilla users have their e-mail address set to the <a
href="#config-replicator_address">replicator e-mail address</a>. This
should be the e-mail address of the Bugzilla P4DTI user only. See <a
href="#section-5.4.2">section 5.4.2</a>.</p>
<h4><a id="message-P4DTI-5503" name="message-P4DTI-5503"> (P4DTI-5503) Bugzilla P4DTI user '%s' does not have a matching Perforce user. It should match the Perforce user '%s' but that matches the Bugzilla user %d (e-mail address '%s').</a></h4>
<h4><a id="message-P4DTI-5514" name="message-P4DTI-5514"> (P4DTI-5514) Bugzilla P4DTI user '%s' does not have a matching Perforce user. It should match the Perforce user '%s' (which has e-mail address '%s').</a></h4>
<p>The Bugzilla P4DTI user (identified by the <a
href="#config-replicator_address">replicator e-mail address</a>)
should match the <a href="#config-p4_user">P4DTI Perforce user</a>,
but their e-mail addresses do not match.</p>
<h4><a id="message-P4DTI-6142" name="message-P4DTI-6142"> (P4DTI-6142) No transition from state '%s' to state '%s'. </a></h4>
<p> A user in Perforce has changed the state of a job in an illegal fashion (for example, changing the state from "assigned" to "verified", bypassing the state "resolved"). </p>
<p> 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. </p>
<h4><a id="message-P4DTI-6153" name="message-P4DTI-6153"> (P4DTI-6153) No login id in TeamTrack's USERS table corresponding to replicator's login id '%s'. </a></h4>
<p> The replicator couldn't find an entry in TeamTrack's table of users
for its own login id. Did you delete this user accidentally? If so,
add it again and restart the <abbr title="Perforce Defect Tracking
Integration">P4DTI</abbr>. If not, please contact Perforce support (see
<a href="#section-11.1">section 11.1, "Troubleshooting"</a>). </p>
<h4><a id="message-P4DTI-6164" name="message-P4DTI-6164"> (P4DTI-6164) No LAST_CHANGE record for this replicator. </a></h4>
<p> Someone has reconnected the TeamTrack server to a new TeamTrack database without first stopping the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>. Either reconnect to the old TeamTrack database or restart the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>. </p>
<h4><a id="message-P4DTI-6175" name="message-P4DTI-6175"> (P4DTI-6175) TeamTrack database version %d is not supported by the P4DTI. The minimum supported version is %d. </a></h4>
<p> You're running an old version of TeamTrack that isn't supported by the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>. Upgrade your TeamTrack server to a supported version. See <a href="#section-3.3.1">section 3.3.1, "TeamTrack software prerequisites"</a>. </p>
<h4><a id="message-P4DTI-6186" name="message-P4DTI-6186"> (P4DTI-6186) Incorrect date in Perforce: '%s' is not in the format 'YYYY/mm/dd HH:MM:SS'. </a></h4>
<p> You've entered something in a date/time field in Perforce that
couldn't be recognized as a date and time. Date/time values in Perforce
must be in the format year/month/day hour:minutes:seconds, with four
digits for the year, and two digits for everything else. For example,
<code class="source">2001/08/04 04:14:56</code>. </p>
<h4><a id="message-P4DTI-6197" name="message-P4DTI-6197"> (P4DTI-6197) Incorrect time in Perforce: '%s' is not in the format 'H:MM:SS'.</a></h4>
<p> You've entered something in an elapsed time field in Perforce that
couldn't be recognized as an elapsed time. Elapsed time values in
Perforce must be in the format <code class="source">H:MM:SS</code>. For
example <code class="source">4:14:56</code> or <code
class="source">100:00:00</code>. </p>
<h4><a id="message-P4DTI-6211" name="message-P4DTI-6211"> (P4DTI-6211) No TeamTrack entity in table '%s' with id %d. </a><br />
<a id="message-P4DTI-6233" name="message-P4DTI-6233"> (P4DTI-6233) No TeamTrack selection name for selection id '%d'. </a><br />
<a id="message-P4DTI-6266" name="message-P4DTI-6266"> (P4DTI-6266) No state name for TeamTrack state %d. </a></h4>
<p> The TeamTrack database is inconsistent: a foreign key reference was
not found. If you've recently edited your TeamTrack workflow, then this
might be due to a race condition; try restarting the replicator (see <a
href="#section-5.5">section 5.5</a>). If the problem persists, contact
Perforce support (see <a href="#section-11.1">section 11.1,
"Troubleshooting"</a>). </p>
<h4><a id="message-P4DTI-6222" name="message-P4DTI-6222"> (P4DTI-6222) No TeamTrack entity in table '%s' with name '%s'. </a><br />
<a id="message-P4DTI-6244" name="message-P4DTI-6244"> (P4DTI-6244) No TeamTrack selection for field '%s' corresponding to Perforce selection '%s'. </a><br />
<a id="message-P4DTI-6277" name="message-P4DTI-6277"> (P4DTI-6277) Perforce state '%s' is unknown. </a><br />
<a id="message-P4DTI-6426" name="message-P4DTI-6426"> (P4DTI-6426) No TeamTrack state corresponding to Perforce state '%s'. </a></h4>
<p> A Perforce job has a field with a value that's illegal in TeamTrack
(for example, a non-existent project). Either correct the job so that
all fields are legal, or update your TeamTrack workflow to add the new
value and restart the replicator (see <a href="#section-5.5">section
5.5</a>). </p>
<h4><a id="message-P4DTI-6255" name="message-P4DTI-6255"> (P4DTI-6255) No Perforce state corresponding to TeamTrack state '%s'.</a></h4>
<p> The replicator is trying to replicate an issue in TeamTrack that
can't be translated to Perforce because its state is unknown. </p>
<p> This can happen if you've added a state to the TeamTrack workflow.
In that case you need to restart the replicator (see <a
href="#section-5.5">section 5.5</a>). </p>
<p> It can also happen if you've set <a
href="#config-use_deleted_selections"><code
class="source">use_deleted_selections</code></a> to 0 but there's an
issue in a deleted state. See that configuration parameter for
advice. </p>
<h4><a id="message-P4DTI-6288" name="message-P4DTI-6288"> (P4DTI-6288) No TeamTrack state in project '%s' corresponding to Perforce state '%s'. </a></h4>
<p> A user in Perforce changed the state of a job to a state that is not legal for the project to which the job belongs. (Note that the state is legal in some other project, otherwise it wouldn't be possible to set the job to that state.) </p>
<p> 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. </p>
<p> 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. </p>
<p> (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.) </p>
<h4><a id="message-P4DTI-6335" name="message-P4DTI-6335"> (P4DTI-6335) The TeamTrack field %s is append-only: you're not allowed to edit previous comments. </a></h4>
<p> A user in Perforce has updated other users' comments in an
append-only journal field; this isn't allowed. Either edit the field
properly (by adding new material at the end), or else change the field
definition in TeamTrack so that it's no longer append-only (in the
TeamTrack Administrator, select the "Workflows" tab, choose the
workflow, click "Edit...", select the "Default Fields" tab, choose the
field, click "Edit...", select the "Options" tab, uncheck the "Append
only" checkbox, click "OK", click "OK") and restart the replicator (see
<a href="#section-5.5">section 5.5</a>). </p>
<h4><a id="message-P4DTI-6404" name="message-P4DTI-6404"> (P4DTI-6404) Can't submit new issue to TeamTrack: SUBMITTER %d is unknown. </a></h4>
<p> When creating a new issue in TeamTrack based on a job in Perforce,
the replicator couldn't guess a good value for the
<code>SUBMITTER</code> field in TeamTrack. TeamTrack requires this
field to contain a valid user. Possible causes are: </p>
<ul>
<li><p> A Perforce user couldn't be translated to a TeamTrack user.
Fix the problem and try again. See <a href="#section-3.5">section
3.5, "User accounts"</a>. </p></li>
<li><p> The replicator's guessing algorithm has failed (it looks in
the <code>P4DTI-user</code>, <code>Owner</code> and <code>User</code>
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
<a
href="../aag/index.html#config-prepare_issue"><code
class="source">prepare_issue</code></a> function; then </p>
<ul>
<li><p> If you were migrating, re-run the migration starting from
the job which couldn't be migrated [<a title="Perforce Defect
Tracking Integration Advanced Administrator's Guide"
href="../aag/index.html#section-4.10">GDR
2001-11-14, 4.10</a>]. </p></li>
<li><p> Otherwise, restart the replicator (see <a
href="#section-5.5">section 5.5</a>) and update the job so that it
is replicated again (by running a command like <code
class="command">p4 job -o <i>JOBNAME</i> | p4 job
-i</code>. </p></li>
</ul></li>
</ul>
<h4><a id="message-P4DTI-6415" name="message-P4DTI-6415"> (P4DTI-6415) Submitted new issue to TeamTrack with issue id %05d, but couldn't find it in the database. </a></h4>
<p> The replicator couldn't find a newly-submitted issue in the
TeamTrack database. Please contact Perforce support (see <a
href="#section-11.1">section 11.1, "Troubleshooting"</a>). </p>
<h4><a id="message-P4DTI-7043" name="message-P4DTI-7043"> (P4DTI-7043) Perforce client changelevel %d is not supported by P4DTI. Client must be at changelevel %d or above. </a></h4>
<p> The Perforce client executable specified by the <a href="#config-p4_client_executable"><code class="source">p4_client_executable</code></a> parameter is an old version not supported by the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>. Install a supported version (see <a href="#section-3.2.1">section 3.2.1, "Perforce software prerequisites"</a>) and set the <a href="#config-p4_client_executable"><code class="source">p4_client_executable</code></a> parameter to name it. </p>
<h4><a id="message-P4DTI-7054" name="message-P4DTI-7054"> (P4DTI-7054) The command '%s' didn't report a recognizable version number. Check your setting for the 'p4_client_executable' parameter. </a></h4>
<p> Your setting for the <a href="#config-p4_client_executable"><code class="source">p4_client_executable</code></a> parameter doesn't name a Perforce client executable (or doesn't name one that's supported by the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>. Correct your setting. </p>
<h4><a id="message-P4DTI-7076" name="message-P4DTI-7076"> (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. </a></h4>
<p> Check your setting for the <a href="#config-p4_port"><code
class="source">p4_port</code></a> parameter. Check that the Perforce
server is running happily. Check that it has enough disk space. Check
that your Perforce licence is up to date. </p>
<h4><a id="message-P4DTI-7065" name="message-P4DTI-7065"> (P4DTI-7065) %s The Perforce client exited with error code %d. </a><br />
<a id="message-P4DTI-7087" name="message-P4DTI-7087"> (P4DTI-7087) %s </a></h4>
<p> There's a problem with Perforce. Look up the text of the error message in <a href="#section-11.3">section 11.3, "Other error messages"</a>, for advice. </p>
<h4><a id="message-P4DTI-7098" name="message-P4DTI-7098"> (P4DTI-7098) The Perforce interface does not support the operating system '%s'. </a></h4>
<p> You've installed the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> on an unsupported operating system. See the release notes for details of the supported operating systems. </p>
<h4><a id="message-P4DTI-7101" name="message-P4DTI-7101"> (P4DTI-7101) Jobspec fields '%s' and '%s' have the same number %d. </a></h4>
<p> The replicator was trying to install a new Perforce jobspec, but it
can't because two fields have the same field number (field number is a
unique key in Perforce). If you're using advanced configuration [<a
title="Perforce Defect Tracking Integration Integrator's Guide"
href="../ig/index.html#section-8.6">GDR 2000-10-16,
8.6</a>], then check that your <a
href="../ig/index.html#config-jobspec"><code
class="source">jobspec</code></a> configuration parameter gives unique
numbers to each field; see [<a title="Perforce Defect Tracking
Integration Integrator's Guide"
href="../ig/index.html#section-8.4">GDR 2000-10-16,
8.4</a>]. Otherwise, contact Perforce support (see <a
href="#section-11.1">section 11.1, "Troubleshooting"</a>). </p>
<h4><a id="message-P4DTI-8341" name="message-P4DTI-8341"> (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. </a><br />
<a id="message-P4DTI-8352" name="message-P4DTI-8352"> (P4DTI-8352) The Perforce command 'p4 info' didn't report a recognisable version. </a></h4>
<p> You are running a version of the Perforce server that is not
supported by the <abbr title="Perforce Defect Tracking
Integration">P4DTI</abbr>. See the release notes for supported Perforce
server versions. </p>
<h4><a id="message-P4DTI-8363" name="message-P4DTI-8363"> (P4DTI-8363) P4DTI fields not found in Perforce jobspec. </a></h4>
<p> If you're using advanced configuration [<a title="Perforce Defect
Tracking Integration Integrator's Guide"
href="../ig/index.html#section-8.6">GDR 2000-10-16,
8.6</a>], then check that your <a
href="../ig/index.html#config-jobspec"><code
class="source">jobspec</code></a> configuration parameter has the
required <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>
fields; see [<a title="Perforce Defect Tracking Integration Integrator's
Guide" href="../ig/index.html#section-8.4">GDR
2000-10-16, 8.4</a>]. Otherwise, contact Perforce support (see <a
href="#section-11.1">section 11.1, "Troubleshooting"</a>). </p>
<h4><a id="message-P4DTI-8727" name="message-P4DTI-8727"> (P4DTI-8727) Issue '%s' should be replicated but is not. </a><br />
<a id="message-P4DTI-8738" name="message-P4DTI-8738"> (P4DTI-8738) Issue '%s' should be replicated to job '%s' but that job either does not exist or is not replicated. </a><br />
<a id="message-P4DTI-8749" name="message-P4DTI-8749"> (P4DTI-8749) Issue '%s' is replicated to job '%s' but that job is replicated to issue '%s'. </a><br />
<a id="message-P4DTI-875X" name="message-P4DTI-875X"> (P4DTI-875X) Job '%s' would need the following set of changes in order to match issue '%s': %s. </a><br />
<a id="message-P4DTI-8760" name="message-P4DTI-8760"> (P4DTI-8760) Job '%s' has associated filespec '%s' but there is no corresponding filespec for issue '%s'. </a><br />
<a id="message-P4DTI-8771" name="message-P4DTI-8771"> (P4DTI-8771) Issue '%s' has associated filespec '%s' but there is no corresponding filespec for job '%s'. </a><br />
<a id="message-P4DTI-8782" name="message-P4DTI-8782"> (P4DTI-8782) Change %s fixes job '%s' but there is no corresponding fix for issue '%s'. </a><br />
<a id="message-P4DTI-8793" name="message-P4DTI-8793"> (P4DTI-8793) Change %d fixes issue '%s' but there is no corresponding fix for job '%s'. </a><br />
<a id="message-P4DTI-8807" name="message-P4DTI-8807"> (P4DTI-8807) Change %s fixes job '%s' with status '%s', but change %d fixes issue '%s' with status '%s'. </a><br />
<a id="message-P4DTI-8818" name="message-P4DTI-8818"> (P4DTI-8818) Job '%s' is marked as being replicated to issue '%s' but that issue is being replicated to job '%s'. </a><br />
<a id="message-P4DTI-8829" name="message-P4DTI-8829"> (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. </a><br />
<a id="message-P4DTI-8862" name="message-P4DTI-8862"> (P4DTI-8862) 1 inconsistency found. </a><br />
<a id="message-P4DTI-8873" name="message-P4DTI-8873"> (P4DTI-8873) %d inconsistencies found. </a><br />
<a id="message-P4DTI-8884" name="message-P4DTI-8884"> (P4DTI-8884) Asked for issue '%s' but got an error instead. </a><br />
<a id="message-P4DTI-8895" name="message-P4DTI-8895"> (P4DTI-8895) Job '%s' has a date field in the wrong format: %s. </a></h4>
<p> The Perforce jobs database is inconsistent with the TeamTrack
database. This might be a consequence of frequent activity in the two
systems (because the <abbr title="Perforce Defect Tracking
Integration">P4DTI</abbr> works by polling, there's a delay between
changing one system and the the other system being brought up to date);
if so, the databases will be made consistent if you cease activity and
poll twice (<a href="#section-7.1">section 7.1, "Taking a single
step"</a>). </p>
<p> 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 (<a href="#section-9.2">section 9.2,
"Refreshing jobs in Perforce"</a>). </p>
<p> If that doesn't work, contact Perforce support (see <a
href="#section-11.1">section 11.1, "Troubleshooting"</a>). </p>
<h4><a id="message-P4DTI-891X" name="message-P4DTI-891X"> (P4DTI-891X) Error (%s): %s </a></h4>
<p> There's a problem in the defect tracker. Look up the text of the error message in <a href="#section-11.3">section 11.3, "Other error messages"</a>, for advice. </p>
<h4><a id="message-P4DTI-9060" name="message-P4DTI-9060"> (P4DTI-9060) Defect tracker '%s' does not support migration of Perforce users. </a></h4>
<p> The <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>
doesn't provide automated support for migrating users from Perforce to
TeamTrack. You have to create new uses in TeamTrack by hand using the
TeamTrack Administrator. </p>
<h4><a id="message-P4DTI-913X" name="message-P4DTI-913X"> (P4DTI-913X) Error in P4DTI logger: %s </a></h4>
<p> Something's gone wrong with the P4DTI logger. Look up the text of
the error message in <a href="#section-11.3">section 11.3, "Other error
messages"</a>, for advice. </p>
<h4><a id="message-P4DTI-9242" name="message-P4DTI-9242"> (P4DTI-9242) Expected translate_jobspec to return a dictionary, but instead it returned %s. </a></h4>
<p> Check that you have a line like <code class="source">return
job</code> at the end of your <a
href="../aag/index.html#config-translate_jobspec"><code
class="source">translate_jobspec</code></a> function. </p>
<h4><a id="message-P4DTI-10037" name="message-P4DTI-10037"> (P4DTI-10037) TeamTrack version %s is not supported by the P4DTI. </a></h4>
<p> Check your setting for the <a href="#config-teamtrack_version"><code class="source">teamtrack_version</code></a> parameter. See the release notes for the supported versions. </p>
<h4><a id="message-P4DTI-10059" name="message-P4DTI-10059"> (P4DTI-10059) MySQLdb version '%s' (release '%s') detected. This release is incompatible with the P4DTI.</a></h4>
<p> You're using a release of the Python database module MySQLdb which is known to be incompatible with the P4DTI. Install a supported release of MySQLdb. See <a href="#section-3.4.1">section 3.4.1, "Bugzilla software prerequisites"</a>. </p>
<h4><a id="message-P4DTI-1006X" name="message-P4DTI-1006X"> (P4DTI-1006X) MySQLdb version '%s' (release '%s') detected. This release is not supported by the P4DTI, but may work. </a></h4>
<p> You're using a release of the Python database module MySQLdb which is not supported by the P4DTI, but which may work anyway. If you have problems accessing the Bugzilla database, install a supported release of MySQLdb. See <a href="#section-3.4.1">section 3.4.1, "Bugzilla software prerequisites"</a>. </p>
<h4><a id="message-P4DTI-10106" name="message-P4DTI-10106"> (P4DTI-10106) Fatal error in P4DTI service: %s. </a></h4>
<p> Something's happened to the <abbr title="Perforce Defect Tracking
Integration">P4DTI</abbr> when running as an NT service. Look up the
text of the error message in <a href="#section-11.3">section 11.3,
"Other error messages"</a>, for advice. </p>
<h4><a id="message-P4DTI-10172" name="message-P4DTI-10172"> (P4DTI-10172) An attempt to write a log message to standard output failed. </a></h4>
<p> Something has gone wrong with the standard output of the replicator.
This can happen if standard output was originally connected to a
terminal, but the terminal has been closed without stopping the
replicator. </p>
<p> The remedy is to start the replicator with the startup script, as
described in <a href="#section-5.6.1">section 5.6.1, "Running
automatically on Unix"</a>, or to redirect the standard output to
somewhere safe, for example </p>
<blockquote><code class="command">python run.py > /dev/null</code></blockquote>
<h3><a id="section-11.3" name="section-11.3">11.3. Other Error messages</a></h3>
<h4><a id="error-Perl-1" name="error-Perl-1">Insecure $ENV{BASH_ENV} while running with -T switch at ./processmail line %d</a></h4>
<p> You're using Bugzilla 2.14, 2.14.1, 2.14.4, or 2.16.1, but the
patch hasn't been applied yet. See <a href="#section-5.4.1">section
5.4.1, "Patching Bugzilla"</a>. </p>
<h4><a id="error-_mysql.InternalError-1" name="error-_mysql.InternalError-1">_mysql.InternalError: (3, "Error writing file '%s' (Errcode: 28)")</a></h4>
<p> We've seen this error when MySQL has run out of disk space. </p>
<h4><a id="error-_mysql.OperationalError-1" name="error-_mysql.OperationalError-1">_mysql.OperationalError: (1045, "Access denied for user: '%s@%s' (Using password: NO)")</a></h4>
<p> The <a href="#config-dbms_user"><code class="source">dbms_user</code></a> parameter is set incorrectly or the <a href="#config-dbms_password"><code class="source">dbms_password</code></a> parameter is set to None when a password is required. </p>
<h4><a id="error-_mysql.OperationalError-2" name="error-_mysql.OperationalError-2">_mysql.OperationalError: (1045, "Access denied for user: '%s@%s' (Using password: YES)")</a></h4>
<p> The <a href="#config-dbms_password"><code class="source">dbms_password</code></a> parameter is set incorrectly. </p>
<h4><a id="error-_mysql.OperationalError-3" name="error-_mysql.OperationalError-3">_mysql.OperationalError: (1049, "Unknown database '%s'")</a></h4>
<p> The MySQL server on <a href="#config-dbms_host"><code class="source">dbms_host</code></a> doesn't serve a database whose name matches the <a href="#config-dbms_database"><code class="source">dbms_database</code></a> parameter. </p>
<h4><a id="error-_mysql.OperationalError-4" name="error-_mysql.OperationalError-4">_mysql.OperationalError: (2003, "Can't connect to MySQL server on '%s' (111)")</a></h4>
<p> A MySQL connection couldn't be established to the host given by the <a href="#config-dbms_host"><code class="source">dbms_host</code></a> parameter on either the port given by the <a href="#config-dbms_port"><code class="source">dbms_port</code></a> parameter or the default MySQL port 3306. Possible causes include: </p>
<ul>
<li>The MySQL server is down.</li>
<li>The MySQL server is configured to serve on a different port number</li>
</ul>
<h4><a id="error-_mysql.OperationalError-5" name="error-_mysql.OperationalError-5">_mysql.OperationalError: (2005, "Unknown MySQL Server Host '%s' (2)")</a></h4>
<p> The host given by the <a href="#config-dbms_host"><code class="source">dbms_host</code></a> parameter could not be located. </p>
<h4><a id="error-_mysql.OperationalError-6" name="error-_mysql.OperationalError-6">_mysql.OperationalError: (2006, 'MySQL server has gone away')</a></h4>
<p> The connection to the MySQL server has been lost. The replicator
will recover when the server connection is re-established. </p>
<h4><a id="message-Perforce-Error-1" name="message-Perforce-Error-1">Perforce error: Can't create a new user - over licence quota</a></h4>
<p> You don't have a licence for the replicator. See <a href="#section-3.2.1">section 3.2.1, "Perforce software prerequisites"</a>. </p>
<p> This might be because you changed the <a
href="#config-p4_user"><code class="source">p4_user</code></a> parameter
but didn't delete the old userid. </p>
<h4><a id="message-Perforce-Error-2" name="message-Perforce-Error-2">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.</a></h4>
<p> You're using a Perforce client that's incompatible with the Perforce server (for example, you're using a Perforce 2000.2 client to connect to a Perforce 2001.1 server). Check your setting for the <a href="#config-p4_client_executable"><code class="source">p4_client_executable</code></a> parameter. </p>
<h4><a id="message-Perforce-Error-3" name="message-Perforce-Error-3">Perforce error: Error detected at line %d. Value for field '%s' must be one of %s.</a></h4>
<p> The replicator is trying to replicate an issue that's has a
selection that isn't valid in Perforce. </p>
<p> 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 <a
href="#section-5.5">section 5.5</a>). </p>
<p> It can also happen if you've set <a
href="#config-use_deleted_selections"><code class="source">use_deleted_selections</code></a>
to 0 but there's an issue with a deleted option. See that configuration
parameter for advice. </p>
<h4><a id="message-Perforce-Error-4" name="message-Perforce-Error-4"> Perforce error: You don't have permission for this operation </a></h4>
<p> You haven't given the replicator permission to edit the Perforce jobspec. The replicator needs to have superuser privileges in Perforce. For instructions, see <a href="#section-5.2.1">section 5.2.1, "Creating a Perforce user for the replicator"</a>. </p>
<h4><a id="error-socket.error-1" name="error-socket.error-1">socket.error: (10222, 'invalid argument')</a></h4>
<p> Your SMTP server may be refusing connections. Check your <a
href="#config-smtp_server"><code class="source">smtp_server</code></a>
parameter. Check that your SMTP server is up and running. </p>
<h4><a id="error-socket.error-2" name="error-socket.error-2">socket.error: host not found</a></h4>
<p> You may have specified the wrong hostname for the SMTP server.
Check your <a href="#config-smtp_server"><code
class="source">smtp_server</code></a> parameter. Check that your SMTP
server is up and running. </p>
<h4><a id="error-TeamShare-API-Error-1" name="error-TeamShare-API-Error-1">TeamShare <abbr title="Application Programmer Interface">API</abbr> error: ERROR: (no message from the TeamShare <abbr title="Application Programmer Interface">API</abbr>)</a></h4>
<p> This means that TeamTrack reported an error, but provided no information about the cause of the error. The Windows Application Log on the TeamTrack server machine often contains more information about why problems are occurring. Use the Event Viewer to examine the Windows Application Log on that machine. </p>
<p> This might be because you are using TeamTrack version 5.0 or later,
but you specified <code class="source">teamtrack_version = "4.5"</code>.
Check your setting for the <a href="#config-teamtrack_version"><code
class="source">teamtrack_version</code></a> parameter. </p>
<h4><a id="error-TeamShare-API-Error-7" name="error-TeamShare-API-Error-7">TeamShare <abbr title="Application Programmer Interface">API</abbr> error: ERROR: Unable to find transition 0.</a></h4>
<p> The replicator user may not have the "Update All Issues"
privilege. Check the privileges for the replicator user: see <a
href="#section-5.3.2">section 5.3.2, "Creating a TeamTrack user for the
replicator"</a>. </p>
<h4><a id="error-TeamShare-API-Error-2" name="error-TeamShare-API-Error-2">TeamShare <abbr title="Application Programmer Interface">API</abbr> error: SERVER_ERROR: Authentication Failed. Invalid user id or password</a></h4>
<p> You haven't created a user in TeamTrack for the replicator (for instructions, see <a href="#section-5.3.2">section 5.3.2, "Creating a TeamTrack user for the replicator"</a>), or else you've given the replicator incorrect values for the <a href="#config-teamtrack_user"><code class="source">teamtrack_user</code></a> and <a href="#config-teamtrack_password"><code class="source">teamtrack_password</code></a> parameters. </p>
<h4><a id="error-TeamShare-API-Error-3" name="error-TeamShare-API-Error-3">TeamShare <abbr title="Application Programmer Interface">API</abbr> error: SERVER_ERROR: Access Denied. You do not have <abbr title="Application Programmer Interface">API</abbr> connect privileges.</a></h4>
<p> The replicator's TeamTrack user lacks the "Connect using the <abbr title="Application Programmer Interface">API</abbr>" privilege. You need to use the TeamTrack Administrator to assign this privilege. See <a href="#section-5.3.2">section 5.3.2, "Creating a TeamTrack user for the replicator"</a>. </p>
<h4><a id="error-TeamShare-API-Error-6" name="error-TeamShare-API-Error-6">TeamShare <abbr title="Application Programmer Interface">API</abbr> error: SERVER_ERROR: Server error: -1.</a></h4>
<p> You may be using TeamTrack 4.5 but have specified <code
class="source"><a href="#config-teamtrack_version">teamtrack_version</a>
= "5.0"</code>. Check your setting for the <a
href="#config-teamtrack_version"><code
class="source">teamtrack_version</code></a> parameter. </p>
<p> Or your TeamTrack server may be running on a secure web server (its
address starts <code class="source">https:</code>). The <abbr
title="Perforce Defect Tracking Integration">P4DTI</abbr> does not
support TeamTrack on a secure web server. </p>
<h4><a id="error-TeamShare-API-Error-4" name="error-TeamShare-API-Error-4">TeamShare <abbr title="Application Programmer Interface">API</abbr> error: SOCKET_CONNECT_FAILED: Socket Connect failed.</a></h4>
<p> The <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> can't connect to the TeamTrack server. Check
that TeamTrack is up and running. Check your setting for the <a
href="#config-teamtrack_server"><code
class="source">teamtrack_server</code></a> parameter. </p>
<h4><a id="error-TeamShare-API-Error-8" name="error-TeamShare-API-Error-8">TeamShare <abbr title="Application Programmer Interface">API</abbr> error: SOCKET_READ_ERROR: Authentication Failed. No user information.</a></h4>
<p> TeamTrack is not accepting authentication information from the HTTP
header because you have turned off this feature. </p>
<p> Set up TeamTrack to accept authentication information from the HTTP
header. In the TeamTrack Administrator, choose Options > Settings;
choose the <span class="gui">Server</span> tab; click the <span
class="gui">"Accept Info From Browser/Header"</span> checkbox. (Note
that you do not have to turn off the <span class="gui">"Accept Info From
Form/URL/Cookie"</span> checkbox. If both boxes are checked, TeamTrack
tries to get the authentication information from a cookie first, and the
HTTP header second.) </p>
<h4><a id="error-TeamShare-API-Error-5" name="error-TeamShare-API-Error-5">TeamShare <abbr title="Application Programmer Interface">API</abbr> error: SOCKET_READ_ERROR: Socket error.</a></h4>
<p> You may have tried to connect to a TeamTrack server with an
incorrect user id or password. Check your settings for the <a
href="#config-teamtrack_user"><code
class="source">teamtrack_user</code></a> and <a
href="#config-teamtrack_password"><code
class="source">teamtrack_password</code></a> parameters. </p>
<p> The replicator user may not have the "Connect using the API"
privilege. Check the privileges for the replicator user: see <a
href="#section-5.3.2">section 5.3.2, "Creating a TeamTrack user for the
replicator"</a>. </p>
<h2><a id="section-A" name="section-A">A. References</a></h2>
<table>
<tr valign="top">
<td>[<a id="ref-BeOpen-PythonLabs-2000-10-16" name="ref-BeOpen-PythonLabs-2000-10-16" href="http://www.python.org/doc/current/tut/tut.html">BeOpen PythonLabs 2000-10-16</a>]</td>
<td>
"Python Tutorial";
Guido van Rossum (Fred L. Drake, Jr., editor);
<a href="http://www.python.org/doc/current/tut/tut.html">BeOpen PythonLabs</a>;
2000-10-16;
<<a href="http://www.python.org/doc/current/tut/tut.html">http://www.python.org/doc/current/tut/tut.html</a>>.
</td>
</tr>
<tr valign="top">
<td>[<a id="ref-Bugzilla-1999-02-25" name="ref-Bugzilla-1999-02-25" href="http://www.ravenbrook.com/project/p4dti/import/2000-05-09/bugzilla-2.10/bugzilla-2.10/README">Bugzilla 1999-02-25</a>]</td>
<td>
Bugzilla 2.10 Installation README file;
Ry4an Brase, Bryce Nesbitt, Dan Mosedale, Martin Pool, Terry Weissman;
<a href="http://www.mozilla.org/">The Mozilla Organization</a>;
1999-02-25
</td>
</tr>
<tr valign="top">
<td>[<a id="ref-Bugzilla-2002-09-30" name="ref-Bugzilla-2002-09-30" href="http://www.ravenbrook.com/project/p4dti/import/2002-09-30/bugzilla-2.14.4/bugzilla-2.14.4/docs/html/">Bugzilla 2002-09-30</a>]</td>
<td>
"The Bugzilla Guide" (for Bugzilla 2.14.4);
<a href="mailto:barnboy@trilobyte.net">Matthew P Barnson</a>;
2002-09-30.
</td>
</tr>
<tr valign="top">
<td>[<a id="ref-GDR-2001-11-14" name="ref-GDR-2001-11-14" href="../aag/index.html">GDR 2001-11-14</a>]</td>
<td>
"Perforce Defect Tracking Integration Advanced Administrator's Guide";
<a href="mailto:gdr@ravenbrook.com">Gareth Rees</a>;
<a href="http://www.ravenbrook.com/">Ravenbrook Limited</a>;
2001-11-14.
</td>
</tr>
<tr valign="top">
<td>[<a id="ref-MySQL-2000-07-02" name="ref-MySQL-2000-07-02" href="http://www.ravenbrook.com/project/p4dti/import/2000-07-02/MySQL-3.23.20-Reference.html">MySQL 2000-07-02</a>]</td>
<td>
"MySQL Reference Manual for version 3.23.20-beta";
<a href="http://www.mysql.com/">MySQL</a>;
2000-07-02.
</td>
</tr>
<tr valign="top">
<td>[<a id="ref-Perforce-2001-06-18a" name="ref-Perforce-2001-06-18a" href="http://www.perforce.com/perforce/doc.011/manuals/p4guide/">Perforce 2001-06-18a</a>]</td>
<td>
"Perforce 2001.1 Command Line User's Guide";
<a href="http://www.perforce.com/">Perforce Software</a>;
2001-06-18;
<<a href="http://www.perforce.com/perforce/doc.011/manuals/p4guide/">http://www.perforce.com/perforce/doc.011/manuals/p4guide/</a>>, <<a href="ftp://ftp.perforce.com/pub/perforce/r01.1/doc/manuals/p4guide/p4guide.pdf">ftp://ftp.perforce.com/pub/perforce/r01.1/doc/manuals/p4guide/p4guide.pdf</a>>.
</td>
</tr>
<tr valign="top">
<td>[<a id="ref-Perforce-2001-06-18b" name="ref-Perforce-2001-06-18b" href="http://www.perforce.com/perforce/doc.011/manuals/p4sag/">Perforce 2001-06-18b</a>]</td>
<td>
"Perforce 2001.1 System Administrator's Guide";
<a href="http://www.perforce.com/">Perforce Software</a>;
2001-06-18;
<<a href="http://www.perforce.com/perforce/doc.011/manuals/p4sag/">http://www.perforce.com/perforce/doc.011/manuals/p4sag/</a>>, <<a href="ftp://ftp.perforce.com/pub/perforce/r01.1/doc/manuals/p4sag/p4sag.pdf">ftp://ftp.perforce.com/pub/perforce/r01.1/doc/manuals/p4sag/p4sag.pdf</a>>.
</td>
</tr>
<tr valign="top">
<td>[<a id="ref-RB-2000-08-10" name="ref-RB-2000-08-10" href="../ug/index.html">RB 2000-08-10</a>]</td>
<td>
"Perforce Defect Tracking Integration User's Guide";
<a href="mailto:rb@ravenbrook.com">Richard Brooksby</a>;
<a href="http://www.ravenbrook.com/">Ravenbrook Limited</a>;
2000-08-10.
</td>
</tr>
<tr valign="top">
<td>[<a id="ref-GDR-2000-10-16" name="ref-GDR-2000-10-16" href="../ig/index.html">GDR 2000-10-16</a>]</td>
<td>
"Perforce Defect Tracking Integration Integrator's Guide";
<a href="mailto:gdr@ravenbrook.com">Gareth Rees</a>;
<a href="http://www.ravenbrook.com/">Ravenbrook Limited</a>;
2000-10-16.
</td>
</tr>
<tr valign="top">
<td>[<a id="ref-TeamShare-2002-01-31" name="ref-TeamShare-2002-01-31">TeamShare 2002-01-31</a>]</td>
<td>
"TeamTrack Administrator Manual 5.5";
<a href="http://www.teamshare.com/">TeamShare</a>;
2002-01-31.
</td>
</tr>
</table>
<h2><a id="section-B" name="section-B">B. Document History</a></h2>
<table>
<tr valign="top">
<td>2000-08-10</td>
<td><a href="mailto:rb@ravenbrook.com">RB</a></td>
<td>Created placeholder.</td>
</tr>
<tr valign="top">
<td>2000-09-11</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Added instructions for demonstrating the integration and notes on
version 0.2.</td>
</tr>
<tr valign="top">
<td>2000-09-20</td>
<td><a href="mailto:rb@ravenbrook.com">RB</a></td>
<td>Replaced demo instructions with full documentation outline from documentation plan.</td>
</tr>
<tr valign="top">
<td>2000-10-15</td>
<td><a href="mailto:rb@ravenbrook.com">RB</a></td>
<td>Added installation and uninstallation sections, and other sections discussed in [RB 2000-10-07]. Removed parts specific to Ravenbrook Information System.</td>
</tr>
<tr valign="top">
<td>2000-10-16</td>
<td><a href="mailto:rb@ravenbrook.com">RB</a></td>
<td>Merged with master sources and GDR's demonstration instructions for version 0.2. More edits required to make this consistent with the master sources.</td>
</tr>
<tr valign="top">
<td>2000-10-19</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Updated to fix defects in release 0.3.1 [<a
href="http://www.ravenbrook.com/project/p4dti/doc/2000-10-17/release-0.3.1-test-report/">GDR
2000-10-17a</a>] and release 0.3.2 [<a
href="http://www.ravenbrook.com/project/p4dti/doc/2000-10-18/release-0.3.2-test-report/">RB
2000-10-18b</a>].</td>
</tr>
<tr valign="top">
<td>2000-11-25</td>
<td><a href="mailto:lmb@ravenbrook.com">LMB</a></td>
<td>Removed "system" from title. Made lots of minor formatting and transition
edits. Moved Glossary to end of document. Reorganized Section 4.</td>
</tr>
<tr valign="top">
<td>2000-11-26</td>
<td><a href="mailto:rb@ravenbrook.com">RB</a></td>
<td> Improved prerequisites section. Added draft Bugzilla prerequisites. Formatted troubleshooting section. Updated version 0.3 references to version 0.4. </td>
</tr>
<tr valign="top">
<td>2000-11-27</td>
<td><a href="mailto:rb@ravenbrook.com">RB</a></td>
<td>Added readership. Removed some false statements.</td>
</tr>
<tr valign="top">
<td>2000-11-29</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Revised section 5 (configuration) to explain how to use the automatic configuration engine for TeamTrack. Moved material from sections 4 and 5 to make an appendix E for advanced configuration. Added section 4.6, a placeholder that will describe how to create a Perforce user for the replicator. The integration with TeamTrack now requires Python 2.0.</td>
</tr>
<tr valign="top">
<td>2000-11-29</td>
<td><a href="mailto:rb@ravenbrook.com">RB</a></td>
<td>Corrected overview and improved replicator diagram. Changed prerequisites to point at Perforce 2000.2 beta release. Added proper text to Bugzilla prerequisites section. Cross-referenced to User's Guide. </td>
</tr>
<tr valign="top">
<td>2000-11-29</td>
<td><a href="mailto:lmb@ravenbrook.com">LMB</a></td>
<td>Changed "—" to "--" because the former doesn't display properly in Netscape. Made some minor edits in Sections 1-3.</td>
</tr>
<tr valign="top">
<td>2000-11-30</td>
<td><a href="mailto:lmb@ravenbrook.com">LMB</a></td>
<td>Corrected figure numbers in the text that were off by one. Finished editing the <abbr title="Administrator's Guide">AG</abbr>. Swapped round Sections D and E. Searched the doc for "dfn" tags and incorporated those terms into the glossary. Deleted the list in Section 4.1 and folded its single entry into the preceding sentence. Added a short note to Section 4.4 to the effect that if you're using IIS, you don't need to stop and restart the TeamTrack server. Added a note to Section 4.6 that we need to tell admins to make the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> user a Perforce super user and add it to the "p4 protect" table if they're using it.</td>
</tr>
<tr valign="top">
<td>2000-11-30</td>
<td><a href="mailto:rb@ravenbrook.com">RB</a></td>
<td>Added instructions to upgrade users Perforce clients and to stop using TeamShare SourceBridge. Told the administrator to check the Windows event log when things go wrong, because the TeamShare <abbr title="Application Programmer Interface">API</abbr> doesn't tell the replicator about errors.</td>
</tr>
<tr valign="top">
<td>2000-11-30</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td> Added comments to the example jobspec in section D.2, and fixed
the formatting. Added note saying that you may not have a field
called "code". Listed the TeamTrack workflows that won't work well.
Wrote advice on how to configure the integration. Added the <code
class="source">changelist_url</code> configuration parameter.</td>
</tr>
<tr valign="top">
<td>2000-12-01</td>
<td><a href="mailto:rb@ravenbrook.com">RB</a></td>
<td> Moved TeamTrack and Bugzilla configuration sections into the Configuration chapter, after the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> configuration instructions. Added basic Linux installation instructions. Rewrote sections of the configuration instructions to go with the new flow. Deleted section on switching TeamTrack databases. Updated registry editing and Team Track privilege instructions. Added instructions for creating a Perforce user for the replicator. Explained multiple transition limitation. Updated screenshots. </td>
</tr>
<tr valign="top">
<td>2000-12-04</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Made list of configuration parameters in <a href="#section-5.2">section 5.2</a> consistent with the configuration file (by alphabetizing both lists). Added missing configuration parameter <code class="source">closed_state</code>. Added note in section 5.2 about checking the configuration.</td>
</tr>
<tr valign="top">
<td>2000-12-05</td>
<td><a href="mailto:rb@ravenbrook.com">RB</a></td>
<td> Changed figures to use "div" tags in line with the user manual and to allow more flexible use of material in figures. Added basic notes on Bugzilla configuration (more to come). </td>
</tr>
<tr valign="top">
<td>2000-12-06</td>
<td><a href="mailto:rb@ravenbrook.com">RB</a></td>
<td>Added section 2.3 about supported platform configurations.</td>
</tr>
<tr valign="top">
<td>2000-12-07</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Advised admin to make e-mail addresses or userids the same in TeamTrack and Perforce. Advised admin to restart when users are added or changed.</td>
</tr>
<tr valign="top">
<td>2000-12-07</td>
<td><a href="mailto:rb@ravenbrook.com">RB</a></td>
<td> Removed "TeamTrack only" notice from "replicated_fields" configuration parameter heading. </td>
</tr>
<tr valign="top">
<td>2000-12-08</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td> Documented translation of "ignore" state. Improved advice about what to do with a field called "code". Fixed table of contents. </td>
</tr>
<tr valign="top">
<td>2000-12-08</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td> Documented <code class="command">refresh_perforce.py</code>. </td>
</tr>
<tr valign="top">
<td>2000-12-08</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td> Documented translation of "ignore" state. Improved advice about what to do with a field called "code". Fixed table of contents. </td>
</tr>
<tr valign="top">
<td>2000-12-08</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td> Documented <code class="command">refresh_perforce.py</code>. </td>
</tr>
<tr valign="top">
<td>2000-12-08</td>
<td><a href="mailto:rb@ravenbrook.com">RB</a></td>
<td> Brought configuration section 5.2 up to date with Bugzilla configurator (see <a href="http://www.ravenbrook.com/project/p4dti/issue/job000115/">job000115</a>). </td>
</tr>
<tr valign="top">
<td>2000-12-08</td>
<td><a href="mailto:rb@ravenbrook.com">RB</a></td>
<td> Updated to match unified configuration file and related re-organization of sources. </td>
</tr>
<tr valign="top">
<td>2000-12-11</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Noted that the <a href="#config-changelist_url"><code class="source">changelist_url</code></a> configuration parameter must be suitable for passing to <code class="source">sprintf()</code>.</td>
</tr>
<tr valign="top">
<td> 2000-12-13 </td>
<td> <a href="mailto:rb@ravenbrook.com">RB</a> </td>
<td> Updated for version 0.5 to cover Bugzilla supported platforms, configurations, and known issues. Added changelist_url for use with P4Web. </td>
</tr>
<tr valign="top">
<td> 2000-12-13 </td>
<td> <a href="mailto:rb@ravenbrook.com">RB</a> </td>
<td> Moving the Python 1.5.2 sources and Linux <abbr title="Red Hat Package Manager">RPM</abbr> to the project imports. </td>
</tr>
<tr valign="top">
<td> 2000-12-15 </td>
<td> <a href="mailto:nb@ravenbrook.com">NB</a> </td>
<td> Added verbose configuration item. </td>
</tr>
<tr valign="top">
<td> 2000-12-15 </td>
<td> <a href="mailto:nb@ravenbrook.com">NB</a> </td>
<td> Added more chat about bugzilla_user. </td>
</tr>
<tr valign="top">
<td> 2000-12-15 </td>
<td> <a href="mailto:nb@ravenbrook.com">NB</a> </td>
<td> More about e-mail addresses, python script names, and deleting jobs. </td>
</tr>
<tr valign="top">
<td> 2000-12-22 </td>
<td> <a href="mailto:lmb@ravenbrook.com">LMB</a> </td>
<td> Started improving the manual as agreed in e-mail from RB (Documentation preparation meeting with LMB, 2000-12-20). </td>
</tr>
<tr valign="top">
<td> 2001-01-01 </td>
<td> <a href="mailto:lmb@ravenbrook.com">LMB</a> </td>
<td> Continued improving the manual as agreed in e-mail from RB, modulo deleting things (Documentation preparation meeting with LMB, 2000-12-20). Removed spaces around em-dashes as per "Read Me First!" </td>
</tr>
<tr valign="top">
<td>2001-01-02</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>The recommendation for administrator experience (<a href="#section-3">section 3</a>) is more realistic. Moved text from Appendix D to the Integrator's Guide, and replaced with a reference. Replaced "company.com" with "company.domain" since the former exists. Fixed typos and improved wording to fix defects recorded in [<a href="http://www.ravenbrook.com/project/p4dti/doc/2000-12-08/release-0.4.2-test-report/">GDR 2000-12-08b</a>], [<a href="http://www.ravenbrook.com/project/p4dti/doc/2000-12-08/release-0.4.2-test-report-2/">GDR 2000-12-08c</a>], and [<a href="http://www.ravenbrook.com/project/p4dti/doc/2000-12-31/release-0.4.2-test-report/">GDR 2000-12-09</a>]. Made cross-references consistent. Added two error messages to section 13.2. Added figures 5 and 6 showing example log output. Added <a href="#section-5.4.3">section 5.4.3</a> about providing field descriptions.</td>
</tr>
<tr valign="top">
<td> 2001-01-02 </td>
<td> <a href="mailto:lmb@ravenbrook.com">LMB</a> </td>
<td> Merged GDR's changes to master manuals with this branch. Got about two-thirds of the way through a heavy copyedit. </td>
</tr>
<tr valign="top">
<td> 2001-01-03 </td>
<td> <a href="mailto:lmb@ravenbrook.com">LMB</a> </td>
<td> Made some changes suggested by GDR. Finished copyedit; noticed a number of things I didn't catch in the copyedit, so I'm sure there are other problems. Verified links. Indicated which comments I thought had been dealt with, in case GDR has time to work on this document tomorrow. Did a once-over in IE5 to make sure I didn't break anything too badly in the last two days. </td>
</tr>
<tr valign="top">
<td> 2001-01-05 </td>
<td> <a href="mailto:lmb@ravenbrook.com">LMB</a> </td>
<td> Dealt with about half of the changes that TC@perforce suggested. </td>
</tr>
<tr valign="top">
<td> 2001-01-06 </td>
<td> <a href="mailto:lmb@ravenbrook.com">LMB</a> </td>
<td> Procedurized and listed everything, as per TC@perforce's suggestions. </td>
</tr>
<tr valign="top">
<td> 2001-01-07 </td>
<td> <a href="mailto:lmb@ravenbrook.com">LMB</a> </td>
<td> Edited references. Replaced Section 5.3.3. </td>
</tr>
<tr valign="top">
<td> 2001-01-07 </td>
<td> <a href="mailto:lmb@ravenbrook.com">LMB</a> </td>
<td> Removed extraneous title material and Sections A and B. Removed comments and sent them in an e-mail to p4dti-staff. Did final copyedit and finished prepping manual to send to TC@perforce. </td>
</tr>
<tr valign="top">
<td> 2001-01-20 </td>
<td> <a href="mailto:lmb@ravenbrook.com">LMB</a> </td>
<td> Incorporated TC's handwritten edits. Cut lots of stuff out of the glossary. </td>
</tr>
<tr valign="top">
<td> 2001-01-21 </td>
<td> <a href="mailto:lmb@ravenbrook.com">LMB</a> </td>
<td> Re-added author, date, and other title material, and Sections A and B. Added comments on what I'd been doing to the manual in the interim (not much). Edited some new material from GDR. As per GDR's e-mail of 2001-01-18, point 5, deleted Section C and moved the material in Section D to Section 5.3.3. Fixed XREFS to Section 5; checked XREFS to Sections 12, 13, C, and D. Added material on when you might want to refresh jobs. Edited Section 10 slightly. Checked that procedure lead-ins and lists meet TC's specifications. Copied in Nick's changes to the info on patching Bugzilla and to the closed_state and replicated_fields parameters. Deleted mentions of bugzilla_user. Corrected internal XREFS. Copied over information on log files from master sources. Ran the spelling checker. </td>
</tr>
<tr valign="top">
<td>2001-01-22</td>
<td><a href="mailto:lmb@ravenbrook.com">LMB</a></td>
<td> As per TC@perforce's request and GDR's instructions, added menu command for how to start the TeamTrack Administrator from Windows. Added upgrade instructions to Section 4. </td>
</tr>
<tr valign="top">
<td>2001-01-29</td>
<td><a href="mailto:nb@ravenbrook.com">NB</a></td>
<td>Added <a href="#config-bugzilla_directory"><code class="source">bugzilla_directory</code></a> configuration parameter.</td>
</tr>
<tr valign="top">
<td> 2001-02-01 </td>
<td> <a href="mailto:rb@ravenbrook.com">RB</a> </td>
<td> Updated references to Perforce manuals to version 2000.2. Added steps to section 10, "Uninstalling the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>", to undo all installation steps. Added missing information to section 9, "Maintaining the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>", and clarified some of the existing instructions. </td>
</tr>
<tr valign="top">
<td> 2001-02-02 </td>
<td> <a href="mailto:rb@ravenbrook.com">RB</a> </td>
<td> Implemented paper review comments of 2001-01-25 by TC@perforce. </td>
</tr>
<tr valign="top">
<td>2001-02-12</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Added <a href="#config-start_date"><code class="source">start_date</code></a> configuration parameter. Renamed <code class="filename">refresh_perforce.py</code> to <code class="filename">refresh.py</code>.</td>
</tr>
<tr valign="top">
<td>2001-02-13</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Added note about security of jobs. Added socket.error error message to section 11.2. Alphabetized messages in section 11.2. Added note about "localhost" not working as a value for the teamtrack_server configuration parameter. Indicated that administrator_address and smtp_server can be None.</td>
</tr>
<tr valign="top">
<td> 2001-02-14 </td>
<td> <a href="mailto:rb@ravenbrook.com">RB</a> </td>
<td> Added Linux <abbr title="Red Hat Package Manager">RPM</abbr> instructions. </td>
</tr>
<tr valign="top">
<td> 2001-02-15 </td>
<td> <a href="mailto:rb@ravenbrook.com">RB</a> </td>
<td> Fixed "zcat" to "gunzip -c" to fool-proof unpacking. </td>
</tr>
<tr valign="top">
<td> 2001-02-16 </td>
<td> <a href="mailto:rb@ravenbrook.com">RB</a> </td>
<td> Added brief instructions for starting the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> automatically. </td>
</tr>
<tr valign="top">
<td> 2001-02-16 </td>
<td> <a href="mailto:nb@ravenbrook.com">NB</a> </td>
<td> Added section 6.1, on migrating sets of issues. Also add some poll_period and start_date references. </td>
</tr>
<tr valign="top">
<td>2001-02-21</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Documented <code class="filename">p4dti.reg</code> in section 5.3.1.</td>
</tr>
<tr valign="top">
<td>2001-02-22</td>
<td><a href="mailto:nb@ravenbrook.com">NB</a></td>
<td>Documented MySQLdb and MySQL versions in section 3.4.1.</td>
</tr>
<tr valign="top">
<td>2001-02-22</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Gave instructions in section 11.1 on identifying the release that you're using. Added "Can't create a new user - over licence quota" to error messages in section 11.2. Wrote section 6.2 on migrating from Perforce jobs.</td>
</tr>
<tr valign="top">
<td>2001-02-26</td>
<td><a href="mailto:nb@ravenbrook.com">NB</a></td>
<td>Added Bugzilla-related errors to section 11.2.</td>
</tr>
<tr valign="top">
<td>2001-02-27</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Alphabetized the list of error messages in section 11.2. Gave full error messages, including prefixes, for each error. Improved error descriptions.</td>
</tr>
<tr valign="top">
<td> 2001-03-02 </td>
<td> <a href="mailto:rb@ravenbrook.com">RB</a> </td>
<td> Added missing contents entries. Fixed some HTML errors and tidied up some other HTML. Transferred copyright to Perforce under their license. Added section on advanced configuration. </td>
</tr>
<tr valign="top">
<td>2001-03-02</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Removed section 9.3 on tracking down TeamTrack errors section, since it's redundant with section 11.2.</td>
</tr>
<tr valign="top">
<td> 2001-03-05 </td>
<td> <a href="mailto:rb@ravenbrook.com">RB</a> </td>
<td> Added e-mail messages to the list of things we'd like in bug reports. Added some missing "abbr" tags. </td>
</tr>
<tr valign="top">
<td>2001-03-13</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Added message ids to the messages in section 11.2; moved messages without ids in section 11.3. Added some missing error messages. Removed <code class="source">verbose</code> parameter; added <code class="source">log_level</code> parameter. Alphabetized section 5.1.</td>
</tr>
<tr valign="top">
<td>2001-03-16</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Changed "daemon licence" to "background user licence" for consistency with Perforce's own terminology. Background user licences are available from Perforce Customer Service, not Technical Support.</td>
</tr>
<tr valign="top">
<td>2001-03-16</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Added text for messages 105-117, 200-209, 314, 315.</td>
</tr>
<tr valign="top">
<td> 2001-04-11 </td>
<td> <a href="mailto:rb@ravenbrook.com">RB</a> </td>
<td> Updated version to 1.1. </td>
</tr>
<tr valign="top">
<td> 2001-04-20 </td>
<td> <a href="mailto:rb@ravenbrook.com">RB</a> </td>
<td> Fixed reference to Bugzilla download at info.ravenbrook.com to point to www.ravenbrook.com. </td>
</tr>
<tr valign="top">
<td>2001-05-17</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Removed occurrences of messages 844-847, 607-612 from example replicator output (not produced any more).</td>
</tr>
<tr valign="top">
<td>2001-05-23</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Provided link to online support information.</td>
</tr>
<tr valign="top">
<td>2001-05-24</td>
<td><a href="mailto:nb@ravenbrook.com">NB</a></td>
<td>Updated for Bugzilla 2.12.</td>
</tr>
<tr valign="top">
<td>2001-07-03</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Added <a href="#config-teamtrack_version"><code class="source">teamtrack_version</code></a> configuration parameter. Added error messages from the TeamTrack 5.0 API and error message from the TeamTrack 4.5 API when connecting to a TeamTrack 5.0 server. </td>
</tr>
<tr valign="top">
<td>2001-07-09</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Updated TeamTrack screen shots to version 5.0.</td>
</tr>
<tr valign="top">
<td>2001-07-09</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td><abbr title="Red Hat Package Manager">RPM</abbr> users should use the stop script to stop the replicator.</td>
</tr>
<tr valign="top">
<td>2001-07-09</td>
<td><a href="mailto:nb@ravenbrook.com">NB</a></td>
<td>Added job_url config parameter.</td>
</tr>
<tr valign="top">
<td>2001-07-14</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Updated references to Perforce manuals to 2001.1, since we now support that version.</td>
</tr>
<tr valign="top">
<td>2001-07-15</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Explained how to set up an integration without being connected to a network.</td>
</tr>
<tr valign="top">
<td>2001-07-17</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Added more error messages to troubleshooting section.</td>
</tr>
<tr valign="top">
<td>2001-07-24</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>The <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> doesn't support TeamTrack on a secure web server. Added more troubleshooting advice for TeamTrack errors.</td>
</tr>
<tr valign="top">
<td>2001-07-25</td>
<td><a href="mailto:nb@ravenbrook.com">NB</a></td>
<td>Changed restarting instructions: Bugzilla users don't need to restart the replicator when adding a new user.</td>
</tr>
<tr valign="top">
<td>2001-07-25</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>The replicator user needs submit, update and transition privileges in TeamTrack 5.0.</td>
</tr>
<tr valign="top">
<td>2001-07-28</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Reordered section 5.1 so that configuration parameters appear in the same order as in config.py.</td>
</tr>
<tr valign="top">
<td>2001-07-31</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Added error from incompatibility between Perforce client and server.</td>
</tr>
<tr valign="top">
<td>2001-08-07</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>No need to restart the TeamTrack integration when you add a user.</td>
</tr>
<tr valign="top">
<td>2001-09-03</td>
<td><a href="mailto:nb@ravenbrook.com">NB</a></td>
<td>Added Bugzilla 2.14.</td>
</tr>
<tr valign="top">
<td>2001-09-12</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Added <a href="#config-use_windows_event_log"><code class="source">use_windows_event_log</code></a> configuration parameter and prerequisite.</td>
</tr>
<tr valign="top">
<td>2001-09-13</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Added TeamTrack error message "SOCKET_READ_ERROR: Authentication Failed. No user information." to troubleshooting section.</td>
</tr>
<tr valign="top">
<td>2001-09-26</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Added section on limitations of the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>.</td>
</tr>
<tr valign="top">
<td>2001-10-04</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Improved description of workflows that don't work well with the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr>. Added table of supported field types.</td>
</tr>
<tr valign="top">
<td>2001-10-07</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Added <a href="#config-use_perforce_jobnames"><code class="source">use_perforce_jobnames</code></a> parameter.</td>
</tr>
<tr valign="top">
<td>2001-10-18</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Added troubleshooting advice for messages 123, 127, 615, 618, and 619.</td>
</tr>
<tr valign="top">
<td>2001-09-23</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Added new command <code class="filename">poll.py</code> and table of commands.</td>
</tr>
<tr valign="top">
<td>2001-10-25</td>
<td><a href="mailto:nb@ravenbrook.com">NB</a></td>
<td>Improved information on supported MySQLdb releases. Added troubleshooting advice for messages 1005 and 1006.</td>
</tr>
<tr valign="top">
<td>2001-11-05</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Added section on replicating new jobs from Perforce to the defect tracker.</td>
</tr>
<tr valign="top">
<td>2001-11-08</td>
<td><a href="mailto:ndl@ravenbrook.com">NDL</a></td>
<td>Added section 5.6.2, on running as an NT service; cleaned up sections 5.5 and 5.6.</td>
</tr>
<tr valign="top">
<td>2001-11-14</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Moved material requiring Python programming or knowledge of defect tracker schema to the Advanced Administrator's Guide.</td>
</tr>
<tr valign="top">
<td>2001-11-19</td>
<td><a href="mailto:ndl@ravenbrook.com">NDL</a></td>
<td>Message 891 becomes more general. Document message 1017.</td>
</tr>
<tr valign="top">
<td>2001-11-22</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Documented <a href="#config-use_deleted_selections"><code class="source">use_deleted_selections</code></a> configuration parameter and associated error messages.</td>
</tr>
<tr valign="top">
<td> 2001-11-22 </td>
<td> <a href="mailto:rb@ravenbrook.com">RB</a> </td>
<td> Cross-referenced sections on deleting Perforce jobs to the migration section of the AAG. </td>
</tr>
<tr valign="top">
<td>2001-11-27</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Documented a processmail-related error message that can come up when migrating if you haven't applied the Bugzilla patch.</td>
</tr>
<tr valign="top">
<td>2001-12-03</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Added remaining error messages to section 11.</td>
</tr>
<tr valign="top">
<td>2002-01-24</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Noted support for Bugzilla's "emailsuffix" feature.</td>
</tr>
<tr valign="top">
<td>2002-01-31</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Documented the supported MySQLdb versions. Changed MySQLdb link from release 0.3.0 to release 0.9.1.</td>
</tr>
<tr valign="top">
<td>2002-01-31</td>
<td><a href="mailto:nb@ravenbrook.com">NB</a></td>
<td>Added Bugzilla 2.14.1.</td>
</tr>
<tr valign="top">
<td>2002-02-01</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Noted support for TeamTrack 5.5.</td>
</tr>
<tr valign="top">
<td>2002-03-14</td>
<td><a href="mailto:nb@ravenbrook.com">NB</a></td>
<td>Removed support for TeamTrack 5.02.</td>
</tr>
<tr valign="top">
<td>2002-04-08</td>
<td><a href="mailto:nb@ravenbrook.com">NB</a></td>
<td>Add _accessible fields to the Bugzilla fields table.</td>
</tr>
<tr valign="top">
<td>2002-04-09</td>
<td><a href="mailto:nb@ravenbrook.com">NB</a></td>
<td>Remove extraneous paragraph close tag.</td>
</tr>
<tr valign="top">
<td>2002-05-06</td>
<td><a href="mailto:ram@parrus.com">Ram</a></td>
<td>Added windows notes for Bugzilla software prerequisites.</td>
</tr>
<tr valign="top">
<td> 2002-06-26 </td>
<td> <a href="mailto:rb@ravenbrook.com">RB</a> </td>
<td> Merged Parrus Technologies' Bugzilla for Windows port into Ravenbrook sources. </td>
</tr>
<tr valign="top">
<td>2002-10-04</td>
<td><a href="mailto:nb@ravenbrook.com">NB</a></td>
<td>Add recent Bugzilla releases, and deprecate old defect tracker
releases.</td>
</tr>
<tr valign="top">
<td> 2002-10-25 </td>
<td> <a href="mailto:rb@ravenbrook.com">RB</a> </td>
<td> Brought cross references to manuals and Bugzilla documentation up to date. </td>
</tr>
<tr valign="top">
<td>2002-12-11</td>
<td><a href="mailto:nb@ravenbrook.com">NB</a></td>
<td>One file changed by the Bugzilla patch is called
doeditparams.cgi, not doeditparams.pl. Also added note on using
"patch" on Windows, link to suitable patch utility. Also added
"-p1" switch to the patch command line. Also added link to mx
RPM.</td>
</tr>
<tr valign="top">
<td>2002-12-13</td>
<td><a href="mailto:nb@ravenbrook.com">NB</a></td>
<td>Refer to patch utility for Windows in section 5.4.1.</td>
</tr>
</table>
<h2><a id="section-C" name="section-C">C. Glossary</a></h2>
<table>
<tr valign="top">
<td><a id="term-changelist" name="term-changelist" href="#term-changelist">changelist</a></td>
<td> An atomic change transaction in Perforce. </td>
</tr>
<tr valign="top">
<td>
<a id="term-background-user-license" name="term-background-user-license" href="#term-background-user-license">background user license</a><br />
<a id="term-daemon-license" name="term-daemon-license" href="#term-daemon-license">daemon license</a>
</td>
<td> A license for a process rather than a person. </td>
</tr>
<tr valign="top">
<td><a id="term-fix" name="term-fix" href="#term-fix">fix</a></td>
<td> A link between a job and a changelist. </td>
</tr>
<tr valign="top">
<td><a id="term-issue" name="term-issue" href="#term-issue">issue</a></td>
<td> A unit of work tracked by the defect tracker, for example, a bug, a change request, or an enhancement request. </td>
</tr>
<tr valign="top">
<td><a id="term-job" name="term-job" href="#term-job">job</a></td>
<td> A unit of work tracked by Perforce. </td>
</tr>
<tr valign="top">
<td><a id="term-replicator" name="term-replicator" href="#term-replicator">replicator</a></td>
<td> A process that copies (replicates) data between a defect tracker and a Perforce server in order to keep each one up to date with changes made in the other. Replication allows developers to do their routine defect resolution work entirely from their Perforce client, without needing to use the defect tracker's interface. It also allows developers to relate their changes to defect tracking issues. </td>
</tr>
<tr valign="top">
<td><a id="term-workflow" name="term-workflow" href="#term-workflow">workflow</a></td>
<td> A set of rules that control who can do what to which issues. </td>
</tr>
</table>
<h2><a id="section-D" name="section-D">D. Table of commands</a></h2>
<table border="1" cellspacing="0" cellpadding="5">
<tr valign="top">
<th>Command</th>
<th>Description</th>
<th>Reference</th>
</tr>
<tr valign="top">
<td><code class="command">python check.py</code></td>
<td>Check that the defect tracker database is consistent with the
Perforce jobs and fixes, and report any inconsistencies.</td>
<td><a href="#section-7.3">7.3</a></td>
</tr>
<tr valign="top">
<td><code class="command">python check_jobs.py</code></td>
<td>Check that Perforce jobs are consistent with the Perforce
jobspec.</td>
<td>[<a title="Perforce Defect Tracking Integration Advanced Administrator's Guide" href="../aag/index.html#section-4.5">GDR 2001-11-14, 4.5</a>]</td>
</tr>
<tr valign="top">
<td><code class="command">python migrate.py</code></td>
<td>Migrate Perforce jobs to defect tracker issues.</td>
<td>[<a title="Perforce Defect Tracking Integration Advanced Administrator's Guide" href="../aag/index.html#section-4.10">GDR 2001-11-14, 4.10</a>]</td>
</tr>
<tr valign="top">
<td><code class="command">python migrate_users.py</code></td>
<td>Create defect tracker users corresponding to Perforce users.</td>
<td>[<a title="Perforce Defect Tracking Integration Advanced Administrator's Guide" href="../aag/index.html#section-4.4">GDR 2001-11-14, 4.4</a>]</td>
</tr>
<tr valign="top">
<td><code class="command">python poll.py</code></td>
<td>Poll the defect tracker and Perforce for changes, replicate those
changes, then stop.</td>
<td><a href="#section-7.1">7.1</a></td>
</tr>
<tr valign="top">
<td><code class="command">python refresh.py</code></td>
<td>Delete all jobs and fixes in Perforce, then copy all the
replicated issues from the defect tracker again. For use when you
change the <code class="source">replicated_fields</code> (for <a
href="#config-replicated_fields-Bugzilla">Bugzilla</a> or <a
href="#config-replicated_fields-TeamTrack">TeamTrack</a>) or <a
href="#config-start_date"><code class="source">start_date</code></a>
configuration parameters.</td>
<td><a href="#section-9.2">9.2</a></td>
</tr>
<tr valign="top">
<td><code class="command">python run.py</code></td>
<td>Run the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> replicator.</td>
<td><a href="#section-5.5">5.5</a></td>
</tr>
<tr valign="top">
<td><code class="command">python service.py <i>[argument]</i></code></td>
<td>Manage the <abbr title="Perforce Defect Tracking Integration">P4DTI</abbr> replicator as a Windows NT Service. With no argument, installs the service. Otherwise specify one of: <code class="command">start</code>, <code class="command">stop</code> or <code class="command">remove</code>.</td>
<td><a href="#section-5.6.2">5.6.2</a></td>
</tr>
<tr valign="top">
<td><code class="command">python teamtrack_query.py</code></td>
<td>Query the TeamTrack database.</td>
<td>[<a title="Perforce Defect Tracking Integration Advanced Administrator's Guide" href="../aag/index.html#section-6">GDR 2001-11-14, 6</a>]</td>
</tr>
</table>
<hr />
<p> <small>This document is copyright © 2001 Perforce Software, Inc. All rights reserved.</small> </p>
<p> <small>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.</small> </p>
<p> <small> <strong> 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. </strong> </small> </p>
</body>
</html>