
# Campus visits requirements document

Prepared by: Michael Kowalczyk  
Revision date: 9/28/2024

## Overview

In the Math and CS Department, the current workflow for campus visits works as follows.
 1. The department secretary receives a campus visit request from the campus visit office.
 1. The secretary sends an email to the computer science professors asking if someone could take the visit.  Information pertaining to the visit is included in this email (prospective student's name, anticipated major, hometown, date of visit, and possible times that could be scheduled that day).
 1. Professors email back saying that they can take the visit (or not) and at what time.

The main problem is with the last step.  Professors will often delay in responding, for a variety of reasons.  For example:
 - A professor might be *technically* available for a certain day, but it would be hectic to fit it in so they would rather someone else take that one.
 - Professors might delay in responding, reasoning that if they delay then someone else will take it.
 - A professor might not be able to take the visit, but won't actually respond saying so.

This results in the secretary having to send multiple emails asking for someone to take the visit, and/or the CS chair polling the secretary to see if a visit is taken yet.  When an incoming student doesn't know if they will be meeting with a professor it sets a bad impression, especially for those who travel great distances for the campus visit. 

## System expectations

We would like a system to address the following:

- There should be some way of encouraging a balance between the number of visits assigned to various professors (perhaps there should be a record of number of visits taken, etc.)
- We expect a quick turnaround time, so that the student has confirmation of which professor they are meeting with in, say, within a few days of the visit info coming to the department secretary.
- The system should eliminate the need for the secretary to nag and for the CS chair to keep polling to see if visits are taken or not.
- Address the "social loafing" problem by managing better communication between the professors (for example, some quick and convenient way of expressing "I can do this visit if nobody else is available, but I would rather not").  The system may take this information into account when sending auto-notifications to the faculty.

## Entities

- User
    - *Name* - person's name
    - *Email* - email address used for login and notifications
    - *Password* - for logging into the web portal
    - *Roles* - zero or more of these options: coordinator, admin, or faculty.
        - *coordinator* - communicates with the CV office and communicates with faculty to determine who is doing a visit
        - *Admin* - has superuser priviledges, such as creating and deleting users.
        - *Faculty* - a user who can do campus visits for Computer Science.
    - *Available times* - (for faculty only) a weekly schedule of regularly available times for campus visits
- Visit
    - *Possible times* - a list of time intervals in which the visitors are available on the visit day
    - *Day* - the calendar day for which the visit has been scheduled with the campus visit office 
    - *DecidedTime* - the time at which the faculty member has agreed to meet for this visit
    - *DecidedGuide* - the faculty member who has agreed to conduct this visit
    - *Status* - the current status of this visit:
        - *proposed* - the visit is known to the department, but no faculty is assigned
        - *assigned* - a faculty member has agreed to do the visit at a *decided time*
        - *confirmed* - the secretary has informed the Campus Visit office of the *decidedGuide* and *decidedTime*
        - *completed* - the *decidedGuide* has conducted the visit
        - *canceled* - the visit has been canceled before it could be conducted
    - *Notes* - other information pertaining to the visit that would be useful to the *decidedGuide*
- Visitor
    - *Name* - actual name
    - *Role* - the type of visitor: prospective student, parent, or guest (other).
    - *Antipicated start semester* - the start semester, as reported by the CV office
    - *Antipicated majors, minors* - desired major(s) and minor(s), from the CV office
    - *Type* - category (for prospective students only): high school, transfer, or non-traditional
    - *Hometown* - name of city and state of origin
- Committment - the level of committment associated with a given faculty member for a particular visit 
    - *Level* - possible values for involvement are: unknown, cannot, prefer not, can do

![UML Diagram](entityRelationships.png "Entity relations")

## Queries

Unless stated otherwise, these queries can be performed by any user.

- **Q1** - List visits.  *Parameters: startDate, endDate, assignedFaculty, currentStatus* (any or all of these can be omitted, and assignedFaculty may be "none" to search for unassigned visits).  *Result:* For each visit matching all of the parameters given: list student name(s), day, possibleTimes, decidedTime, decidedGuide, and status.  Sorted by visit day.
- **Q2** - View visit.  *Parameters: visitID*.  View all attributes for the given visit, and also the associated committment level for each faculty member in the system.
- **Q3** - View faculty stats.  *Parameters: startDate, endDate*.  For each faculty *f*, list the number of visits *v* for which *v.decidedGuide = f* and also the number of visits *v* for which *v.decidedGuide = f* and *v.status = completed*.  For both of these sums, the visits are restricted to *startDate <= v.day <= endDate*.
- **Q4** - List users.  *Parameters: none*.  This query is available for *admin* and *coordinator* only.  For each user *u* in the system, list *u.name, u.roles, u.availableTimes* (if *u.roles* includes *faculty*), and *email*.

## Events

There are a few problem domain events of interest.  For each of these a source is listed, which is how this event is made known to the system.
- *VisitRequest* - the Campus Visit office contacts the department secretary with information pertaining to a new campus visit.  *Parameters*: date, possible times, student name, other visitor names, and majors/minors of interest.  *Source:* department secretary keys in the data (coordinator role).
- *ClaimVisit* - a faculty member decides to do a visit.  *Parameters*: visit, decidedGuide, decidedTime.  *Source:* faculty member or coordinator.  NOTE: If the coordinator claims a visit for a faculty member, then the faculty member must receive a notification (unlike the case where a faculty member claims a visit for himself).
- *ConfirmVisit* - the department secretary contacts the Campus Visit office that someone has taken the visit.  Parameters: visit's *decidedGuide* and *decided time*.  *Source:* department secretary (coordinator role).
- *CancelVisit* - the campus visit office notifies the department secretary that the visit has been cancelled by the student.  *Parameters:* Visit.  *Source:* department secretary (coordinator role).
- *AbaondonVisit* - some circumstance has caused the faculty member to vacate the guide position for a visit.   *Parameters:* Visit.  *Source:* faculty member.
- *VisitTimePassed* - the *decidedTime* for the visit plus an hour has passed in Eastern Time; the visit is assumed to be completed.
- *AdjustNotificationFrequency* - *Parameters:* Visit, numberOfDays.  Sets the frequency for periodic notifications to the given number of days.  *Source:* department secretary (coordinator role)
- *SetCommittmentLevel* - a faculty member sets (or clears) their committment level for a particular visit.  *Parameters:* faculty, visit, level.  *Source:* faculty.  Invariant: The committment level must always be "can do" for the assigned guide, if any.
- *EditAvailableTimes* - *Parameters:* faculty, subset of daytime hours for each weekday.  Sets the available times for that faculty member.
- *CreateUser* - *Parameters:* name, email, password, roles.
- *EditUser* - *Parameters:* user, plus one or more of: name, email, password, roles.
- *ChangePassword* - *Parameters:* user, password.
- *SetEmailLinkTimeout* - *Parameters:* numberOfDays.  Indicates the number of days which email links remain active, after which the link gives an error message.

![UML Diagram](eventsAndVisitStates.png "Event sequences")

## Notifications

**R1** - The system notifies faculty via email under any of the following circumstances:
- A new *visitRequest* is made
- The faculty member is the *decidedGuide* for a visit which is scheduled for tomorrow
- Periodic reminders for faculty members who have an unknown committment level for one or more proposed visits.

**R2** - The system notifies coordinators via email under any of the following circumstances:
- Periodic reminders for visits that are in the *proposed* state.
- A time conflict has been detected between two different visits.

**R3** - Both faculty and coordinators are notified if a faculty member has claimed or abandoned a visit (except for a faculty member who changed his own status)

## Platform
**R4** - All users can log into the system as a web app to perform actions suitable to their role(s).

**R5** - Notifications are delivered via email, with embedded unguessable links so that likely actions pertaining to the notification can be performed in one click without logging in.

## User permissions
Users act in different roles with regard to editing the system's internal model of campus visits.  

| Event                        | Coordinator | Faculty | Admin |
| ---------------------------- | :---------: | :-----: | :---: |
| VisitRequest                 |      ✔      |         |       |
| ClaimVisit                   |      ✔*     |    ✔    |       |
| ConfirmVisit                 |      ✔      |         |       |
| CancelVisit                  |      ✔      |         |       |
| AbaondonVisit                |      ✔*     |    ✔    |       |
| VisitTimePassed (automatic)  |             |         |       |
| AdjustNotificationFrequency  |      ✔      |         |       |
| SetCommittmentLevel          |      ✔*     |     ✔   |       |
| EditAvailableTimes           |      ✔*     |     ✔   |       |
| CreateUser                   |             |         |   ✔   |
| EditUser                     |             |         |   ✔   |
| ChangePassword               |      ✔      |     ✔   |   ✔+  |
| SetEmailLinkTimeout          |             |         |   ✔    |

Legend:  
✔ = The action is allowed by this user role.  
✔* = The action can be performed by the coordinator, acting on behalf of a faculty member.  
✔+ = The admin can change any user's password (other users can only change their own).

## Security
**R6** - The web app portal is password-protected and served over HTTPS, exclusively.

**R7** - Embedded email links pertaining to user actions are long, unguessable strings which expire after a certain number of days (which can be set by an admin).  Following an expired link shows an error message.

## Preferences
Unnecessary email should be minimized.  Within notification frequency, it would be preferable to have a single email containing notifications for all relevant visits rather than receiving a separate email for each notification.

## Likely changes
Rules guiding notification frequency are likely to change.  The coordinator has limited control over this, but experience with the system will help to understand how to best give the coordinator more granular control.
