E-mail entry of issues

Perhaps one of the most popular special features of Razor is the ability to submit new issues via e-mail. This allows customers and service personnel to enter new problem reports directly into the system from remote locations (or other machines at the same facility) without requiring access to a full network connection or GUI.

NOTE: You must have Razor installed on the same platform as your mail server.

Installation and set up

When a database is created, special shell scripts are generated:

$RAZOR_UNIVERSE_DIR/Scripts/rz_mail_issue_catcher1
$RAZOR_UNIVERSE_DIR/Scripts/rz_mail_issue_catcher.<issue group>

There will be a unique copy of this script for each database on your system as well as for each issue group. An <issue group> name is the name that appears in the Group pull-down in issues (i.e. the issue group name for ++ISSUES++.Test is simply Test). All that's necessary to take advantage of e-mail submission of issues is to establish an e-mail alias at your site which will send the incoming message off to the appropriate script for processing. Someone with superuser access will need to do the following steps:

1. Define a user at your site as being the Razor administrator. Modify the /etc/aliases file on the machine which processes the e-mail for your network by adding the following line:

razor-admin: <username>

The <username> entry is a comma separated list of one or more userid's that will be notified if there are problems.

2. Define the e-mail alias which will be used for the submission of issues. Enter this as another entry in the /etc/aliases file. Mail sent to this alias will be piped directly into the above named script.² For example, if the alias you wish to use is "problem", and the related database resides at /home/razoradm/razor_db, then you would add the following line:

problem: "| /home/razoradm/razor_db/RAZOR_UNIVERSE/Scripts/
rz_mail_issue_catcher"

3. As superuser, run the newaliases program to record the changes to the file. There may also be some additional steps to properly enable these modifications through NIS at your site. Your local sys-admin people should be well versed on the necessary steps.

Once the above steps are complete, e-mail entry of new issues will be enabled. The script will take the subject line of the message and enter that as the first TEXT_FIELD entry of the attribute section (typically the title line). All of the remaining attributes on the form will take on their default values. The body of the message will be entered in the first of the two text panes at the bottom of the form.

Upon completion, the initial STATE will be related to the e-mail address of whoever submitted the issue. E-mail will also be sent back to that person indicating the issue number that the entry was assigned.

Setting initial attribute values on e-mail submission

A simple text e-mail message sent to the defined address yields a very limited input mechanism. Only the subject line and first text pane are utilized. If the e-mail message is properly formatted however, it is possible to have direct control over the other attributes at the top of the form.

The e-mail message may contain a set of attribute/value pairs which will be parsed and used upon receipt of the message. There should be only one setting made per line, and the collection of settings must begin with the single keyword `SET' and terminate with the single keyword `BODY'. There should be 1 or more tabs separating the attribute name from the proposed value on each line.

The spelling and capitalization of the attribute labels, as well as the proposed values, must appear exactly as defined in the Attributes file for the database. When providing a value for a TIMESTAMP attribute, it must be formatted exactly as called out in the Attributes file. Below is a sample e-mail message, as it would affect our default attribute collection.

SET
Title           This is the preferred title
Priority        Low
Impact          Minimal
Projection      10/24/1997
Scope           Code, Library
Responsibility  Testing
BODY

And here's the text which will end up in the first of
the two text panes at the bottom of the form...

Since the formatting of the e-mail message is rather precise, and requires detailed knowledge about the options available in the related Attributes file, it is best suited for use with automated processes such as formatting scripts, programs, or intermediate interfaces.

Filling the second text pane on e-mail submission

In addition to the above functionality, it is possible to have some of the incoming e-mail message placed in the first text pane, and some of it in the second text pane.

If present in the message, everything below the following line...

#=#=#=#=#=#=#=#=#=# --- SOLUTION --- #=#=#=#=#=#=#=#=#=#

will appear in the second text pane on the issue form. Please note that the separator line must appear exactly as shown. As with setting attribute values on e-mail submission, this functionality is best suited for use with automated processes such as formatting scripts, etc.

Modifying e-mail entry behavior

The rz_issues_mail_catcher script which does most of the e-mail processing is normally more than adequate for most sites. You are not, however, required to use it, and may substitute one of your own design in its place. This would allow you to perhaps preprocess the incoming messages and set various attributes based on where the mail originated, lock out entry from certain sites or individuals, or change its default response back to the originator.

We would recommend that rather than edit the script we provide, you copy it to a new name and refer to your script in the /etc/aliases file. This will greatly reduce confusion if there are difficulties. Tower Concepts is, of course, not obliged to provide service for problems with anything but their own products. As a general rule however, we'll do what we can to help.

Licensing considerations

The e-mail interface used to submit issues acts just like another issues user if you have purchased 5, (or fewer), seats. Once you have more than 5 seats, e-mail submission acts like a parallel application which means that you can have x simultaneous issues users and x simultaneous e-mail submittals.

In other words, if you purchase 5 seats of Razor, and there are 5 copies of the issues program running when an e-mail submission is being made, then it will be refused. All of the issues license tokens will have been taken. If you purchased 6, (or more), seats of Razor, and that same number of issues programs are in use, concurrent e-mail submissions will proceed with no problem.

¹ To turn off automatic success notification, the rz_mail_issue_catcher script must be modified to set NOTIFY_ON_SUCCESS to 0.
² The idea of configuring e-mail to go directly into a shell script is also explored later in this manual. See "Scripts which receive and process e-mail" on page 247.