Grad Visit Day web application (v3)

Background

This app is used to support Grad Visit Day, held in February or March in CS (and Math). The principal user is the Graduate Recruitment Coordinator; the application is also used by invited prospective grad students to register for the event, and by faculty members to book meetings with these students.

The app was originally designed based on CSCF ST#86639
The TWiki page for v1 of this application, also based on CSCF ST#86639, can be found here: GradVisitDay.

For answers to questions not adddressed here, look at the code, or talk to Daniel Allen.

Usage

User Intructions

Up-to-date user instructions can be found on the homepage of the application https://cs.uwaterloo.ca/grad-visit-day-scheduler/

Developer Documentation

URLs

The web application can be found at:

• Production ('prod'): https://cs.uwaterloo.ca/grad-visit-day-scheduler/ and https://cs.uwaterloo.ca/grad-visit-day-signup/
• Dev code: https://git.uwaterloo.ca/cscf/grad-visit-day/
• Git tips: GitUWaterlooCSCF

Git Cloning

To set up a working dev version, you must first clone the repository to your local machine. To do so, run the following command within your web directory (/var/www):

git clone gitlab@git.uwaterloo.ca:cscf/grad-visit-day.git

Apache Permissions

Once you have cloned the repository, you will find a file named htaccessDev within the root of the newly created directory. Make a backup of the .htaccess file in the directory (which is used in production) , then rename htaccessDev to .htaccess. This will override the original .htaccess settings allowing easier setup of the development environment.

On line 4 in htaccessDev (now just .htaccess), the path to the AuthUserFile will need to be modified to point to your own .htpasswd file, which contains your dev users/password information.

If you have not created a .htpasswd file, do so using the following instructions, replacing username with your username:

cd /home/username
mkdir private
chmod 711 private
htpasswd -c /home/username/private/.htpasswd-inv username

...and supply a password for your username.

With the above apache configurations, you will have a dev environment with password protection.

Database Connection and Setup

Before you proceed, you should have the following set up:

• mysql with a dev user account and password
• phpMyAdmin

In order for the web application to display anything, it must be able to establish a database connection. To do so, you must create a file that defines some unique parameters. Navigate to the private folder we created earlier within your user directory (/home/username/private/ ) and create a file named db-passwords.inc and add these definitions to the contents (replacing your mysql username and password):

<?php
define('GRAD_DAY_APP_DB', 'app_grad_day');
define('GRAD_DAY_APP_HOST', 'localhost');
define('GRAD_DAY_APP_USER', 'your mysql username'); 
define('GRAD_DAY_APP_PASSWORD', 'your mysql password');
?>

Next, you must go to the web application's directory and find the file named db.php. On line 13, edit the require_once statement's path to point to your new db-passwords.inc file.

require_once('/home/username/private/db-passwords.inc');

Now that the application should be able to successfully connect to your database, we need to create and populate the database for testing purposes. Login to phpMyAdmin and create a new database named 'app_grad_day' (we used this name in our db-passwords.inc file). Once you have created the database, you can use a provided .sql file to populate the database. For example, we will use the app_grad_day_DATA_FOR_TESTING.sql file. Navigate to the root of the web application (/var/www/grad-visit-day) and execute the following command:

mysql -u <username> -p -h localhost app_grad_day <app_grad_day_DATA_FOR_TESTING.sql 

Use the username and password you used when configuring MySQL on your machine.

The final step is to maually add yourself to the user table in the app's database so that you are authorized to access it. Go to phpMyAdmin and select the database. Go to the 'users' table and insert a new row at the end of the table:

• For the id field, leave it blank as it will automatically generate the id.
• For the userid field, enter your WatIAM username.
• For the name field, enter you name in First Last format.
• For the office field, enter an office if you would like.
• For the type field, enter 2 (for admin).
• For the group_number field, enter 0 (not used).

Hit Go and test that you can now access the application.

Additional Necessary Code Changes

• For PDF schedules to be created and downloaded properly:
  • Path to /pdf directory on line 619 and 745 of pages/scheduleModel.php must be edited to the absolute path of the pdf directory.
• To allow signup.php to not be CAS authenticated (for registrations of students):
  • check out a second copy of the code in a separate directory, with a different .htaccess file, containing only:
  • DirectoryIndex index.php?page=signup

Optional Code Changes

The following changes should be made in production.

• On line 50 of pages/professor.php the contact info needs to be changed to your departments respective contact.
• The text on pages/signup.php is, for the most part, department/program specific. This will also need to be altered to reflect specifics of your install.
• In order to customize the list of research interests / programs, you must edit two arrays found in the code.
  1. $research_interests array on line 8 of pages/signupModel.php
  2. $research_interests array on line 6 of pages/adminModel.php
• The date of the grad-visit-day is defined by a string on line 41 of index.php. This date appears at the top of all pages, in the header section.
• There is functionality to add users and students to the database through the application itself (manually, one by one), and also edit the entries.
• The available time-slots can be changed via the 'time' table in the database.

Production Database Management

The application uses a MySQL database. The database can be modified using the GUI application phpMyAdmin.

• Production: https://cs.uwaterloo.ca/phpMyAdmin/

Database Design

The database contains 10 tables: meeting, student, student_user, user, user_student, lab, lab_time, student_lab, time, and user_time. Three of these are not used in the current version: lab, lab_time, student_lab.

The meeting table has 6 columns:

• id (a unique number to identify the meeting)
• user_id (the ID of the user who set the meeting)
• student_id (the ID of the student who the meeting will be with)
• time (the time the meeting will occur)
• location (the location of the meeting)
• meeting_with (the person/group who will meet with the student)

The student table has 3 columns:

• id (the unique number used to identify each student)
• name (the full name of the student)
• research_interests (the student's research interests)

The user table has 5 columns:

• id (the unique number used to identify each user)
• userid (the userid for the user [this should be the same as the userid used to log into CAS - if this is different from the user's CAS username, the user will not be able to access the app])
• name (the full name of the user)
• office (the user's office)
• type (the level of access the user should have: disabled, faculty, or admin)

The student_user table has 2 columns:

• student_id (this is a FK value which points to the ID of a student)
• user_id (this is a FK value which points to the ID of a user)

This table is used to link students to users. Each student ID corresponds to the ID in the students table and each user ID corresponds to the ID in the users table. This table is used to create the links which tell the app which students are interested in seeing which professors.

The user_student table has 2 columns:

• user_id (this is a FK value which points to the ID of a user)
• student_id (this is a FK value which points to the ID of a student)

This table is used to link users to students. Each user ID corresponds to the ID in the users table and each student ID corresponds to the ID in the students table. This table is used to create the links which tell the app which users are interested in seeing which students. These values determine what names show up under the 'Meeting Requested By' header in the 'Schedule Meetings' or 'Attendees' table. The lab table has two columns: (Unused in this version)

• id (unique number to identify each lab site)
• name (full name of the lab)

The lab_time table has two columns: (Unused in this version)

• lab_id (FK value which points to the ID of a lab)
• time_id (FK value which points to the ID of a meeting time-period).

The student_lab table has two columns: (Unused in this version)

• student_id (FK value which points to the ID of a student)
• lab_id (FK value which points to the ID of a lab)

The time table has two columns:

• id (unique number to identify each meeting time-period)
• time (full text description of the time-periods)

The user_time table has two columns:

• user_id (FK value which points to the ID of a user)
• time_id (FK value which points to a time-period the user is available to meet)