The first thing you'll need to do is get an account suitable for running Bookaroo. This needs to be on a machine that has Python version 1.5.2 or later (I haven't tested the script with later versions of Python, but it should work), and gives you web space with the capability to run CGI scripts. Bookaroo also assumes that some sort of user authentication is provided by the web server; more on this later. (Note for CL users: the lab doesn't provide CGI-enabled web space, and as far as I know isn't likely to in the near future. I use the Student-Run Computing Facility.)
The next step is to obtain the archive containing the Bookaroo files (see http://www.rho.org.uk/software.html). Unpack them into an appropriate place (eg, your public_html directory). The files will be created in a directory "bookaroo"; the scripts will work wherever they are, as long as they're all in the same directory, but I find it tidier to use a seperate directory. The archive should contain:
The only files that should be visible via the web are the CGI scripts themselves, ie Bookaroo.cgi and, if you're using it, Password.cgi.
Bookaroo assumes that, by the time the CGI scripts are run, the web server has sorted out user authentication and set the environment variable REMOTE_USER to the username of the remote user. The file sample.htaccess, if renamed .htaccess, will cause Apache to sort this out using basic HTTP authentication; add usernames/passwords using the htpasswd command. Password.cgi allows users to change their own passwords via the web. If you want to use more advanced authentication or a different web server, you're on you're own; let me know how you get on.
Rename the file Sample_Bookaroo.cgi to Bookroo.cgi. Now edit it to give the various configuration values more appropriate values. You should, as a bare minimum, replace the placeholder from and cc addresses with your own address, and the superuser list to be a list with a single element; your user name. [There a lot more options than this; I'll document them Real Soon Now.]
Rename the file Sample_bookarooData.xml to bookarooData.xml. This file will contain the data entered into the system. The next job is to fill it in with user data...
At present, quite a few jobs are performed simply by editing bookarooData.xml in a text editor. (Be sure that your text editor locks the file that it's editing; vi does this, but I can't speak for anything else.) The format is XML, and quite straightforward. The file is divided into three sections: users, which contains records of users, groups, which contains details of supervision groups, and calendar, which contains actual appointments. The latter is filled in by the script; don't worry about it for now.
users contains a user element for each user (supervisor or supervisee). This element has an id attribute containing the user ID of the user, and name which holds their full name. This element also has one or more child elements specifying the groups to which the user belongs.
groups contains a group element for each group of supervisees who are supervised, and hence book appointments, as a unit. It has an id attribute that is used to refer to the group, and one or more subject children detailing how many supervisions the group has left to book in a particular subject.
An example will make all this clearer:
<?xml version="1.0" encoding="UTF-8" ?> <bookaroo> <users> <user id="xxx11" name="Xavier X. Xerox"> <memberof group="1" /> <memberof group="2" /> </user> <user id="yy222" name="Yanis Yarlsberg"> <memberof group="1" /> </user> </users> <groups> <group id="1"> <subject name="Advanced Graphics" supervisions="1" /> <subject name="HCI" supervisions="2" /> </group> <group id="2"> <subject name="Project" supervisions="5" /> </group> </groups> <calendar> </calendar> </bookaroo>
Here, Xavier and Yanis are supervised in a group for Advanced Graphics and HCI; they have one supervision left in the former, and two in the latter. In addition, Xavier is supervised for his project, and has five supervisions left for that.
You should now be able to add your supervisees and groups to the database. Also add a user entry for yourself. Don't forget to also add them (and yourself) to whatever authentication mechanism you're using. Assuming you've done that, Bookaroo should be ready to use.
Point a web browser at the CGI script; after entering your username and password, you should see a timetable. If you're a superuser, you can "Add a busy message"; try this. Once you've put something in the timetable, you'll notice the "Cancel" button; only superusers get those. If you're in any supervision groups, the group members are listed, along with buttons allowing you to book any supervisions you have remaining.
From here on in, it's all fairly self-explanatory. I'll document it in more detail later; contact me if you have any specific questions.
Rob Hague ( Rob.Hague@cl.cam.ac.uk)