Ravenbrook / Projects / Perforce Defect Tracking Integration / Version 1.3 Product Sources / Design

Perforce Defect Tracking Integration Project


Design of e-mail messages from the replicator

Gareth Rees, Ravenbrook Limited, 2001-10-26

1. Introduction

This document describes the circumstances in which the P4DTI sends e-mail, and the contents of the e-mail messages.

The purposes of this document are: (1) to make sure that we test all circumstances; (2) to enable developers to add new e-mail messages; (3) to understand the sometimes tortuous algorithm for constructing messages so that existing messages can be maintained.

The intended readership is project developers and testers.

This document is not confidential.

2. E-mail circumstances

Messages specific to a single job are sent to the administrator, the job owner, and the last person to change the job. Messages concerning operation of the P4DTI in general are sent to the administrator only.

Table 1. Kinds of e-mail messages

Id Subject Method Job-specific? Description
860 Job '%s' overwritten by issue '%s'. overwrite_issue_dt_to_p4, called from replicate Yes If a conflict occurs (job edited simultaneously with issue), and the job was overwritten by the issue. Documented in detail in [RB 2000-08-10b, 2.2].
857 Issue '%s' overwritten by job '%s'. overwrite_issue_p4_to_dt, called from replicate Yes If a conflict occurs and the issue was overwritten by the job. This can't happen in the P4DTI at present (because of the "defect tracker wins" policy).
860 Job '%s' overwritten by issue '%s'. overwrite_issue_dt_to_p4, called from revert_issue_dt_to_p4 Yes If the replication of the job to the issue fails, and the job was overwritten by issue.
908 Job '%s' could not be replicated to the defect tracker. replicate_new_issue_p4_to_dt Yes If the replication of a new job to the defect tracker failed.
866 The P4DTI replicator has started. mail_startup_message No When the run.py script is started, a message to say that the replicator has started. This also reports problems (or potential problems) with the user mapping. Documented in detail in [RB 2000-08-10a, 3.5]
848 Job '%s' could not be replicated to issue '%s'. revert_issue_dt_to_p4 No If the replication of the job to the issue fails, and the overwrite of the job by the issue also fails.
863 The replicator failed to poll successfully. run No Any failure during normal execution, other than those listed above.

3. How e-mails are composed

Table 2 is a kind of variorum edition of the majority of the e-mails sent by the P4DTI.

Table 2. Composition of e-mail messages

Id Description Text Method
865 Opening This is an automatically generated e-mail from the Perforce Defect Tracking Integration replicator '%s'. mail
841 Introductory statement (intro argument to mail_report). "Defect tracker issue '%s' and Perforce job '%s' have both changed since the last time the replicator polled the databases. The replicator's conflict resolution policy decided to overwrite the job with the issue." The reason argument to overwrite_issue_dt_to_p4
614 If in the context of an exception, the exception itself. "No transition from state '%s' to state '%s'." mail_report
862 Optional additional information (extra argument to mail_report) "The job looked like this before being overwritten:" overwrite_issue_dt_to_p4
- The job itself
852 If in the context of an exception, introduce the traceback "Here's a full Python traceback:" mail_report
- If in the context of an exception, the stack trace. - mail_report
853 If mail is being sent to users other than the administrator (that is, if there's a problem with a job), then advice about who to contact "If you are having continued problems, please contact your P4DTI administrator <%s>." mail_report

A. References

[RB 2000-08-10a] "Perforce Defect Tracking Integration Administrator's Guide"; Richard Brooksby; Ravenbrook Limited; 2000-08-10.
[RB 2000-08-10b] "Perforce Defect Tracking Integration User's Guide"; Richard Brooksby; Ravenbrook Limited; 2000-08-10.

B. Document History

2001-10-26 GDR Initial draft.
2001-10-29 NB Tidied up, added message 908.

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.

$Id: //info.ravenbrook.com/project/p4dti/version/1.3/design/mail/index.html#3 $

Ravenbrook / Projects / Perforce Defect Tracking Integration / Version 1.3 Product Sources / Design