App::GalionReSched

Galion ReSched is a web-based resource-scheduling application, written in Perl. It can be used to book limited resources (such as computers and meeting rooms), so that you always know who is scheduled to use any given one at any given time.

In addition, Galion ReSched now also features program signup lists, staff schedule tracking, and notification of incoming email to a shared circulation-desk account.

Live Demo

There's a live demonstration so you can see Galion ReSched in action at http://cgi.galion.lib.oh.us/staff/resched-public/resched/

Installation

1. Unzip or untar the downloaded Galion ReSched software in a suitable location. Issue any necessary chmod commands to ensure that the web server user can access the files and execute the cgi scripts. For security reasons, it is important to ensure that dbconfig.pl cannot be directly accessed by web users. (If .pl is associated with cgi execution, chmod ugo-x dbconfig.pl should do this.)

2. Ensure that you have the prerequisite software installed.

   • You need an RDBMS. At this time MySQL is the only one fully supported, though it would probably only require minor changes (mostly to db.pl) to support Postgres or any other reasonably capable DBMS. (Postgres support could probably be easily ported over from jonadabot.)

   • You need a web server, of course. I've only tested with Apache. The web server must be configured to serve out the directory where you unzipped resched, and the .cgi extension must be associated with perl (or may use shebangs if /usr/bin/perl is the correct path to perl on your system).

   • Speaking of which, you need perl, and at least the following modules (available from the CPAN):

     • DateTime

     • DateTime::Span

     • DateTime::Format::MySQL

     • DBI

     • DBD::mysql

     • Carp

     • Digest::MD5

     • HTML::Entities

     • Taint::Util

     • Data::Dumper

3. Open ajax.js in a text editor and change the basedir variable (on the second line) so that it contains the public URI of the resched directory on your installation. This value should end with a directory separator (forward slash). This step must be repeated any time you upgrade.

4. Open dbconfig.pl in a text editor and assign suitable values to the four variables therein. (If dbconfig.pl does not exist, start with a copy of dbconfig.pl.sample.)

5. Log into the RDBMS as a privileged user (e.g., root), create the database you specified in dbconfig.pl, and grant all privileges on that database to the user you specified in dbconfig.pl. The SQL to do this on MySQL will probably look something like the following:

   CREATE DATABASE resched;

   GRANT ALL PRIVILEGES ON resched.* TO username@localhost IDENTIFIED BY 'somepassword';

   FLUSH PRIVILEGES;

6. If you have not already done so, check that the MySQL root user account is password protected. (In most distributions this should be the case by default, but check.)

7. Run the create-tables.pl Perl script. This will create the empty database tables.

8. If you are upgrading from a previous version, check CHANGES.txt to see if there are fields you need to add to existing tables.

9. Create at least one user record in the users table, which you and your users will use to log into the web interface. You can use the create-user.pl script to do this. (Even if you are doing authentication by IP address, you still need a user account. The IP authentication automatically logs users in based on their network address, but it still needs a user account to log them into.)

10. If you want to do authentication by IP address, create the appropriate record(s) in the auth_by_ip table. Each IP address should be in the same notation the web server gives it to you in $ENV{REMOTE_ADDR}. For Apache, this is standard dotted quad notation (for IPv4; not sure about IPv6). The user field needs an id from the users table.

    Authentication by IP address is probably not real secure, but my users would never put up with needing Yet Another Password for this. If your users are willing to remember individual usernames and passwords, that's probably better.

11. Create at least one schedule. You can log into the web interface and use admin.cgi to do this. Multiple resources (e.g., rooms, computers) can be booked according to the same schedule, so you may only need one schedule record, depending on your needs. The schedule record tells what time of day you start booking and describes the positions and lengths of the booking timeslots (e.g., every hour on the hour starting at 9am).

12. For each resource you want to take bookings for, create a record in the resched_resources table. You can log into the web interface and use admin.cgi to do this.

13. Optionally, if some of your resources are meeting rooms, and if you have additional equipment available for them (e.g., tables, chairs, coffee makers, whatever), you may wish to use the admin interface to add this auxilliary equipment. Once you have done so, you can go into the resource records for your bookable resources and select which equipment is available with each resource.

14. You need certain entries in the misc_variables table. You can use config.cgi to create these. Even if you wish to accept the defaults, you should hit the save button at least once, so that the variables are created.

15. Create sitecode.pl. There's a sitecode.pl.sample that you can copy. If you need to do any site-specific name normalization, edit the normalisebookedfor function here.

16. You may need to make a few changes to the code itself, as some things may still be hardcoded that shouldn't be. As time goes on I am getting more and more of that stuff moved into config.cgi and/or sitecode.pl, but this is an ongoing process. TODO.txt might provide some clues as to what remains, but it is not entirely comprehensive. If you do need to make code changes because of things that are hardcoded, the author would appreciate hearing about what changes you had to make. Ideally, I would like to get all such things moved into the config interface and/or sitecode.pl.

