[Prev] [Next] [TOC]

Handling ClearDDTS Mail

Throughout the defect life cycle, ClearDDTS uses UNIX electronic mail to notify users about bug submissions and state transitions. In addition, mail can be sent between separate ClearDDTS installations for remote submission and subscription. This chapter discusses how ClearDDTS uses mail and how that mail can be customized for your environment. The following topics are covered:



Why use electronic mail?

 There are a number of benefits to using electronic mail for data transfer. For example, mail is usually the first network utility that is set up on a UNIX system, and one can safely assume that system administrators will keep it working. By piggy-backing on top of mail, ClearDDTS allows system administrators to easily manage the environment without having to administer yet another communications facility.

In addition, because electronic mail is so pervasive in the UNIX community, ClearDDTS can be connected between any two systems on the Internet or any two systems where a telephone exists. Thus connectivity can be sophisticated or simple and ClearDDTS will use whatever system is in place.



How ClearDDTS handles mail

Incoming mail for ClearDDTS usually contains copies of raw defect reports and automatic administration commands. A daemon reads this mail, and determines what should be done with the mail message.

The daemon forwards any items it cannot understand to the person who has been designated the ClearDDTS administrator. For example, mail about the company picnic sent to ClearDDTS would be forwarded to the ClearDDTS administrator. Usually such mail is from human users; these typically are questions about ClearDDTS, but occasionally they are "bounced" notification messages resulting from incorrect user mail addresses.

After reading and processing each mail message, ClearDDTS records the transaction, and deletes the message.

Note: The ClearDDTS administrator should not modify or delete ClearDDTS mail. ClearDDTS manages its own mail box with no help from human users.

Types of ClearDDTS mail

 ClearDDTS defines several types of mail messages:


Looking at an example

 To see how ClearDDTS handles mail, assume that we have two ClearDDTS machines called SFOqa and LDNcc. These machines can be any place (say California and London). On each machine is one project. On SFOqa we have project XX and on machine LDNcc we have project ZZ.

ClearDDTS uses the ~ddts/conf/aliases file to determine the mail addresses and aliases for the local host. Since formatted bug mail is only generated locally, the ClearDDTS administrator never has to worry about remote aliases.

Note: Global aliases are recognized as long as the mailer program specified in adminbug inst uses them. However, ClearDDTS does not explicitly use those aliases.
If a state transition occurs on SFOqa and a user on LDNcc must be notified, then ClearDDTS on SFOqa will send a raw bug transaction to LDNcc, and ClearDDTS on LDNcc will then send local formatted mail to the user on LDNcc.

Similarly, if an engineer on machine SFOqa submits a defect against a project ZZ that resides on the remote machine LDNcc, the raw bug (ASCII) data that comprises the transaction is sent from SFOqa to LDNcc where it is incorporated in LDNcc's database.

An acknowledgment is then sent back from LDNcc to SFOqa and SFOqa's database is updated to reflect the fact that the bug was received. This round trip handshake guarantees that no defect will ever be lost in the mail system.



Determining who receives mail

Formatted mail is generated for every state transition in four ways. The first three ways rely on fields defined within the defect. If the defect report has any of the following fields defined, then mail is sent to the address specified in that field:

If the value of $Engineer has changed, mail is sent to both the old and new values of $Engineer.

Notification list

 The fourth way formatted mail can be generated is from a notification list. A notification list is specified when a project is created. Whenever a bug enters a particular state, or is modified while in that state, users on that notification list receive a formatted copy of the updated defect. The mail notification list is defined in the ~ddts/projects/<project>/proj.notify file. For example:

N-notify: chris dave
O-notify: chris
A-notify: chris
R-notify: chris dave
D-notify: chris
F-notify: chris
P-notify: chris
V-notify: chris
In this example, the user chris is notified of every new state transition. The user dave is only notified of bugs entering or modified in the New and Resolved states. The ClearDDTS administrator and the project manager can modify this list with the adminbug mprj command.



Customizing notification mail

You can control the format and content of notification mail by customizing a notification template (notify.tmpl). You can create a class-specific notify.tmpl or create user-specific templates. To determine mail configuration parameters, ClearDDTS uses the first template file it finds. It searches in the following order:

~ddts/www/user_prefs/<userid>.notify.tmpl
~ddts/class/$class/notify.tmpl
~ddts/class/$class/mail.subject (format prior to release 4.5)
Note: Using a notification template is optional. If you do not use a notification template, ClearDDTS uses the default mail.subject file only. The mail.subject file allows you to customize the subject string of e-mail, but not the content. There are extensive comments in the mail.subject file that describe how to do this.

Mail Domain

 ClearDDTS uses the e-mail address to search for a user-specific notification template. Since some users enter their domain name (chris@bigcorp.com instead of just chris) in the notification lists and mail fields, ClearDDTS must be able to strip off the domain name prior to looking for the user-specific notification template. To ensure that ClearDDTS can find the appropriate user-specific template, enter the following field in the ~ddts/etc/ddtsrc file:

