NAME
bugmail - ClearDDTS mail notification generator
SYNOPSIS
bugmail
DESCRIPTION
The bugmail program is invoked by the ddtsd daemon whenever
there is any mail notification work to be performed.
Based on defect record files found in its spool directory,
the bugmail program mails notification messages regarding
database changes to certain users.
When a defect is submitted or modified, the old version (if
any) is saved in the spool directory. The new version is
retrieved in the ~ddts/allbugs directory. If a defect record
is entirely new, the spooled record file just contains the
Identifier of the new record.
For each bug record found in its spool directory, bugmail
compares the old and new versions of the record, and sends
electronic mail to notify certain users about the changes.
In particular, a mail message is generated for each state
transition that the record appears to have gone through
between the new and old versions.
The notified users include the submitter of the defect
record (found in the Submitter-mail field), the engineer
responsible for resolving the defect (found in the
Engineer-mail field), the most recent responsible engineer,
if different from the current one (found in the Engineer-
mail field of the old copy of the record), other interested
users (found in the Other-mail field), and the users to be
notified for that project regarding the state transition(s)
that occurred (see the ~ddts/projects//proj.notify
file).
Normally, all mail messages to the user who caused the
transaction to occur are suppressed, because that user
presumably does not need to be notified. But that policy can
be changed by the administrator by adding the line:
Allow-updater-mail: Y
to the ~ddts/etc/ddtsrc file. This will make it so the
updater is not automatically excluded from the list of
recipients.
Also, multiple state transitions will only generate one mail
message unless the user commits each change separately.
The bugmail program must run real-user-id ddts. It should
not be run directly by users.
ADDRESS DETERMINATION
Here is how bugmail determines which email addresses to
notify.
First, notification mail is normally not sent to the person
performing the change (see Allow-updater-mail above). To
be more technically precise, bugmail compares defect record
field Updated-by to the userid in question; if they match,
mail is suppressed.
Addresses to which email will be sent come from the
Submitter-mail, Engineer-mail, and Other-mail fields in the
defect, and from the proj.notify list for the state(s) of
the defect.
For the Submitter-mail, the actual logic is as follows:
If the first 5 characters of this defect's
Identifier matches this DDTS site's site ID
(i.e., submitted on this site)
AND Submitter-id is not null
AND Submitter-mail is not null
AND Submitter-id is not equal to Updated-by
then send email to Submitter-mail
NOTE: The field "Old-Machids" in ~ddts/etc/ddtsrc can contain
a space separated list of site IDs. The Identifier is matched
against this list as well. This list should be the previous
site IDs for this installation if the site ID ever changed.
It must be manually editted by the Administrator.
Likewise for Engineer-mail:
If this record's Engineer field is not null
AND Engineer-mail is not null
AND Engineer is not equal to Updated-by
then send email to Engineer-mail
NOTE: If the Engineer has changed, mail is sent to both the
old and the new values of Engineer-mail.
Similarly for Other-mail but there is no corresponding "-id"
and "-mail":
For each token in Other-mail
if token != Updated-by
send notification mail to 'token'
Similarly for the project notification lists:
- Determine the states that the defect transitioned
through.
- For each state "X" that the defect transitioned
through on the current transaction, retrieve
X-notify from the proj.notify.
- For each token on each retrieved list, if it is not
equal to Updated-by then send notification mail.
Each token in X-notify can be a combination of mail
addresses, field names from the current defect and field
names from the proj.notify.
For example:
O-notify: fred $A-notify $Opened-mail
In this example, the notification list would contain "fred",
the contents of A-notify from the proj.notify file and the
contents of the field Opened-mail in the defect that bugmail
is currently processing. The assumption in this example is
that the current defect does not define a field A-notify.
Otherwise the contents of the defect would take precedence.
All the notifications are built and queued in a table, then
sent at the very end. This process inherently drops
duplicates since the key to the table is the mail address
to which mail is being sent. So if the same user is listed
as Submitter-mail and on the project notify list for example,
they do not receive two copies of the mail.
NOTE: If the userid is specified differently in the two
places, i.e. as a simple userid in one place and as a fully-
qualified email address in the other, the user might receive
duplicate mail.
NOTIFICATION MAIL CUSTOMIZATIONS
For each user to which bugmail intends to send email,
bugmail will choose one template to retrieve the
configuration parameters. It will look for one in the
following places in this order:
~ddts/www/user_prefs/.notify.tmpl
~ddts/class/$class/notify.tmpl
~ddts/class/$class/mail.subject
The first notification template that applies is used. The
username is the name of the user (email address) that
bugmail is trying to notify. (A system controlled email
alias is also acceptable as a "username").
No matter which file bugmail uses, it sets certain
variables and expects a Message-template file (see below)
to be able to derive certain fields.
The following variables are defined before running the
notify.tmpl file in the context of the new version of the
defect:
$OLDSTATUS - The previous state letter of the defect
record.
$TRANSITION - State transition (new state letter) for
which the mail is being generated.
$TRANSITION-TYPE - Analysis of changes to the defect:
"new" - no old bug
"transition" - State/Class/Project changed
"assign" - Engineer changed
"modify" - something changed
$RECIPIENT - The email address (possibly stripped) for
which we are sending mail. (See Notify-
domain later)
In addition, all the old fields are also available to the
notification template and have been renamed to have "--"
prepended to the names. For example, the old headline can
be accessed via the name "$--Headline" while the new headline
is accessed with "$Headline".
Setting Bugmail Fields
The notify.tmpl can set any field the administrator wants
to set, but only the following are currently being used:
__________________________________________________________
Subject Subject of mail message (Required)
Message-template Template to run instead of
master.tmpl to notify users
Suppress-mail (Y/N) suppress mail if no changes
Display-added-enclosures (Y/N) should change_history
print added enclosures?
Show-enclosures-on-submit (Y/N) should change_history
show all enclosures on submit?
Bugmail-diff-command $~/bin/bugmail_diff
__________________________________________________________
The Subject field is mandatory and will be used for the
subject of the email notification message.
If a Message-template field points to a non-existent
template file then NO MAIL WILL BE SENT for that ID and
user. For ease of upgrading, Message-template will be
preset to the value of "$~/class/$Class/master.tmpl" if it
exists, but this can be changed. The Message-template file
is processed with the contents of the new defect with
$OPERATION set to 'n'.
The Suppress-mail field tells bugmail not to send an email
if there are no unsuppressed differences to the defect. If
this field is set and "nothing" changes, no email is sent.
If the change_history filter is NOT run in the Message-
template file, then this flag has no effect and mail is
still sent out.
The field Display-added-enclosures determines what to do
when diffing enclosures when an enclosure is added. If set
to "N", only the string "Enclosure %s has been added." is
added to the mail message. If set to "Y", the entire
enclosure is shown. This flag is used to prevent
redundancy in the mail message. Some templates do not
print all enclosures, so you would want to print the
added one during a diff. But many other templates print
all enclosures in the notification mail and this means the
added enclosure would already be in the mail message. This
flag does not control what happens with a "new" bug.
The field Show-enclosures-on-submit is similar to the
Display-added-enclosures flag, but it only controls
enclosures when the bug has just been submitted (no old
bug). If set to "Y" (default is "N"), the contents of all
enclosures is shown in the change_history portion of the
output. This flag is independent of the Display-added-
enclosures flag.
The field Bugmail-diff-command is meant to contain the
path to the command used to compute the differences
between two versions of a enclosure with the same name.
The default value is $~/bin/bugmail_diff. The script is
expected to take three arguments:
bugmail_diff "title" oldfile newfile
where oldfile and newfile are paths to temporary files
containing the old text and the new text.
The exit status of the bugmail_diff program is ignored. If
the bugmail_diff program prints any text to stdout, then
it will be assumed that there are differences to report on
this enclosure and the text of the bugmail_diff program
output will be printed.
Users can create their own bugmail_diff program by copying
and modifying the example bugmail_diff program and setting
the derived value of Bugmail-diff-command to be the path
of this new program.
History enclosures are not compared.
Suppressing Bugmail
The Administrator can create a file named
~ddts/class/$class/bugmail_ignore_fields in dfile format.
The fields that the Administrator puts in this file will
be ignored by the change_history filter. Values do not
need to be placed in the dfile, just the names of the
fields. See the dfile(5) man page to find out more about
this format. Enclosure differences can be suppressed by
changing the Bugmail-diff-command to specifically suppress
changes. Any field that is "unset" while deriving the
message template (not the notify.tmpl) will not be
included in the change_history.
Debugging Problems
The bugmail program appends messages to a log file,
~ddts/spool/LOG, recording all defect records it has
processed. The log file may be examined if mail
notification problems occur. The size of LOG is controlled
by the ClearDDTS cleanup utility, ddtsclean(1). The
Administrator can add the following setting to the
~ddts/etc/ddtsrc file to control how verbose bugmail is:
Bugmail-verbose-log: Y
Administrators trying to debug their customizations to
control bugmail will probably want to set this field, at
least temporarily.
FILES
~ddts/class/$class/notify.tmpl Template to configure bugmail ~ddts/class/$class/bugmail_ignore_fields List of fields to not compare ~ddts/spool/bugmail Spool directory for bugmail ~ddts/spool/LOG Log file ~ddts/conf/* Configuration files ~ddts/etc/ddtsrc Configuration file ~ddts/allbugs/??/* New versions of defect records
SEE ALSO
bugs(1), bugs.in(1), ddtsd(1), ddtsclean(1)