			TEAMTRACK JOURNAL FIELDS

	      Gareth Rees, Ravenbrook Limited, 2001-09-26


1. INTRODUCTION

This document describes TeamTrack journal fields and the design for
replicating them to and from Perforce, to fix job000371.

The intended readership is project developers.

This document is not confidential.


2. JOURNAL FIELDS

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:

    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.

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.

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


3. REPRESENTATION

A journal field is represented as a multi-line text field (TS_FLDTYPE =
101) with TS_ATTRIBUTES either 2 (old entries editable) or 3 (append
only).  This is not documentated in the TeamTrack database schema for
TeamTrack 5.0 [TeamShare 2001-04-30]: I've reverse-engineered it from
the database.

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


4. REPLICATION DESIGN

Replicate a journal field from TeamTrack to Perforce as its contents
plus the separator line

    ------- Append additional comments below -------

(as in the replication of longdesc fields in the Bugzilla integration).

To replicate from Perforce to TeamTrack, for all journal fields:

   1. Check that the separator line is present.  If not, don't
      replicate.

For an "append only" journal field:

   2. Check that the material above the separator line matches the value
      in TeamTrack; if not, don't replicate.

For all journal fields:

   3. If there is material below the separator line, replace the
      separator line with the appropriate header line (see section 2).
      If there is no material below the separator line, remove it.


A. REFERENCES

[TeamShare 2001-04-30] "TeamTrack Database Schema (Database Version:
514)"; TeamShare; 2001-04-30;
<http://www.ravenbrook.com/project/p4dti/import/2001-06-19/teamtrack-5034/api/schema.htm>.


B. DOCUMENT HISTORY

2001-09-26 GDR Created


C. COPYRIGHT AND LICENCE

This document is copyright &copy; 2001 Perforce Software, Inc.  All
rights reserved.

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

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