Notify-domain: @<your_domain>.com
With this field set, ClearDDTS can find the preferences file for the user chris (chris.notify.tmpl) even if the e-mail address found is chris@bigcorp.com. If the domain found does not match the domain in the ddtsrc file, ClearDDTS uses the entire e-mail address when looking for the notification template.


Debugging Tool

The options you can set for notification mail provide a great deal of flexibility. While configuring and testing your settings, you can have more verbose output for notification mail generated in the ~ddts/spool/LOG file. To do this add the following field to the ~ddts/etc/ddtsrc file:

Bugmail-verbose-log: Y
The additional output can include information on the notification template used, user e-mail address, message-template used, and other options.


Notification Options

The notification template file (either class-specific or user-specific) uses the following fields to control the e-mail parameters:

Special variables

 Notification mail sets certain variables that can be used to derive the fields appearing in the mail (see Message-template below). Defects are looked at in both their old version (before editing) and new version. The following variables are defined before running the notify.tmpl file in the context of the new version of the defect:

Variable Description
$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 e-mail address to which we are sending mail.

In addition, all the old fields are also available to the notification template and have been renamed to have "--" added to the beginning of the name. For example, the old headline can be accessed using the name "$--Headline" while the new headline is accessed with "$Headline".

Message-template

The Message-template field defines the template file used to determine which defect fields to include in the notification e-mail. By default, this field contains the path to the master.tmpl. You can create your own message template (or multiple templates) to include only the fields you are interested in. If the Message-template field points to a non-existent file, no e-mail is sent. For example:

Message-template:
	if equals $TRANSITION-TYPE modify
		echo $~/class/$Class/modify.tmpl
	elif equals $TRANSITION-TYPE assign
		echo $~/class/$Class/engr.tmpl
	elif not equals "$Project" "$--Project"
	and not equals $TRANSITION-TYPE new
		echo $~/etc/forward.tmpl
	elif equals $TRANSITION O
		echo ""
	elif equals "$Showstopper" Y
		echo $~/class/$Class/showst.tmpl
	else
		echo $~/class/$Class/master.tmpl
	fi
In this example, the $TRANSITION-TYPE and $TRANSITION variables are used to determine which message template to use for formatting the mail. It is defined as follows:

Change_history filter

 The change_history filter determines what changes have been made to a defect. In order to have a list of changes (the field change log section) appear in notification mail you must include the change_history filter in a field of the message template. How you do this depends on the message template you are using.

In the default master.tmpl (which is also the default message template), OPERATION n is used by ClearDDTS to process notification mail. In the default master.tmpl file, the Begin derivation tests for OPERATION n and sets Putmail as follows:

Begin:          unset Begin
                .
                .
                .
                if equals $OPERATION n     # mail notification?
                    set OPERATION v        # yes, pretend viewing,
                    set Do-enclosures Y    # but also show enclosures,
                    set Putmail Y          # and process mail.
                elif equals $OPERATION l   # dumpbug w/enclosures?
                    set OPERATION v        # yes, pretend viewing,
                    set Do-enclosures Y    # but also show enclosures,
                    set Putmail N          # ...with no mail processing
                 else
                    set Do-enclosures N    # don't show enclosures
                 fi
When OPERATION is n, ClearDDTS changes OPERATION to v with the addition of showing enclosures (Do-enclosures) and processing mail (Putmail).

Because Putmail is set in the Begin derivation you must add the change_history filter to the Putmail field derivation in the default master.tmpl (it is the last derivation in the default master.tmpl):

Putmail:     unset Putmail
             if equals "Y"
                   change_history "Changes to this defect include:"
             fi
To set up a change log when using a different message template, you must include a field derivation containing change_history in that template. For example:

Changes:
        unset Change_history
        "\n"
        change_history "Changes to this defect include:"
        "\n"
If you choose to include the change log you can also choose where in the e-mail message it should appear. To do this, move the entire derivation containing the change_history filter to a new location in the message template. For example, in the master.tmpl file you can put it between the Begin and Identifier field derivations to make the change log appear at the beginning of the notification e-mail.

The change_history filter can accept up to two optional arguments:

-f

 Only include the change log for fields and not enclosures.
-e

 Only include the change log for enclosures and not fields.
"title"

 Uses this text as a title for the change log section of the e-mail. The title must be enclosed in quotes. If a title is not supplied, ClearDDTS uses the following default:
+++++ Field change log (added to mail by bugmail) +++++

Defect access with webddts

Notification mail can contain a URL to access the referenced defect using the webddts interface. If you have web integration with your e-mail tool, this provides a way to quickly launch webddts and view the defect. A sample derivation containing a URL might be:

Putmail:     unset Putmail
             change_history "Changes to this defect include:"
        "\nThe URL for the defect is:\n"
        "http://web.server/ddts/ddts_main?id=$Identifier\n\n"

