New for version 2.6 and later:
- New passwd format, you must load “req?create” once after upgrading the script files from pre-2.6 versions
- Integrated support for the standard HTTP authentication. (I still prefer cookies)
- Cookies are much simpler, now you can open wreq in multiple windows
- New email rules.
- Many other changes. Please look over the recent changes below before upgrading.
- BTW, wreq is Y2k Compliant, since it uses perl and stores the time in seconds since 00:00:00 UTC, January 1, 1970.
Note to wreq 1.x users: Version 2.x uses a slightly different database format in order to ensure future expansibility. You are *recommended* to upgrade to the latest version. Here is how to upgrade: 1. Copy all the new perl scripts into its usual places, 2. Backup your data directory (say, by making a tar file), 3. chmod or chown on everything in the data directory to give you the write permissions, 4. At your shell prompt, cd to the directory where the file ‘req-misc’ is, and run the command “perl req-misc convert12”, 5. chmod or chown on everything in the data directory back so your web server can write in it, 6. Use netscape to access wreq URL to see if the converting is OK. 6. If not, please let me know.
Introduction (click here to see Joe Heiser’s power user documentation)
Warning: Not all the features described below have been implemented yet. They’ll be worked on whenever I get spare time. As of this release, only a basic stand-alone server is implemented. You can think of it currently as an emulation of the popular req system on the web (but it doesn’t depend on req at all). The root server feature will be written soon.
Wreq is designed to be a distributed request/problem tracking system with builtin knowledge database to help systems personnel to stay on top of requests and to prompt knowledge sharing among all local support groups. Most departments in a large organization normally have their own local staff to support their computers and networks, and one common problem is that there is no easy or automatic way for all the local support groups to share the knowledge and expertise they each have. This system attempts to address this problem by automating the sharing process. To facilitate this, the organization will set up wreq on one chosen web server and configure it to be the root req server for all the departments. Each department can then put wreq on their local web server and configure it to handle requests from people within the department (or any number of departments they are supporting). People can submit requests either by accessing their local req server’s URL or by sending email to the req server’s email alias. Each req server can also be configured to handle requests from other departments too, if another department doesn’t have a web server or just don’t want to mess with it (but want the req services). The root server is there to collect the shared database items to make the sharing possible across all the departments using req services. Each server has 5 categories of data:
- Active requests: all the requests/problems from your department waiting to be resolved.
- Resolved requests: all the resolved requests of your department or supported group.
- FAQs: Frequently asked questions derived from requests that your server received. Your local server has your locally added faqs. The root server has faqs from all servers. You have the option to search either local or global faq lists.
- TechNotes: A collection of ideas and how-to’s entered by staff members when they want to share something useful with everyone else. Just like FAQs, TechNotes are shared among all servers. When you reply to a user about a request, you can include the content of any faqs and technotes in your message.
- System Log: A place to log major systems/network changes for users to view.
- SOS: Questions posted by staff members when they need everyone’s help on something. These questions are kept on the root server and visible to everyone from any req server.
You can configure your server to only accept requests from a given set of hosts and to only allow a given set of hosts to view the database items. User authentication is based on hostname, email address, password and netscape cookies. All support persons (called power users in the source code) are required to have a password to login and other users are not. The default password for power users is the password you used or changed to when you configure the server (see below).
Installation
To use wreq, first you must have perl version 5 with GDBM support installed on your web server. Install perl now if you haven’t. Gnu gdbm and perl are available from many GNU archive place. Here is how you can tell if your perl is up to the job: At a shell prompt, run the command “perl -e ‘use GDBM_File;'” (without the double quotes, of course). If it doesn’t say anything, your perl is fine. We are using perl 5.003 on Solaris, SunOS and IRIX here. Knowing some perl will make using wreq more fun. The GD module for perl is also needed to plot the usage info, see below.
First download the code by clicking here. This is a gnu-zipped tar file. Now untar it to the cgi-bin directory of your web server and you’ll have a directory called ‘wreq’ in your cgi-bin directory. All the files in the wreq package must reside in
this single directory.
Next you need to change the first “#!/usr/local/bin/perl” line in the files ‘req’,’req-mail’ and ‘req-convert’ to whatever is proper to run your perl . Now open the file ‘req-config’ in a text editor to change various global parameters. Normally you don’t need to change anything else in other files.
One script ‘req-convert’ is provided to convert old req data files to wreq format if you are currently using req. To convert, open ‘req-convert’ in a text editor, change “$reqtop=” to point to the req directory where the directories ‘data’ and ‘faq’ reside and change “$defaultemailaddress=” to the proper email address to append to any incomplete email addresses. Be warned that you might need to make some additional changes to make it work for your installation of req. Now run ‘req-convert’ from a shell to convert all the req data.
Now you need to change the ownerships and permissions of files in ‘wreq’ directory so that all the files in ‘wreq’ directory is readable by everyone (or at least your web server), ‘req’ and ‘req-mail’ are executable by everyone. The ‘data’ directory and everything in it are readable and writable by the uid and gid of your web server daemon and not by others.
To route email to the req server, you need to edit the /etc/aliases file (on the NIS server if you are running NIS, on web server itself if not) to include the following 3 aliases:
- req: wreq@your_web_server
- wreq:”|path_to_your_’req-mail’ _program”
- req-dist: uid1,uid2….
where uid1,uid2… are email addresses you want to forward all incoming requests too.
Finally the server is ready to be configured. Load the URL ‘http://your_web_server/cgi-bin/wreq/req’ in a browser and click on the ‘configure’ link. You are now looking at the server configuration page. Fill out your dept’s full name. For password, type in “numlock” (without the quotes) in the password field and type in a new password you like to the next field. I’d recommend everyone choosing a new password here. Fill in the email alias field the email alias you want your users to send requests to, as in /etc/alias file above. The req-dist list is the one you have set up in the /etc/aliases file. Leave the root server URL blank, since I haven’t done it yet. In ‘Local Support Email List’ filed enter the email addresses of people who will handle all the requests from your department, one per line. People logging in with these email addresses are power users and can do anything to the database. In ‘Permitted Hosts’ field fill in hostname or IP address patterns for all the hosts you wish to receive requests from, one per line. For now, leave the “Additional FAQ hosts’ field blank. The “Priority List” box is for you to enter a list of priorities you want your users to select from when they submit requests through the web. One priority per line and each line must have a priority number (high to low) and a name string. You can also customize your supported “OS Types” and “Areas”. Now click on the “Create” button to create the profile or click on “Modify” to make any changes.
Now you users are ready to submit requests by using the same URL or the req alias….
Submit requests
Once the URL ‘http://your_web_server/cgi-bin/wreq/req’ has been loaded in their web browser, your users will see a form with lots of fields to fill out. To submit a request, fill in Name/Email/Location/Phone# first. They are required to fill in these 3 fields only once and they will be remembered by the web server by using netscape cookies. If you have a local ph server, you can jsut fill in a partial email or name and click on “PhoneBook” button to complete them. Then choose OS type, Area and Priority Category, type in a subject and the rest. Click “Send” to send it to the server. When a power user loads this page, there is also an extra “Todo for” field; this can be used to assign a request to another supporting person.
Handle requests
Load in the URL above and click on the “keep track and follow up” link. This page is where you’ll spend most of your time to work in requests. The window is divided into 4 frames. For easy referencing, I’ll call upper-left frame “A1”, upper-right frame “M1”, lower-left frame “A2”, lower-right frame “M2”. Frame “A1” has a list of the 6 different categories of data. Click on any of them, the entries of that database will show up in frame “M1”. Frame “A2” has a list of actions you can apply to a request or faq. “M2” will be used to show the content of a request or faq. For testing, go back to the URL above and submit several requests and come back here and click on “Active” in frame “A1” when you are done. BTW, “M1” will be updated automatically every 5 minutes, so you don’t have to reload it yourself to stay current.
The “M1” frame contains a title ‘Active’ and a link for searching the database, 3 links to control how many entries to show, a link to reload current frame and a table of a list of requests. The headings of the rows of the table are in bold font. Click on a heading will cause the request list to be sorted by that column. You’ll notice that heading will be shown in a red color to indicate this fact. The default sorting is by the 1st column, which is the fastest BTW. For any request listed in “M1”, click on its request number in the 1st column to display the content of that request in frame “M2”, if you have the permission (either on req-dist list or being the sender of the request. I’ll assume you are on the dist list for the rest of this section). Click on links in other columns will selectively list only “similar” requests. The request number in the first column will be shown in green when the reuqest was just submitted or when any new info added; it’ll stay green until you act on it. Note that when you click on ‘Active’ or ‘Resolved’ in Frame ‘A1’ to bring the table in “M1”, all the requests with green
request numbers (in the first column) will be listed first and none of the headings is red; this is a programmed feature to
draw your attention to the requests which are either new or have new info from the users.
When a request is shown in “M2”, you can click on “Take/Untake” in “A2” to take/untake/steel it. Click on “Give” to give it to someone else. Click on “ActOn” to act on the request or send email to the user. When you click on “ActOn”, you’ll see a form display of the request in frame “M2”. Change anything like user’s Name/Email/Location or OS type/Area/Priority, or subject and add your input to this request, and select “update” radio box, click “Update” to update the database with all your changes. Click on “Mail” if you want to send a copy of your changes and inpput to the user as well. Select “comments” to simply add/mail a comment, “info” to mail user for more info, “stall” to stall the request, “resolve” to resolve the request, “reopen” to mark a previously resolved request open again. There is also a ‘resolve’ button in “A2” for quick resolve without any comments. To merge a request with others, just select “merge” and type in the other request numbers in the text field below and then click on “Update”. The “Attach FAQs” and “Attach TechNotes” boxes near the bottom are used to attach faqs or technotes to mail messages to the user. These 2 boxes sometimes will have a number in them already, which is the last faq or technotes you view before clicking on “ActOn”. The “2Faq” link in “A2” will let you turn the currently shown request into a faq. Same for “2Tech”. The behaviors of the links in “A2” depend on which is the last request or last faq/tech/sos you accessed. Play around and find out more…
Many other features (and bugs of course) are waiting for you to find….
Have fun!
