<?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>E-mail design</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>Design of e-mail messages from the replicator</h1>
<address>
<a href="mailto:gdr@ravenbrook.com">Gareth Rees</a>,
<a href="http://www.ravenbrook.com/">Ravenbrook Limited</a>,
2001-10-26
</address>
</div>
<h2><a id="section-1" name="section-1">1. Introduction</a></h2>
<p> This document describes the circumstances in which the <abbr
title="Perforce Defect Tracking Integration">P4DTI</abbr> sends e-mail,
and the contents of the e-mail messages. </p>
<p> 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. </p>
<p> The intended readership is project developers and testers. </p>
<p> This document is not confidential. </p>
<h2><a id="section-2" name="section-2">2. E-mail circumstances</a></h2>
<p>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.</p>
<div align="center">
<p> <a id="table-1" name="table-1">Table 1.</a> Kinds of e-mail
messages </p>
<table border="1" cellspacing="0" cellpadding="5">
<tr valign="top">
<th>Id</th>
<th>Subject</th>
<th>Method</th>
<th>Job-specific?</th>
<th>Description</th>
</tr>
<tr valign="top">
<td>860</td>
<td>Job '%s' overwritten by issue '%s'.</td>
<td><code>overwrite_issue_dt_to_p4</code>,
called from <code>replicate</code></td>
<td>Yes</td>
<td>If a conflict occurs (job edited simultaneously with issue),
and the job was overwritten by the issue. Documented in detail in
[<a title="Perforce Defect Tracking Integration User's Guide"
href="../../manual/ug/index.html#section-2.2">RB 2000-08-10b,
2.2</a>].</td>
</tr>
<tr valign="top">
<td>857</td>
<td>Issue '%s' overwritten by job '%s'.</td>
<td><code>overwrite_issue_p4_to_dt</code>,
called from <code>replicate</code></td>
<td>Yes</td>
<td>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). </td>
</tr>
<tr valign="top">
<td>860</td>
<td>Job '%s' overwritten by issue '%s'.</td>
<td><code>overwrite_issue_dt_to_p4</code>,
called from <code>revert_issue_dt_to_p4</code></td>
<td>Yes</td>
<td>If the replication of the job to the issue fails, and the
job was overwritten by issue. </td>
</tr>
<tr valign="top">
<td>908</td>
<td>Job '%s' could not be replicated to the defect tracker.</td>
<td><code>replicate_new_issue_p4_to_dt</code></td>
<td>Yes</td>
<td>If the replication of a new job to the defect tracker failed.</td>
</tr>
<tr valign="top">
<td>866</td>
<td>The P4DTI replicator has started.</td>
<td><code>mail_startup_message</code></td>
<td>No</td>
<td>When the <code>run.py</code> 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
[<a title="Perforce Defect Tracking Integration Administrator's
Guide" href="../../manual/ag/index.html#section-3.5">RB
2000-08-10a, 3.5</a>] </td>
</tr>
<tr valign="top">
<td>848</td>
<td>Job '%s' could not be replicated to issue '%s'.</td>
<td><code>revert_issue_dt_to_p4</code></td>
<td>No</td>
<td>If the replication of the job to the issue fails, and the
overwrite of the job by the issue also fails. </td>
</tr>
<tr valign="top">
<td>863</td>
<td>The replicator failed to poll successfully.</td>
<td><code>run</code></td>
<td>No</td>
<td>Any failure during normal execution, other than those listed
above. </td>
</tr>
</table>
</div>
<h2><a id="section-3" name="section-3">3. How e-mails are composed</a></h2>
<p> <a href="#table-2">Table 2</a> is a kind of variorum edition of the
majority of the e-mails sent by the <abbr title="Perforce Defect
Tracking Integration">P4DTI</abbr>. </p>
<div align="center">
<p> <a id="table-2" name="table-2">Table 2.</a> Composition of e-mail
messages </p>
<table border="1" cellspacing="0" cellpadding="5">
<tr valign="top">
<th>Id</th>
<th>Description</th>
<th>Text</th>
<th>Method</th>
</tr>
<tr valign="top">
<td>865</td>
<td>Opening</td>
<td>This is an automatically generated e-mail from the Perforce Defect
Tracking Integration replicator '%s'.</td>
<td><code>mail</code></td>
</tr>
<tr valign="top">
<td><i>841</i></td>
<td>Introductory statement (<code>intro</code> argument to <code>mail_report</code>).</td>
<td><i>"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."</i></td>
<td><i>The <code>reason</code> argument to <code>overwrite_issue_dt_to_p4</code></i></td>
</tr>
<tr valign="top">
<td><i>614</i></td>
<td>If in the context of an exception, the exception itself.</td>
<td><i>"No transition from state '%s' to state '%s'."</i></td>
<td><code>mail_report</code></td>
</tr>
<tr valign="top">
<td><i>862</i></td>
<td rowspan="2">Optional additional information (<code>extra</code> argument to <code>mail_report</code>)</td>
<td><i>"The job looked like this before being overwritten:"</i></td>
<td rowspan="2"><i><code>overwrite_issue_dt_to_p4</code></i></td>
</tr>
<tr valign="top">
<td>-</td>
<td><i>The job itself</i></td>
</tr>
<tr valign="top">
<td>852</td>
<td>If in the context of an exception, introduce the traceback</td>
<td>"Here's a full Python traceback:"</td>
<td><code>mail_report</code></td>
</tr>
<tr valign="top">
<td>-</td>
<td>If in the context of an exception, the stack trace.</td>
<td>-</td>
<td><code>mail_report</code></td>
</tr>
<tr valign="top">
<td>853</td>
<td>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</td>
<td>"If you are having continued problems, please contact your
P4DTI administrator <%s>."</td>
<td><code>mail_report</code></td>
</tr>
</table>
</div>
<h2><a id="section-A" name="section-A">A. References</a></h2>
<table>
<tr valign="top">
<td>[<a id="ref-RB-2000-08-10a" name="ref-RB-2000-08-10a" href="../../manual/ag/index.html">RB 2000-08-10a</a>]</td>
<td>
"Perforce Defect Tracking Integration Administrator'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-RB-2000-08-10b" name="ref-RB-2000-08-10b" href="../../manual/ug/index.html">RB 2000-08-10b</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>
</table>
<h2><a id="section-B" name="section-B">B. Document History</a></h2>
<table>
<tr valign="top">
<td>2001-10-26</td>
<td><a href="mailto:gdr@ravenbrook.com">GDR</a></td>
<td>Initial draft.</td>
</tr>
<tr valign="top">
<td>2001-10-29</td>
<td><a href="mailto:nb@ravenbrook.com">NB</a></td>
<td>Tidied up, added message 908.</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/mail/index.html#2 $</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>