
                 An Introduction to the Request System

This document is an intro to using the request system.  We will assume these
things:
  - You have set up an alias called "systems" that the request system is
    being used to manage.
  - You have installed the programs with the default names that came
    with request, i.e. "q" and "req".

The system will work the same regardless of the names you actually used.


Overview
========
Req is a tracking system based around this paradigm: people with problems
or questions send requests via email to a group responsible for dealing
with those issues.  Those requests are assigned numbers that can be
tracked and managed in various ways.   The group handling the requests
needs to have access to a UNIX computer or network.

Users send request mail to "systems".  For all they know, it's just going to a
bunch of people.  Their mail is piped through a program which takes the mail,
assigns it a new request number, and puts a copy of the mail in file
associated with the number.  That file will be used as a log of all the events
associated with the request.

The mail is then passed on to the recipients of the list, with the number
of the request added to the subject line of the mail.  It will look 
something like:
  Subject: [Req #42] Help! How do I send mail?

Any mail sent through the mail alias with a request number in the subject
line is assumed to be associated with that number, and is appended to the 
log for that number.  Typically, a member of the alias will reply to the 
user and send a copy of the reply to the list.  The reply then becomes
part of that number's log.  If the user replies, the same thing happens.

Typically, a request happens something like this:

  The User
    The user sends mail with a problem:
      mail systems
      Subject: Help! How do I send mail?
      Dear Systems, I can't seem to send mail!  Help!
         -lost user
      ^D

  Request
    The request system seems mail going to "systems" with no request number.
    It gets a new number and inserts it into the subject.
      Subject: [Req #42] Help! How do I send mail?
    It makes a log of the file.
    It then forwards the mail on to the "systems-dist" mailing list.

  Systems Person
    She's reading her mail and sees her message number 19:
      19  Lost User  [Req #42] Help! How do I send mail?
    She replies, making sure to keep the request number in the subject:
      Subject: Re: [Req #42] Help! How do I send mail
      Cc: systems
      > Dear Systems, I can't seem to send mail!  Help!
      >  -lost user
      User, can you send mail describing the problem in more detail?
         -systems person

  Request
    The request system sees the cc'd copy of the mail and notices the
    req number in the subject line.  It appends a copy of the mail to the
    log for that request number.

And so the dialog goes.  As long as the number stays the same, and as long
as "systems" gets a copy of the mail, the request system will keep up. It
turns out that these conditions happen most of the time.

This is useful, in that it keeps logs of mail.  However, the request
system allows you to work with the requests themselves.   


A Request
=========
A request is something that someone has sent to the mailing list.  It may
not be a request... it may be a DEMAND, or it may be a bug report.  Whatever.

All the dialog and the actions done on a request are kept in the request log.

The log has several features:
  A requester, who is the person who originally requested it.
  An owner, who is the person, if any, working on the request.
  A priority, used by the group to prioritize requests.
  A status, which indicates whether or not the request is resolved, 
    stalled, or open.
  Several dates, indicating the time of the original request, the last
    time it was updated, and the last time the user was informed of
    the status.

One may do any of these actions (and a few others) on a request:
  Take it.  (Assume ownership if no one else owns it.)
  Give it to someone.
  Change the priority.
  Change the status.
  Add comments to it.

These can be done via mail, via a UNIX command line, or via any of the
interfaces that have been developed for it.  Currently, the only other
interface that exists is a Tk based X interface, but an emacs client
and a curses client are under development.

In addition, the queue of active requests may be viewed in a variety of
ways, based on owner (or lack of one), status, priority, requester, and
other features.


The Command Line Interface
==========================
The "q" program is used to view the queue of requests.  It's described in
detail in the manual page.  

Typically with "q", you want to see the last 10 requests:

 226% q 5:
 Req # ! Owner    Age    Told   Status  User       Subject
 ----- - -------- ------ ------ ------- ---------- ---------------------------
   826              2 hr        open    remy       make a pit-guests netgroup
   822 * remy       4 hr   3 hr open    daveg      Re: sudden problems with sz
   818   jeffc      5 hr   2 hr open    laf        Re: Powerbook for Trip
   817   mokwa      5 hr   3 hr open    kenb       Re: recover summer '93 /cou
   816   remy       5 hr        open    wand       Re: emacs-19 mail-mode abbr

This shows you:
  Req:     the number
  !:       the priority (* means 'high')
  Owner:   the person working on it
  Age:     when the request was first made
  Told:    when the requester got a message back about it
  Status:  what the status of the request is (open, stalled, resolved...)
  User:    who requested it
  Subject: what it's about 

Or perhaps you just want to see the requests that you own:
  q -owner <yourloginname>

Or the ones that no one is working on yet (oh no!)
  q -unowned

There are lots of ways to look at the queue, and they're described in
the manual page.

Once you decide to work on a request, you use the "req" program.  For 
example, suppose you want to work on Req #826:
  req -take 826
  [Req #826]  (make a pit-guests netgroup) is now yours.

Now, your name will appear in the "Owner" field of #826.

You can use req to do lots of things: give the request to someone else,
add comments to it, resolve the request, and so on.  See the manual page
on "req" for an explanation of all the options.


Watching the Queue
==================
If you want to keep an eye on the log of req actions, run:
  reqtail -f


Using Email 
===========
If you don't want to mess with the command line, you can do a few things
via email.  If, for example, you wish to reply to a user's message, and
then have the mail system resolve the request, add this line to the mail
header of your reply.
  X-Request-Do: resolve

You can also set the priority of a request, give it to someone else, 
or stall it.  See the manual page on "request" for more details on what
you can insert.

This is especially handy if you can program your mail interface with
macros that makes it easy to insert the headers.


Using tkreq
===========
Tkreq is an X Windows interface to the request system.  It works on top
of "q" and "req" and has many features of both.  It's amazingly handy if
you have X Windows.


Continuing
==========
This is just an intro to the system.  You should play around with it and
read the manual pages to continue.  If you'd like to know how to do various
things with the system, or how some of it works, check out the file "use"
that came with the source code in the "docs" directory.
