<?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" lang="en">
<head>
<title>TeamTrack journal fields</title>
</head>
<body bgcolor="#FFFFFF" text="#000000" link="#000099" vlink="#660066" alink="#FF0000">
<div align="center">
<p>
<a href="http://www.ravenbrook.com/">Ravenbrook</a> /
<a href="http://www.ravenbrook.com/project/">Projects</a> /
<a href="http://www.ravenbrook.com/project/p4dti/">Perforce Defect Tracking Integration</a> /
<a href="../../index.html">Version 2.0 Product Sources</a> /
<a href="../index.html">Design</a>
</p>
<p><i><a href="http://www.ravenbrook.com/project/p4dti/">Perforce Defect Tracking Integration Project</a></i></p>
<hr />
<h1>TeamTrack journal fields</h1>
<address>
<a href="mailto:gdr@ravenbrook.com">Gareth Rees</a>,
<a href="http://www.ravenbrook.com/">Ravenbrook Limited</a>,
2001-09-26
</address>
</div>
<h2><a id="section-1" name="section-1">1. Introduction</a></h2>
<p> This document describes TeamTrack journal fields and the design for
replicating them to and from Perforce, to fix <a
href="http://www.ravenbrook.com/project/p4dti/issue/job000371/">job000371</a>. </p>
<p><b>This document is obsolete.</b> The P4DTI no longer supports
integration with TeamTrack. This document is retained for reference
purposes, but will not be maintained.</p>
<p> The intended readership is project developers. </p>
<p> This document is not confidential. </p>
<h2><a id="section-2" name="section-2">2. Journal fields</a></h2>
<p> Journal fields were introduced in TeamTrack 5.0. A journal field is a
multi-line text field to which a TeamTrack user can append an entry when
they update or transition an issue. Each entry gets a header giving the
date and the id of the user. For example, a journal field may be
displayed as follows after three entries have been added to it: </p>
<blockquote><pre>
9/25/2001 16:45PM - Gareth Rees:
First entry.
9/26/2001 9:02AM - Gareth Rees:
Second entry.
9/26/2001 10:14AM - Nick Barnes:
Third entry.
</pre></blockquote>
<p> There are two types of journal fields. "Append only" journal fields
only offer the option of adding a new entry. Old entries remain
unchanged. "Not append only" journal fields allow TeamTrack users to
edit the old entries (including the header lines). This is done by
offering two input fields in the issue form: the first contains the old
entries and is used to edit them. The second is blank and is used to
add a new entry. </p>
The default TeamTrack 5.0 issue table contains an append-only journal
field ("Additional Notes"). Any multi-line text field can be turned
into a journal field (in the TeamTrack Administrator, click on the
Workflows tab; select a workflow; click "Edit"; click on the "Default
fields" tab; select a text field; click "Edit"; click on the "Options"
tab; click on the "Journal" radio button and turn the "Append only"
checkbox on or off as desired).
<h2><a id="section-3" name="section-3">3. Representation</a></h2>
<p> A journal field is represented as a multi-line text field
(<code>TS_FLDTYPE=101</code>) with <code>TS_ATTRIBUTES</code> either 2
(old entries editable) or 3 (append only). This is not documentated in
the TeamTrack database schema for TeamTrack 5.0 [<a title="TeamTrack
Database Schema (Database Version: 514)"
href="http://www.ravenbrook.com/project/p4dti/import/2001-06-19/teamtrack-5034/api/schema.htm">TeamShare
2001-04-30</a>]: I've reverse-engineered it from the database. </p>
<p> The contents of the field in the database is the entries and header
lines, as presented to the user. There is no special representation of
the entries. (This is how come you can edit other people's comments in
"not append only" journal fields.) </p>
<h2><a id="section-4" name="section-4">4. Replication design</a></h2>
<p>Replicate a journal field from TeamTrack to Perforce as its contents
plus the separator line</p>
<blockquote><code>------- Append additional comments below -------</code></blockquote>
<p> (as in the replication of longdesc fields in the Bugzilla
integration). </p>
<p> To replicate from Perforce to TeamTrack: </p>
<ol>
<li><p> Check that the separator line is present. If not, don't
replicate. </p></li>
<li><p> For an "append only" journal field, check that the material
above the separator line matches the value in TeamTrack; if not, don't
replicate. </p></li>
<li><p> If there is material below the separator line, replace the
separator line with the appropriate header line (see <a
href="#section-2">section 2</a>). If there is no material below the
separator line, remove it. </p></li>
</ol>
<h2><a id="section-A" name="section-A">A. References</a></h2>
<table>
<tr valign="top">
<td>[<a id="ref-TeamShare-2001-04-30" name="ref-TeamShare-2001-04-30" href="http://www.ravenbrook.com/project/p4dti/import/2001-06-19/teamtrack-5034/api/schema.htm">TeamShare 2001-04-30</a>]</td>
<td>
"TeamTrack Database Schema (Database Version: 514)";
<a href="http://www.teamshare.com/">TeamShare</a>;
2001-04-30.
</td>
</tr>
</table>
<h2><a id="section-B" name="section-B">B. Document History</a></h2>
<table>
<tr valign="top">
<td>2001-09-26</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Created.</td>
</tr>
<tr valign="top">
<td>2003-06-02</td>
<td><a href="mailto:nb@ravenbrook.com">NB</a></td>
<td>Marked as obsolete.</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>
<div align="center">
<p><code>$Id: //info.ravenbrook.com/project/p4dti/version/2.0/design/teamtrack-journal/index.html#3 $</code></p>
<p>
<a href="http://www.ravenbrook.com/">Ravenbrook</a> /
<a href="http://www.ravenbrook.com/project/">Projects</a> /
<a href="http://www.ravenbrook.com/project/p4dti/">Perforce Defect Tracking Integration</a> /
<a href="../../index.html">Version 2.0 Product Sources</a> /
<a href="../index.html">Design</a>
</p>
</div>
</body>
</html>