| Caucus E-mail Interface Installation and Usage
Copyright (C) 1996-1999 CaucusCare. |
 |
1. INTRODUCTION AND PURPOSE
The Caucus e-mail interface package adds a "listserv" or mailing-list like capability to the existing Caucus conferencing system.
With this optional package, you can extend the use of your Caucus conferencing system to people who have only e-mail access to the Internet.
When this package is installed and enabled, each Caucus conference organizer can specify a list of e-mail addresses that may participate in that conference. New material (items and responses) are automatically sent to those participants, via e-mail, on a regular basis.
Those users may in turn contribute to the conference by simply replying to those messages. The replies are automatically placed in the proper conference and item.
Note: as of Caucus 4.6, email participation is automatically installed when you install Caucus. (See the new directions.) So the remainder of this document only applies for sites that use earlier versions of Caucus.
2. INSTALLATION
2.0 Caucus 4.0
Warning! If you installed the Caucus 3.1 version of the Caucus e-mail kit, and you have upgraded to Caucus 4.0, you must reinstall the e-mail kit from scratch.
2.1 E-mail Kit Contents.
The Caucus E-mail link kit is contained in a file called "email.tar". It contains this README file, the 'einstall' installation script, and a compressed kit file, kit.t.Z.
2.2 Create the Caucus Mailer userid ("caumail").
Create a Unix userid that is dedicated to handling the e-mail for this interface. (The 'root' user or system administrator must do this.) A good name for this userid is "caumail", although any userid will work. (Do not use the regular "caucus" userid for this account. This must be a separate userid that is only used for this purpose.)
This userid must be able to use the Unix 'crontab' utility.
2.3 Install the software.
Login to the id you created in step 2.2. Do NOT install the software as root! Download or copy the email.tar file to the home directory of that id. Type:
tar xvf email.tar
./einstall
Follow the instructions that are displayed.
Initially the e-mail updates will be sent out once per day. (The same operation "posts" incoming responses received via e-mail.) This may be changed by examining and modifying the contents of the "crontab" listing for this userid.
2.4 Connect the e-mail link to Caucus.
To finish the installation, you must "connect" the Caucus e-mail link software with your regular Caucus installation.
Login to the "caucus" userid. From this id, run the script called "copysweb" that is located in the Caucus Mailer userid's home directory. (For example, if the Caucus Mailer userid's home directory is /home/caumail, then type "/home/caumail/copysweb".)
Now edit the file CML/SP40/Local/switch.i (for 4.0) or CML/CS41/Local/switch.i (for 4.1), and change the definition of the "mail_out" variable to be the Caucus Mailer userid (for example, "caumail").
3. CONFERENCE ORGANIZER INSTRUCTIONS
To allow e-mail users to participate in a conference, the conference organizer must do two things from the "customize" page:
3.1 Include the Caucus Mailer userid in your conference.
Add the Caucus Mailer userid from step 2.2 to the list of users included in your conference. This only needs to be done once.
3.2 Add individual e-mail users.
For each e-mail user that is participating, add their e-mail address to the "Section IV: E-mail participants" box at the bottom of the customize page.
Note that this must be the address that appears on mail sent from the user. Caucus uses the entries in the E-mail participants box for two purposes: to determine who to send mail to, and to control who mail will be accepted from.
This is somewhat subtle point. A person with simple "mail to" address may actually have a longer "from" address. You must use the "from" address. (Some people may also have multiple e-mail aliases that all point to their "real" e-mail address. In either case, you must always use the "from" address that appears in their replies.)
To remove an e-mail participant, simply delete their address from the box. (There is no way to "rename" an e-mail participant to another e-mail address.)
4. E-MAIL PARTICIPANT INSTRUCTIONS
When an e-mail participant is added to a conference (in step 3.2), they will receive the entire contents of the conference as e-mail. Each item will appear (with all of its responses) as one message. The subject heading of the message begins with "::Caucus", and then shows the conference name, item number, response numbers, and item title.
Thereafter, as new items and responses are added to the conference, e-mail participants will receive regular updates (typically daily). All new responses to an item will be delivered as one message. Each new item (with its responses so far) will be delivered as one message.
An e-mail participant may add a response by simply replying to the appropriate message. A reply to a particular message will be posted as a response to that item.
E-mail participants may post HTML responses, by making the first word of their response be "<HTML>". (It must be followed by a space or a return.)
E-mail participants may post new items by replying to any message (from the relevant conference), and changing the subject field to remove the item and response numbers. (I.e., the subject field should just contain the "::Caucus" and the conference name.) On most mailers, this can easily be accomplished by simply backspacing over the subject until the conference name is reached.
The first line of the message will be used as the item title. If the first word of the title is "<HTML>", then the entire item text will be treated as HTML.
5. APPEARANCE OF E-MAIL POSTINGS IN A CONFERENCE
Items and responses posted by e-mail participants look just the same as entries made by regular Caucus users.
The only exception is the name of the participant. The name will appear as plain text, typically followed by their e-mail address, shown "blued" as a link. (Since Caucus doesn't know anything else about them, only the e-mail address is active.)
Conference organizers can delete or edit the participants' items or responses in the usual way.
6. POTENTIAL PROBLEMS
There is one known problem, having to do with e-mail replies.
For many mailers, when a user replies to an e-mail message, the content of the original message is made part of the reply, with a "> " before each line (to distinguish it from the reply proper).
The Caucus e-mail package understands this syntax, and strips all such lines from the text before adding it as a response.
However, some mailers use other methods of marking the lines from the "original text". As these methods are identified, those lines should also be stripped out! (Otherwise a potentially exponential growth may apply, as replies to replies to replies etc. get posted in the conference.)
See the section in the file import.cml in the Caucus e-mail package for more information about how to accomplish this stripping.