Caucus How-To: Pre-registering Users Last revised 30 August 2002.

I. Introduction

The first time that a person uses Caucus, they will normally be asked to "register" themselves.  This means that they will be asked to enter their full name, and (optionally) a telephone number, a brief personal introduction, an e-mail address, and so forth.  This registration process only happens once, although a user can change their personal information at any time.

Alternately, the Caucus manager may choose to "pre-register" an individual user, or groups of users.  This is particularly useful if you have a large body of users who are about to begin working with Caucus, and you want to enforce consistent use of names, phone numbers, e-mail addresses, and so forth for this new group.  Pre-registration also allows you to automatically join groups of users to specific conferences, which may ease the users' confusion about which conferences are important to them.

You can pre-register users in two different ways:

1. Individual registration.  You may register individual users from within Caucus on the Web.  (You must be a Caucus manager with the "create a user" privilege.)  From the Caucus Center, choose the "manage this site" link (underneath your name).  From the management page, choose "Create User".  From this page, you can create a userid (if allowed) and register a single person to that userid, supplying their full name, e-mail address, and so on.

2. Batch registration.  Your Caucus kit also includes a shell script (Unix) or batch file (Windows/NT) called wregister.  This script allows you to register many users at one time, using data in a prepared format. 

The rest of this document describes the use of wregister.

 

II. Using the WREGISTER script

To pre-register a batch of users, you must actually log in as the "Caucus" userid.  (Under Unix, telnet to your host and login as Caucus.  Under Windows/NT, login to the console as Caucus, and start a "cmd" or MSDOS window.)

From here, you will type the appropriate command to run the wregister script.

To use wregister, you must specify a filename on the command line.  For example, to register users from the file prereg, type

   wregister prereg

The file prereg must be in the home directory of the Caucus account and contain the pre-registration information described below.

 

III. File Format -- Basic

The file which contains the list of users to be registered must be in a specific format.  This format includes some necessary information and some optional information.  The following information must be included:

1. Full Name
2. Last Name
3. Web Userid

The following information may also be specified:

4. Telephone number
5. Default settings
6. Personal Introduction
7. Initial conferences
8. Personal Conference List (a user variable)
9. Other User variables
10. Comments

The file may include information for as many users as the host computer system will support.

The information for each person must be supplied on 2 or more lines.  These lines must be together in the file.  The first line supplies items 1 through 4 from the list above, e.g.:

    Jeff Victor:victor:jvictor:(313)-482-8710:

Note these rules about the first line of a person:

• Each field must be terminated by a single colon.

• No field can have a colon in it.  This is especially important for the User Name and Telephone Number fields.  The other fields shouldn't have a colon in them anyway.

• The only thing that distinguishes the fields is their order on the line!

• The first and fourth fields are free-text fields, and can contain Roman characters, kana, and/or Kanji.  For example, the phone number can be anything.  The second field must be one word, but can contain Romanji, kana, and/or Kanji.  The third field must be one word, lowercase ASCII, with no spaces.

• The phone number can be blank, but the (empty) field must still be terminated by a colon.

So, the official technical specification for this line is:

     Full Name:last_name:userid:phone:

The rest of the information lines for a person each begin (in the first column) with a special letter indicating the type of information supplied by that line.  This letter must be uppercase.

The other mandatory line is just a line indicating that this is the end of this user's description.  It is a single 'E' in the first column.

Here is an example of the simplest description:

     Jeff Victor:victor:jvictor:(313)-482-8710:
     E

IV. File Format -- Optional Information

This section describes how to specify the optional information (items 5 through 10 in the list).

1. Default Settings.  The default settings apply only to the (old) Caucus text interface, and not to the web interface.  In most cases these settings may be ignored.

   If you need to add a settings line, it must begin with an 'S'.  This line must be in the same format as the "sys_Tset0" string in the dictionary file DIC2/america0.  Any legal values can be specified.  If the manager chooses to have the user start off with the 'normal' default settings, the line looks like this:

   Soff 23 79 off caucus 8 12 default on 0 . off wordwrap 0 later execmenu
   

2. Personal Introduction.  A Personal Introduction can be many lines long.  Each line must begin with an uppercase 'I'.  Each line may contain Romanji, kana, and/or Kanji.

