Getting the Most From the Configuring Tool Notifications |
 |
A complete script that takes advantage of the notification feature is also presented, beginning on page 82. The script can be adapted to a variety of uses.
Typical Use of Notification
As an example of the way notifications are typically used, consider the user chip, who wishes to be notified whenever the file foo.cc is put back from a development workspace into an integration workspace. To register the event with the Configuring notification feature, chip can use either the graphical user interface or a text editor to place the following entry in the Codemgr_wsdata/notification file in the integration workspace. This entry causes Configuring to send chip a message when anyone performs a putback of foo.cc that changes foo.cc in the parent:
BEGIN foo.cc END |
This basic use of the notification feature is valuable in itself, but many sites have found more creative uses for notification. The key to exploiting the notification feature is recognizing that it calls mail, a flexible program with capabilities that are often overlooked. For example, mail can send messages not only to users but to other programs through a pipe, the operating system feature that allows the output from one program to become the direct input to another.
The Ins and Outs of mail
The mail program can send messages to aliases as well as to users. If you place the name of an alias in the notification file of a workspace, a mail message is sent to all users listed in the alias. By substituting a pipe symbol (|) and a program name for a user name, the contents of the message are passed to the program instead of mailed to a user.
BEGIN foo.cc END |
These entries cause a message to be sent to foo_alias whenever foo.cc is brought over into another workspace. If foo_alias is defined as follows in the /etc/aliases file:
foo_alias:chip@monk, | /home/chip/bin/foo_log.sh
then user chip receives the notification message, and it is also piped to chip's private program foo_log.sh. In this case, foo_log.sh is a script that extracts the Date: and User: lines from the mail message and appends them to a log file. Because these lines contain the date the message was sent and the name of the user who performed the bringover, the log file accumulates a concise history of who brought over this important file.
Mailing a Policy Statement
Real-world examples of custom notification scripts are common among Sun WorkShop TeamWare sites. One example, taken from the annals of SunOS development, is described briefly on page 12. In that case, a notification is placed in top-level workspaces that causes a policy statement to be sent to users who bring over files for the first time. The policy statement details the responsibilities of users who edit files from top-level workspaces and alerts new users that are not able to put back files to top-level workspaces without special permission.
A mail alias provides a straightforward way to automate sending the policy statement. First, the person responsible for the top-level workspace places the required line in the Codemgr_wsdata/notification file of the workspace. For example, the following line, entered without BEGIN and END keywords, causes a message to be sent to newuser_alias whenever someone brings a file over from the workspace:
newuser_alias@mach bringover-from
A line is then placed in the /etc/aliases file on mach to define the alias. The following line causes a message that is mailed to the alias to be piped to the script newuser.sh. The script is designed to parse the mail messages and take the desired action. newuser_alias: | newuser.sh
When a new user brings over a file from the top-level workspace into a development workspace, the following occurs:
Figure 20 Typical Notification Mail Message
Copying the Message
Before attempting to parse a mail message, most scripts make a copy of the message. For example, when a script receives its input from stdin, the following line in the script stores a temporary copy of the incoming message in /tmp: cat > /tmp/incoming_message
The message can then be parsed or appended to a more permanent log file. Parsing Techniques
Most scripts that parse mail messages make heavy use of filters and utilities such as grep(1) (or egrep(1)), sed(1), awk(1), and tr(1). Consult the man pages for complete information. Checking Message Validity
Messages from the Configuring notifier contain the string "Code Manager notification" in their subject lines. A script may check this line to make sure the message was indeed sent to the script by the notifier. The following lines perform this check.:
The first part of the statement,
egrep -i '^Subject:' /tmp/incoming_message
finds every line in the message that begins with the string Subject:.
The command | head -1
outputs only the first of these lines. This step is a safety mechanism to ensure that messages forwarded to the alias (which in general may contain more than one Subject: line) are handled properly. Finally, the awk command | awk -F: '{print $2}'
defines the colon (:) as the field separator in the record (line) and outputs the second field (the string " Code Manager notification" if the message was sent by Configuring). This is the value placed in the variable SUBJECT. Extracting the User Name
The following line extracts the user name from the stored copy of the message and places its value in the script variable USER:
head -1 | awk -F: '{print $2}' | awk '{print $1}'\Q
|
Extracting the Event
The following line extracts the event from the message and places its value in the script variable EVENT:
|
Other information can be extracted with similar commands. For example, the date can be extracted by searching for `^Date:'.
Example Script
Some of the constructs described in the last section are used in the Bourne shell script shown in Figure 21. Refer to the comments in the script for an explanation of its operation.
Configuring notification mail sent to the alias script_alias@conundrum is piped to the script. The script is designed to examine each message sent by Configuring in response to putback events. If the putback is related to a bug fix, group policy requires developers to name the bug with an identifying number in the comment that is included in the message. Bug ID numbers are of the form BUG-number. The script searches each message for these ID numbers and, if the numbers appear in a database file, forwards the message to interested managers.
BUG-12 nod@naptime
identifies nod@naptime as the manager interested in BUG-12.Figure 21 Example Script for Detecting Bug IDs in Mail Files.
Example Output
Consider a bug.dbase file that contains the following lines (note the absence of BUG-121). BUG-12 nod@naptime
When this file is used with the mail message shown in Figure 20, the script sends two mail messages. The first message is mailed to nod@naptime as a result of being listed in the bug.dbase file on the same line as BUG-12. The second is sent to jdoe, the user who initiated the putback, because he mentioned BUG-121 in his comments, which is not in the bug.dbase file.
BUG-3456 torq@inquisition
BUG-6789 hoover@fbi
The reference to BUG-12 generates the message shown in Figure 22.
Figure 22 Mail to Interested Manager About BUG-12