Scripts which receive and process e-mail

Razor encourages the use of an often overlooked capability on UNIX systems; the ability to send e-mail directly into a program or script (as opposed to sending it to a specific user). The mechanics for doing this are fairly straightforward, and allow for a great deal of flexibility and power.

To best understand how this works, we'll explore it in the context of an example.

The issues program allows for specific e-mail addresses to receive a message on certain state transitions, as defined in the Permissions file¹. Suppose, however, that rather than always sending e-mail to a fixed address, we wanted to notify the originator of an issue when the issue is Closed. A common approach is to use the Permissions file, but instead of having the issues program send e-mail to a user account, it sends the message directly into a shell script which decides the best route for further e-mailings.

The first step is to write the script itself, a variation of which is shown below. (A more fully commented form of the script can be found in the Razor release in the file
$RAZOR_HOME/examples/notify_on_closure.)

#! /bin/sh

FULLTEXT=/tmp/$$.1
cat > $FULLTEXT

. /local/razor_db/rz_prep.sh
. $RAZOR_HOME/scripts/rz_toolbox

INUM=`egrep 'Issue.*has been mod' $FULLTEXT | cut '-d ' -f3`

RAZOR_GROUP=++ISSUES++
razor_learn $INUM

INFO_FILE=$RAZOR_UNIVERSE_DIR/DOMAIN_01/++ISSUES++/Info/$INUM

ORIGINATOR=`nawk '/STATE.*Submit/ {print $4}' $INFO_FILE`
      WHEN=`nawk '/STATE.*Submit/ {print $3}' $INFO_FILE`

mail -s "$INUM has been closed" $ORIGINATOR << -EOF1-
FYI... Issue number $INUM, (which you originated on $WHEN)
has been closed out.
       Title: $RAZOR_Title
    Priority: $RAZOR_Priority
-EOF1-

exit 0

In brief, the script is performing the following steps...

1. It first captures whatever is coming in on standard input out to a temporary file. This is the body of the e-mail sent as a result of the state transition of the issue.

2. The script then sources in the appropriate rz_prep.sh file, and follows that by referencing the rz_toolbox (discussed earlier²).

3. Next, it extracts the issue number from the body of the e-mail message, and uses that as an argument to the razor_learn function.

4. The info file for the issue is quickly parsed to discover who originated the issue, and when it entered the system.

5. An e-mail message is composed and sent back to the originator.

The second step is to make the appropriate modifications to the Permissions file. Fortunately, the format of the file is fairly straightforward³. All we need to do is add a fourth field to the lines controlling the permissions of who can bring the issue to the closed state. Examples of the related lines are shown below...

...
Submitted  Closed  *       closure
No-Action  Closed  *       closure
Active     Closed  *       closure
Completed  Closed  *       closure
Closed     Closed  nobody
...

Now, whenever an issue is transitioned into the Closed state, an e-mail message will automatically be generated and sent to `closure'.

The final step in accomplishing this is to make an appropriate entry in the /etc/aliases file for your site. You must establish an e-mail address which pipes the message directly into the script. In the example below, we've named the alias to be the same as the script name itself in the hopes of reducing confusion, so the line in /etc/aliases would look like...

closure: "|/local/razor_db/RAZOR_UNIVERSE_DIR/Scripts/
closure"

Note that the above edits require superuser assistance, and it will most likely need to be followed by the running of newaliases and/or other programs to fully enable the address for your network.

¹ For details on this, see "Issue STATEs (permissions)" on page 205.
² See "Using rz_toolbox" on page 224.
³ See "Issue STATEs (permissions)" on page 205.