Faculty Recruiting System

The Faculty Recruiting System is a web application and database used by applicants to CS Faculty positions and the SACA committee (chaired by a faculty member, term switching over on July 1 of each year.). Development in CS has been done by Daniel Allen. Its most common intended uses are:

• to allow candidates to submit their application package and nominate references to submit supporting documents
• to allow references to submit supporting documents for candidates
• to signal to the applications contact in CS when an applicant has registered; and applied for a job.
• to allow the applications contact and the SACA chair to review applicants and mark them short-listed.
• to allow the SACA committee members to review short-listed applicants.
• and to allow the Director of the School to review interviewed candidates and produce summary statistics.

Table of Contents

User Documentation

The Faculty Recruiting System is available at https://www.cs.uwaterloo.ca/faculty-recruiting/.

See "Attachments" below for user documentation.

See FacultyRecruitingSystemVideoUpload for instructions on importing recruiting videos.

Sysadmin Documentation

URLs

The Faculty Recruiting System is available at https://www.cs.uwaterloo.ca/faculty-recruiting/

Regular faculty members also can access the system at https://www.cs.uwaterloo.ca/faculty-recruiting-discuss/ - see the below section on "cs-info".

The running code is housed on our web cluster; files are accessible via linux.cs at /var/www/cs.uwaterloo.ca/faculty-recruiting/. The application uses mysql.cs as mySQL user app_ofas The code is based on "OFAS", the Online Faculty Application System, developed by Vu Huynh in Management Sciences. See below for more notes about the code.

Sysadmin Tasks

The following syadmin tasks should happen each year at the time of the switchover of SACA chair (July 1).

• Changing cs-recruiting email contact
• Year-end moving files

Changing cs-recruiting email contact

cs-recruiting@uwaterloo.ca receives email, also forwarded from cs-recruiting@cs.uwaterloo.ca. This email includes:

• any questions from applicants,
• automated emails sent from the recruiting application when someone submits an application or uploads a reference letter.

This email address must be updated within Connect as soon as the SACA chair changes. It is done by logging into Outlook as cs-recru , then updating Inbox Rules. An email should be sent to cs-recruiting and the chair's regular email. A sample can be found in ST#96413.

