An Overview of WASS Function ======== The WASS system supports appointment scheduling over the web. Unlike traditional scheduling systems, which allow people to specify when they are busy, WASS allows people to specify when they are free. WASS allows appointments to be scheduled only during these free times, which WASS refers to as "blocks". The way WASS works is as follows: 1. Someone who wants to be available for appointments (let's call her "PROFESSOR SMITH") goes into WASS and creates a calendar for themselves (they only need to do this once). They then add blocks of available time to that calendar. They can add or delete such blocks whenever they like. The blocks can either be single blocks (a block of time on a specific date) or recurring blocks (e.g., every Tuesday from 9:30 to noon between a start and end date). Each block corresponds to a date and time when PROFESSOR SMITH is available to meet with other people (e.g., their "office hours"). PROFESSOR SMITH can divide any of these block into individual appointment "slots", or treat them as a monolithic unit (first-come, first-served). PROFESSOR SMITH can also assign various kinds of access limits to the blocks (e.g., restrict access to specified users and/or to users in specified courses). 2. A person wishing to make an appointment (let's call her "STUDENT JANE") with PROFESSOR SMITH goes into WASS, looks up PROFESSOR SMITHS's calendar, finds a block of available time that is convenient for her, and schedules an appointment with PROFESSOR SMITH at that time. STUDENT JANE can only schedule an appointment during one of the blocks of available time that PROFESSOR SMITH has added to her schedule. If the block she selects has been divided into appointment "slots" by PROFESSOR SMITH, then STUDENT JANE must select an available slot. Each calendar in WASS has an associated URL, so, to speed up access, PROFESSOR SMITH can advertise this URL to her students, and they can get directly to her calendar by invoking this URL. 3. STUDENT JANE and PROFESSOR SMITH each receive email notifications and reminders about the appointments, and they can go into the system to view and/or cancel these appointments at any time. The email reminders include links which, when invoked, will send back an ical stream which will cause the appointment to be added to the invoker's local calendar. PROFESSOR SMITH can also "subscribe" her local calendar to her WASS calendar, and thereby have her local calendar automatically kept in sync with her WASS calendar. What differentiates WASS from standard calendar/scheduling systems is its ability to allow people to specify their availability. This is useful in situations such as office hours scheduling (the professor is only available on specific dates for specific periods of time). It can also be used to schedule things such as specialized equipment (which has limited availability) or rooms (e.g., squash courts). WASS is useful in cases where a person or resource is available only on specific days during specific periods of time. It is not intended to replace a standard calendar system (such as Outlook), but can be used an an adjunct to such systems (WASS can generate iCal streams which can be imported into systems such as Outlook). Semantics ========= The WASS system is fundamentaly asymetric. It consist of a set of calendars created by people who hold office hours (e.g., professors, deans, advisors), and appointments made by people who meet with the calendar owners (e.g, students). It also supports the notion of managers, people who manage a professor's calendar. It should be noted, however, that WASS does not enforce any kind of role assignment. Anyone who can authenticate to the system can create a calendar. Thus a student could create a calendar that other people would access to make appointments with the student (e.g., a student who was the leader of a student organization could create a calendar on which they indicate their availability for appointments with other students who wish to meet with them). A given user could use WASS both to publish their availability, and to make appointments with other users. For example, a professor who has a calendar in the system could use WASS to schedule an appointment with another professor who has a calendar in the system. Regardless of the specific role assignments, the system remains fundamentally asymetric. It is intended to be used by people who are available to meet with other people at certain specific dates and times. This is typically what is found with traditional office hours in an academic setting. Someone who simply wishes to make appointments does not need to create a calendar in the system; only people who hold office hours create calendars. Operation ========= The WASS system is entirely web-based and its executable components (PHP scripts) are activated by user (URL) request. WASS has no continuously active code; it runs only when a user accesses a WASS URL. The only part of WASS that requires any kind of un-requested operation is the reminder system (which sends out reminders about appointments). WASS includes a PHP reminder script, and the institution running WASS must arrange to run this script at regular intervals (at Princeton, it runs once a day at 5pm). One way to do this is to create a CRON job which fires off the reminder script using the Unix 'links' or 'elinks' command. This procedure is covered as part of the installation. The operation of WASS is completely controlled by a "parameters" file ("wassParms.class.php"). The institution running WASS customizes this file as part of the installation. All localization is done through this file. Look-and-feel customization can also be done using the CSS files. WASS includes a set of administrative scripts that can be used to query and maintain the system. WASS does not include any administrator scripts for controlling the system. Instead, WASS uses a super-user password to permit administrators to login to the system using the credentials (e.g., userid) of any WASS user. Thus, for example, if a given user reports that there is a problem with their WASS calendar, an administrator can login as that user and inspect their calendar (and make any necessary corrections). A typical use of the super-user password is to login as a professor and create a calendar for them. The super-user password is the MySQL password for the WASS MySQL database. Further information about administering WASS can be found in the administer.txt file. Managers ======== WASS supports the notion of calendar "managers", people who manages someone else's calendar. Any WASS calendar can have one or more associated managers. A manager is simply another person who has a userid on the system. A manager can do anything that the calendar owner can do (add blocks to a schedule, apppointments, cancel appointments, etc.). WASS includes code that allows calendar owmners to add and remove managers from their calendars. It also allows people to "apply" to manager someone's calendar ... this causes email to be sent to that person with a URL they can use to approve or dis-approve the application. The process by which this is done is documented on the relevant WASS displays. Members ======= WASS supports the notion of "group" calendars, calendars that are shared by a group of people (e.g., a calendar for "tutors" that would be shared by a group of people offering tutoring services). Such calendars have "members" rather than "managers", but otherwise behave in much the same way as ordinary calendars. Installation ============ The WASS system includes an installation script (PHP) which assists the installer in carrying out the steps necessary to install the system. This script is designed to be invoked over the web (from a web browser). Before installation can start, the installer must do the following: 1. Setup an account on a Linux LAMP server which will hold the WASS code. This server must run Apache and PHP 5+ and have access to a MySQL server (either on the same server or on a different server). Permissions on this server should be set up such that a) the owning WASS user has read/write/execute access to the WASS files and directories; b) Apache has read/execute access to the files and directories; c) everyone else has NO access to the files and directories. One way to do this is to assign the files and directories to a Unix group to which the Apache server belongs, and give that group read/execute access. Give the owner read/write access, and turn off public access (e.g., '750' in Unix terms). 2. Create a database on the MySQL server which will hold the WASS tables. WASS will need to know the name and username and password for this database, and will also need a connection string to use to access this server. The database password will become the WASS super-user password. The WASS tables need not be created --- they get built as part of the WASS installation. 3. Download the current distribution to the Linux lamp server. 4. Expand the installation. The directory structure of WASS must not be modified. WASS uses relative URLs to access its files, so the directory structure as shipped must not be altered in any way. Permissions must be set up as specified in point 1 above. 5. Run the installation script, admin/install.php, by invoking it from a web browser. Organization ============ WASS consist of a set of objects. Each object is represented by a PHP class, and is stored in a MySQL table. The MySQL table structure is identical to the object (class) structure; that is, the object properties correspond precisely and exactly to the MySQL table properties (even the MySQL object identifier). The objects (classes) are as follows: Calendar: Stores header information about a user's calendar. Series: Stores header information about recurring blocks. Period: Stores frequency/date/time information for recurring blocks. Block: Stores information about a block of time during which a given user is available for appointments. Appointment: Stores information about an appointment. Manager: Stores information about calendar managers. AcCal: Stores information about the institution's academic calendar. Each object is defined in a PHP file found in the "classes" directory, and these files have names of the form "wassObject.class.php". For example, the Calendar object is defined by a PHP class in file wassCalendar.class.php. To each object their corresponds an identically named MySQL table. Thus data on calendars is stored in the MySQL "wassCalendar" table. All communication between WASS and MySQL takes place through the wassSQL (static) class (in file wassSQL.class.php). Documentation ============== WASS contains an internal HELP system. Clicking on the HELP button from any WASS display brings up context-sensitive help. WASS also contains an FAQ file, which should be edited locally to meet local needs. Since people don't read user documentation, I have not created any. The system is designed to be seld-documenting. In the interests of security, you should probably move this text file out of the WASS admin directory and into a directory that is not accessible to web users. It is not needed by the running WASS system. Questions about WASS can be directed to: Serge Goldstein Princeton University OIT serge@princeton.edu 609-258-6059