17. Nonetheless, you should be able to start testing your local installation at this point.

18. If you have questions or comments, you can contact the author at the email address given in INSTALL.txt. (I'm not putting the email address in the POD, because the POD will end up as HTML that will certainly be scraped by the spambots.)

History

When I originally wrote ReSched, we had three computers that we booked in one-hour timeslots, and we wanted to move from a clipboard-based system to something that we could easily access from any staff computer.

I was pretty new to Perl at the time, so the early versions were some pretty messy code. (I've since cleaned up a lot of it, and further cleanup is planned.)

I didn't really start tracking changes until version 0.4.0, when the code was finally stable enough to go several months between updates.

Enhancements in the 0.4.x series included aliases and the "Did You Mean" feature. 0.5.x enhanced aliases and improved name normalisation and overhauled the visual style. The 0.6.x series focused on refactoring the codebase and fixing bugs, but there were also some enhancements, including automatic retrieval of new bookings.

After a conversation on the OPLIN tech mailing list, it became apparent that some other libraries might be interested in using this tool. This lead to the first public release, version 0.6.7.

The public release lead to creation of the configuration interface and a number of technical improvements (including the beginnings of MSIE support, password hashing, and configurability or automatic generation for many things that were originally hardcoded) in the 0.7.x series. The "Combine Rooms" feature was also added.

The 0.8.x series introduced the program signup facility, improved security in a number of ways, made several things more configurable, introduced an administrative interface for creating (booking) schedule and resource records, and continued cleaning up the codebase for improved maintainability.

The 0.9.x series added the word "Galion" to the name of the software (in order to make it easier to find by searching), introduced the staff scheduling feature, made further enhancements to security, enhanced the admin interface, fixed a number of bugs, and added POD documentation.

Customization Guidelines

In general, following these guidelines as you customize your installation should make upgrading to future versions of the software easier than it would be otherwise.

• Whenever possible, use the existing customization mechanisms, config.cgi, admin.cgi, and sitecode.pl.

• Keep a backup copy of your sitecode.pl and anything else you have customized, and back up (or replicate) your database on a regular basis. Any customization that you do via config.cgi or admin.cgi is stored in the database, so having a backup copy of that is important.

• If the customization mechanisms do not address the change you wish to make, but you can fix it by making a change to the data in the database (e.g., by adding records to a table), that is the next-best approach.

• If adding to the list of possible flags for any table, try to use lowercase letters as your flag characters. Lowercase flag letters are reserved for per-site use and should not conflict with any flags added in future versions of the software.

• If you change the actual code, be sure to keep track of what changes you have made. If you later need to re-apply your changes to a future version, knowing exactly what your changes are will help. (If you are comfortable using version control, such as git, that is ideal.)

  If you feel that your code changes make the software more flexible and would make it easier for other sites to customize to their needs, you may consider sending them to the author. If you are willing to release your changes into the public domain, they may be included in a future version of the software so that everyone can benefit from them. Even if you do not wish to send your specific changes, dropping the author a brief note about what you needed to change may lead to better customizability in future releases. Making the software easy to customize is a goal, albeit one that is not always fully achieved.

License

This software is provided free of charge and free of licensing restrictions (as pertains to usage, modification, or distribution) with absolutely no warranty of any kind whatsoever. Releasing this software with no licensing restrictions, the author understands it to be, effectively, in the public domain.

Galion ReSched was written primarily for the Galion Public Library. I am pleased if others can make use of it, but I cannot provide any warranty as to its suitability for the needs of any other organization, and I also cannot guarantee my ability to provide any technical support for the sofware.

Therefore, if you use this software, you must be responsible to determine whether it meets your needs and those of your organization and to make any needed adjustments to ensure that it does.

I am willing to receive feature requests and also bug reports, but I cannot guarantee that requested features will necessarily be implemented or that reported bugs will necessarily be fixed or even that I will necessarily always get back to you in a timely fashion. The needs of the Galion Public Library, and related demands on my schedule, take priority over any work that I may do on the Galion ReSched software. The software is provided to you on an AS-IS basis.

Permission to use, modify, and redistribute the software is granted, provided you agree that neither the original author nor the Galion Public Library is responsible. The author waives any right that he otherwise might have (pursuant to copyright law) to restrict your use, modification, or redistribution of the software. No such restrictions shall be made by the author.

Contributing any improvements that you have made so that they can be considered for inclusions in future versions of the software is strictly optional. I cannot guarantee that any submitted improvements will necessarily be incorporated into any version of the software that I distribute, and you are not required to submit them in the first place if you do not choose to do so.

Attribution (i.e., crediting the original author as the source) is also optional. I do not require it.

Monetary compensation for the software is not expected, and the author himself is unwilling to receive any. (I have already been paid by the library for the time I spent developing it, and I do not wish to complicate my tax filing with additional sources of income.) If you wish to make a donation to the Galion Public Library, you may (the GPL is a 501(c)(3) non-profit association library); but it is not required.