For the SACA Chairs to be able to switch to cs-recruiting in Connect, they need to be added to the cs-controlled NEXUS security group for: cs-mbx-cs-recru - this is done by a ticket request of Clayton (such as /RT#1167944)

To log into Outlook as cs-recru, log in as yourself and click on the right-most icon with your initials (or photo). Pick "Open another mailbox" and on the popup text box, type "cs-recruiting@uwaterloo.ca". As of October 2022, the current set of people on the access list are: the current SACA Chairs, drallen, kbeckman, tdietrich, and cs-director.

In case the displayed email address should be changed from cs-recruiting an application global ADMIN_ADDRESS variable controls the email contact address at the bottom of each page, and the address receiving administrative emails (new applicants, and new applications). This variable is set in $ROOT/waphplib/config.php . (See #PHP_Code below for definition of $ROOT)

A global AUTO_SENDER_ADDRESS variable controls what address is listed as the "from" of auto-sent emails. This variable is set in $ROOT/waphplib/config.php .

Year-end removing files

Rules for document retention require that applicant files older than one year must be deleted. As noted above, we do this on July 1 or thereabouts, for the previous recruiting cycle (eg., July 1 2015, we delete applicants older than July 1 2014).

From the web UI as Chair:

• In the Job Management section, press "Delete Job" for jobs prior the previous year. This will delete the job and all related applications, including all associated .pdf files, references, and reviews by SACA and regular faculty.
• In the View Unapplied section, press "Delete all unapplied" at the bottom of the page. This will delete all logins and all associated .pdf files, for logins who have not applied for any active jobs.

Note that if you do this in the opposite order, "delete all unapplied" first, you will leave behind the logins for people who had applied for the jobs you just deleted.

RT

Make a new item for next year, as a see-also from this year's deletion item. (Reminders: requester is current SACA chair; Upcoming Request, priority 9, start-date is next July 1.)

User Tasks that can also be done by the sysadmin manipulating the database

The following three tasks can be done by admin staff via the Chair View (See the Chair View Manual below). They can also be done via direct database manipulation if necessary.

• Changing SACA committee membership
• Adding regular faculty
• Changing Chair role membership - including default rejection letter

Changing SACA Committee membership by direct database manipulation

Table person has values personid, privilege_id, nexus, firstname, lastname.

e.g., when new faculty arrive:

mysql.cs% mysql
use app_saca;
insert into person (nexus, firstname, lastname, privilege_id) values
  ('smwatt' , 'Stephen', 'Watt'  , 5),
  ('lila'   , 'Lila'   , 'Kari'  , 5),
  ('eschost', 'Eric'   , 'Schost', 5);

Adding new saca committee members is a matter of adding a new line with privilege_id 2.

Their authentication is handled by UWDir via ldap (not CAS, and not nexus authentication, even though the column is labeled "nexus" for historical reasons).

Removing a committee member is accomplished by emptying the privilege_id field from their record. Note that instead deleting the row is a BAD idea- their comments will disappear from any applications, and when a new record is created with the same personid, the old user's comments will re-appear associated with the new user.

Adding regular faculty by direct database manipulation

At the start of a hiring season, if there are any new faculty, we need to add them to the "CS Info Discussion System" (see below for a description) See above about adding new saca committee members- add a new line for the user and give them privilege_id 5.

Changing Chair role membership by direct database manipulation

See above about adding new saca committee members- instead, edit the user and give them privilege_id 1. The privilege is shared by the actual committee chair, Suzana, and Daniel.

Additionally, the chair's name must be changed within /html/chair/view/reject_emailtext.inc - change this very shortly after the new chair is announced, even though rejection letters won't be sent for some time.

"cs-info" Discussion System

Previously there was a faculty "cs-info" rlogin, which is how faculty members reviewed candidates asked to interview. This has been replaced with a separate view on the faculty-recruiting system, at: https://cs.uwaterloo.ca/faculty-recruiting-discuss . It is actually a symbolic link to the faculty-recruiting directory; the code checks which URL they came in from and shows the appropriate data. The -discuss code uses an additional separate database ( app_saca_discuss) containing only the faculty_review table. (A design decision was that different HR rules cover regular faculty comments and SACA comments; this database separation allows the school to use the different HR rules).

The -discuss user-interface removes ability to see reference letters, and only displays applicants who are set to status "Interview" by the Chair Tools.

In the app_saca database, person table is set to privilege_id '5' for everyone who has access to the -discuss system (see above under 'Adding regular faculty'). This includes all CS faculty, and a few faculty in Software Engineering.

Candidates who are going to be interviewed need to be set to status "Interview" in the Chair Tools; they will automatically be visible to faculty members via the -discuss interface.

Development

Development code is stored in the campus git repository for CSCF, at https://git.uwaterloo.ca/cscf/ofas/. Install the code as $ git clone gitlab@git.uwaterloo.ca:cscf/ofas.git faculty-recruiting

• copy waphplib/config.php-template to waphplib/config.php with customisations (create new file named config.php and paste contents from config.php.template and edit required fields.)
• For development, it is important that you set ADMIN_ADDRESS and AUTO_SENDER_ADDRESS so they are not the default (prod) values!
• either set up https on your development machine, or edit setup.php, non_applicant_setup.php, and applicant_setup.php to disable https.

You need to set up a symbolic link from faculty-recruiting-discuss to faculty-recruiting. The command is ln -s faculty-recruiting faculty-recruiting-discuss

To create a new mysql user and import the default data, see the Database Tables section.

settings in waphplib/config.php:

• ADMIN_ADDRESS & AUTO_SENDER_ADDRESS : your email
• APP_ROOT : filepath location of the project
• DB_HOSTNAME & DB_DISCUSS_HOSTNAME : localhost
• DB_USERNAME & DB_DISCUSS_USERNAME : your username
• DB_PASSWORD & DB_DISCUSS_PASSWORD : your password
• DB_DATABASE : app_saca
• DB_DISCUSS_DATABASE : app_saca-discuss

If you get an error that ldap connect is not working, you need the php library for ldap: apt-get install php7.3-ldap

In order to run PHP with apache, you might need to set up other firewall connections with your IP address (similar to the instructions at https://cs.uwaterloo.ca/twiki/view/CF/NewProgrammerGuide, but with your computer’s IP address). Can also use command php -S 127.0.0.1:9000 to run locally on the built in php web server.

Set apache to run as user:

• in /etc/apache2/envvars set APACHE_RUN_USER and APACHE_RUN_GROUP to your userid.
• to set the correct permissions, go to /var/www directory and run this command. sudo chown --recursive username
• Reset apache servers. sudo service apache2 restart
• run, ps aux|grep apache2, to test your changes have worked. There should be one process running as root while the rest run as the newly set userid.

For pdf manipulation, the pdftk snap package is currently used. It can be installed using sudo snap install pdftk, after which a symlink must be created with sudo ln -s /snap/pdftk/current/usr/bin/pdftk /usr/bin/pdftk.

The following changes/additions were also made in order to correctly start the development environment using Apache as of Winter 2021:

• In the file /etc/apache2/sites-enabled/000-default.conf, change the apache root directory from /var/www/html to the parent directory of faculty-recruiting.
• Change the root directory as well in /etc/apache2/apache2.conf to the new root directory.
• Allow write permissions to /var/lib/php using chmod 777 /var/lib/php
• Install ldap-utils with apt-get install ldap-utils
• Have an admin help you create a chair user for the application, or create one manually using mySql (see the Database Tables section below under INSERT INTO `person` ).
• Working around ldap connections by adding return true on the first line of the method checkIfUserExists() in html/chair/users/add_user.php, and changing "nexus.uwaterloo.ca" to "ldap-nexus.uwaterloo.ca" in the "ldap" case of method authenticate() in phplib/Authenticate.php.
• To workaround authentication issues when logging in (username/password combo doesn't exist, multiple usernames, ldap_bind() issues), add a return true at the beginning of nexus_authentication() in authentication.php. This will allow any user to log in with any password. (password validation ignored) IMPORTANT: Don't push this code change, it is meant to be used locally.
• To resolve sql_mode = 'ONLY_FULL_GROUP_BY error, run this sql command. mysql > SET GLOBAL sql_mode=(SELECT REPLACE(@@sql_mode,'ONLY_FULL_GROUP_BY',''));
• If you are encountering a webpage wasn't found error look at the webpage url and see if https was forced. To workaround this, go to applicant_setup.php and comment out the "force SSL" section. Also do this for "force SSL" section in non_applicant_setup.php and setup.php.
• In the apache configuration file, set "AddType" to application/x-httpd-php .php
• To setup Email SMTP for localhost, see the following: https://gist.github.com/raelgc/6031274. This email should be your ADMIN_ADDRESS and AUTO_SENDER_ADDRESS.

Database Tables

See the file schema.sql in the root directory of the checkout for a schema with sample data. (It may also be browsed via the web, here: https://git.uwaterloo.ca/cscf/ofas/blob/master/schema.sql )

You will be creating two mysql databases, creating a non-root mysql user for the application, and granting the new user full privileges on the new databases. Replace newuser and password below with your preferred mysql username and password. This password should be one that isn't used elsewhere in case it is accidentally checked into git. Be careful to use the correct quotes and back-quotes below - it's easier to copy-and-paste rather than typing them out.

From the command-line, login to mysql as the root user: mysql -u root -p.

mysql> CREATE DATABASE IF NOT EXISTS `app_saca`;
mysql> CREATE DATABASE IF NOT EXISTS `app_saca-discuss`;
mysql> CREATE USER 'newuser'@'localhost' IDENTIFIED BY 'password';
mysql> GRANT ALL PRIVILEGES ON `app_saca`.* TO 'newuser'@'localhost';
mysql> GRANT ALL PRIVILEGES ON `app_saca-discuss`.* TO 'newuser'@'localhost';

Exit mysql with \q or exit. You may have to restart mysql with sudo service mysql restart after creating this user.

From the linux command-line, import the database via: mysql -u newuser  -p app_saca < schema.sql.

After the sql database is setup, a user must be created for the dev in the faculty recruiting system

mysql> INSERT INTO `person` (`personid`, `privilege_id`, `nexus`, `firstname`, `lastname`) VALUES (NULL, `1`, `your_watiam_id`, `your_first_name`, `your_last_name`):

PHP Code

The production PHP code is located in the linux.cs.uwaterloo.ca filesystem as: /var/www/cs.uwaterloo.ca/faculty-recruiting (referred to elsewhere in this document as $ROOT).

Global configurations are set in $ROOT/waphplib/config.php.

Many .php scripts call .inc template files.

The filestructure is:

./javascript
./images
./html
./html/saca
./html/saca/review
./html/saca/report
./html/saca/view
./html/saca/job
./html/chair
./html/chair/review
./html/chair/report
./html/chair/upload
./html/chair/view
./html/chair/job
./html/applicant
./html/applicant/register
./html/applicant/authenticated
./html/applicant/retrieve_password
./html/summary
./html/upload

Development code should be checked out on your dev workstation.

Testing code is checked out on the production web server, at /faculty-recruiting-testing . The -testing copy generally uses database.cs user drallen, but we switch to using production's user 'app_saca' when we are very close to releasing another version.

There are minor differences between production and the development code:

diff faculty-recruiting/.htaccess faculty-recruiting-dev/.htaccess
2c2
< RewriteBase /faculty-recruiting/
---
> RewriteBase /faculty-recruiting-dev/

Additionally, there are differences in the file faculty-recruiting{,-dev,-testing}/waphplib/config.php - which contain database and URL define() sections.

• For development, it is important that you set ADMIN_ADDRESS and AUTO_SENDER_ADDRESS so they are not the default (prod) values!

Normal development process is to work in the dev- checkout path, checking in changes regularly, and when it's stable/complete, pushing the code back to the repository.

The parent ST item for < 2017 work is ST#72731 - with the following version sub-items. You can find all tickets via https://cs.uwaterloo.ca/cscf/research/sub/view.php?account=sc-faculty-recruiting

Version	Description	Release Date	Main Work Item
2.1	Initial CS Version	Aug. 2009	ST#68242
2.2	"cs-info" changes to allow all faculty to review candidates	Nov. 2009	ST#69196
2.3	Workflow improvements	Fall 2010	ST#70154
2.4	Workflow improvements	Fall 2011	ST#74472
2.5	Workflow improvements incl. Uploads by Referees	Fall 2012	ST#80445
2.6	AODA compliance, visual appearance, workflow improvements	Fall 2013	ST#87612
2.7	Workflow improvements	Fall 2014	ST#97002
2.7.1	Workflow improvements	Spring 2015	ST#101147
2.7.2	Workflow improvements	Fall 2015	/ST#102233
2.7.3	Workflow improvements	Fall 2016	/ST#102880
2.7.4	Bug fixes	Fall 2017	/ST#108236
2.7.5	Workflow improvements	Fall 2018	/RT#677720
2.7.6	Workflow improvements	Fall 2019	/RT#951168
2.7.7	Workflow improvements	Fall 2021	/RT#1124261