Subject

 This field defines the subject line of the notification e-mail. Typically the subject line includes the defect Identifier and a message appropriate to the transaction. For example:

Subject:    echo "$Project defect $Identifier"

            if equals $TRANSITION S
                echo "$$ was submitted"
            elif equals $OLDSTATUS$TRANSITION SN
                echo "$$ arrived"
                break
             elif equals $OLDSTATUS $TRANSITION
                echo "$$ was updated"
            else
                echo "$$ was moved to state $TRANSITION"
            fi

Suppress-mail and Bugmail-ignore-fields file

 You can choose to suppress notification of certain changes to a defect. For example, suppose you do not want to be notified if the only change to a defect is an update to the Timestamp. To suppress notification changes about the Timestamp field you would:

  1. Make sure the change_history filter is being run in the message template (see above).

  2. If you are using a class-specific notification template, create the file ~ddts/class/$class/bugmail_ignore_fields. If you are using a user-specific notification template, create the file ~ddts/www/user_prefs/<userid>_ignore_fields.

    This is a dfile that contains a list of the fields to be suppressed.

  3. Add the field name followed by a colon to the file. For example: 
    Timestamp:

  4. In your notification template, define the path to the appropriate bugmail_ignore_fields file. For example: 
    Bugmail-ignore-fields-file:
        echo ~ddts/www/user_prefs/<userid>_ignore_fields

  5. In your notification template, set the Suppress-mail field to Y. 
    Suppress-mail:
         echo Y
    When the Suppress-mail field is set to Y, changed fields are compared to those listed in the bugmail_ignore_fields file. Notification mail is not sent if the only changes to a defect are to suppressed fields.

    Note: You can also suppress enclosure changes by adding certain enclosure fields to the bugmail_ignore_fields file as in the following examples:
    Related-file::::Problem
History::::

Display-added-enclosures

 Use the Display-added-enclosures field to determine if the change_history filter should display newly added enclosures (to existing defects) in the change log section of notification mail. If this field is set to Y, the entire enclosure appears in the e-mail. If this field is set to N, only the line "Enclosure <title> has been added" appears in the e-mail. Note that this option does not control enclosures for a newly submitted defect (see below).

Show-enclosures-on-submit

Use the Show-enclosures-on-submit field to determine if the change_history filter should display enclosures for newly submitted defects in the change log section of the notification mail. If this field is set to Y, enclosures in the new defect appear in the e-mail. If this field is set to N, only the line "New record, no historical data" appears in the e-mail. This option does not control e-mail for existing defects, and is not affected by the Display-added-enclosures field.

Bugmail-diff-command

If you are running the change_history filter in your message template, changes to enclosures can also be compared. The script used to do the comparison is defined in the Bugmail-diff-command field. By default, this field is set to ~ddts/bin/bugmail_diff. You can edit this file or create your own file. If you create your own, remember to set the bugmail-diff-command field to the path for your new script.

If the bugmail_diff script finds differences to report, the changed text is printed in the changes section of the notification mail under the heading "Enclosure Changed: <title> ".


Mail for changed sites

If your site reaches 100,000 defects and you change the site identifier (see the Rational Software web site for an FAQ on how to do this), ClearDDTS needs to know about the old site identifier. To ensure that notification mail can reach users for defects with an old site identifier, add the old site identifier to the ~ddts/etc/ddtsrc file as follows:

Old-Machids: BUGno XXXxx
The notification mail process compares the site identifier of a defect to the current site and to values set in this field. If it finds a match, it acts like it owns the defect and is able to send notification mail.



Sending mail to ClearDDTS

You can easily mail a defect to ClearDDTS. To do this, use the e-mail format described in Appendix D. You may also want to refer to the ddtsmailbug shell script for an example. This script, located in the ~ddts/bin directory, includes a customization description.

You can also send mail to ClearDDTS that is appended to a defect as an enclosure. If you send mail (or reply to notification mail) that contains a defect ID for the current site in the subject of the message, that message is appended to the defect in an enclosure. If a defect ID is not found in the subject, a "Confusing mail" message is sent to the ClearDDTS administrator.

ClearDDTS also searches the subject for "enclosure=", and uses the word following as the enclosure title. If ClearDDTS cannot determine the name of the enclosure, it defaults to "mail_log".

When the message is appended to the defect, you will see text similar to the following in the enclosure:

batchbug 981116 164457 Appended via email by "chris@bigcorp.com"
<body of e-mail message>
batchbug 981116 164457 End of message
ClearDDTS checks the sender and prevents "root", "mailer-daemon", "daemon", "postmaster", and names starting with "ddts" from being appended. For more information on appended mail to defects and how to customize this feature see the man page for ddtsappend(1).


[Prev] [Next] [TOC]

Copyright © 1999, Rational Software. All rights reserved.