TeamTrack journal fields

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.

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:

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

2. For an "append only" journal field, check that the material above the separator line matches the value in TeamTrack; if not, don't replicate.

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

B. Document History

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

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

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