3. Initial conferences require one line each.  Each line must begin with an uppercase 'C'.  This must be followed by the entire conference name.  Conference names must be in all lower case, and underscores must be used in place of blanks between words in a name.

   Although initial substrings of conference names can often be used, if an ambiguous name is used, the user will not be joined to the conference, the program will complain to the manager, and then it will continue.

   Specifying an initial conference "joins" the person as a member of the conference.  It does not mark any of the conference items as "read", nor does it add the conference to the user's personal conference list.  The user must be allowed to join the conference; otherwise an error message is displayed, and the 'C' line is ignored.

4. Personal Conference List.  This list is actually maintained as a Caucus "user variable" called my_confs.  To add a conference to the user's personal conference list, add a line containing an upper case 'V', followed immediately by "my_confs", a space, and the conference name.  For example,

       Vmy_confs demonstration
   

   adds the demonstration conference to the user's list.  (Unlike section #3, conference names here may be in mixed case and have blanks in the names.)

5. Other User variables follow the same format as "my_confs": a 'V' followed by the variable name, a space, and the value of the variable.  If the variable should contain multiple lines of text, they must be split up on multiple 'V' lines.  (Each such line appends another line of text to the variable.)

6. Comments.  You may insert comment lines anywhere in the file.  To signify that a line is a comment and should be ignored by the maintenance programs, start it with a '#' ("pound sign", or "hash mark").  Each line may contain Romanji, kana, and/or Kanji.

   There should be no blank lines in the file.  If you need an otherwise blank line for visual spacing, enter a line with just a "#" comment.

 

V. A Complete Example

   #This is the first user:
   Jeff Victor:victor:jvictor:(313) 482-8710:
   IThis is a user's brief introduction.
   IIt is two lines long.
   # This is a comment
   #
   # The rest of the lines for this person are conferences
   # to join the user into:
   Cdemonstration
   Csales_conference
   Vmy_confs demonstration
   Vmy_confs sales conference
   E
   #
   #This is the second user, with no phone number, and a setting
   #for their "homepage" variable.
   Charles Roth:roth:roth::
   IThis is the introduction.
   Cdemonstration
   Vhomepage http://gamgee.acad.emich.edu/~roth
   E

VI. Errors

If the program detects an unrecoverable error about a particular user (e.g. that ID already exists), it will complain about the user, not register him/her, and attempt to continue.

If the program thinks that the disk is full, it will mention this and then give up.

The software tries to protect the user from most mistakes, but it's possible to really confuse it, in which case it may complain and give up.  On the other hand, if you include a colon as part of a user's name, it may fail in strange ways.

VII. Web passwords

One glaring hole in the use of wregister is that there is no way to define the userid and password for a web user.  This is an unfortunate historical accident, due to the fact that wregister was originally written for the pre-web version of Caucus.

An upcoming version of Caucus will feature a much better way of handling user pre-registration, via spreadsheets sent by e-mail.  In the meantime here is a "kludge" approach that you can use in combination with wregister to completely pre-register web users.

This method assumes that you are using the caucus_passwd file to store the user names and encrypted passwords.  (That is the default, unless you have implemented LDAP or some other authentication method.)

The Apache web server includes a simple program called "htpasswd" that can be used to manipulate the caucus_passwd file.  To add a single userid and password, you can type:

   htpasswd -b /home/caucus/caucus_passwd userid password

assuming that htpasswd is in your search path, and that Caucus is installed in /home/caucus.

To register many userids and passwords with Caucus, here's one possible procedure:

1. Build the list of userids and personal information, as described earlier in this document, in a file called prereg.

2. Build the list of userids and passwords in a separate file, called prereg_ids.  Each line of the file must contain a single userid, followed by a blank, followed by the password.

3. Make sure htpasswd is in your search path.  For example, if you have installed Apache in /usr/local/apache2, then htpasswd is probably in /usr/local/apache2/bin.  Either add that directory to your PATH, or explicitly type the full pathname of htpasswd in the next step.

4. From the Caucus home directory, type the following lines at the unix shell prompt:

      ( while read a b; do
           htpasswd -b caucus_passwd $a $b
        done ) <prereg_ids
   

5. Run "wregister prereg" as described above.