Table of contents generated with markdown-toc
Advizer is a web-app designed and implemented for the Faculty of Arts and Sciences at the American University of Beirut (AUB). It is a tool that evaluates AUB student transcripts against any set of requirements provided by the user. Although it was implemented in coordination with the Students Services Office at FAS, its applicability spans across all AUB faculties and departments. The typical users are internal tranfer committees and academic advisers.
Advizer is designed to be independent from AUB's internal system. It does not require access to AUB records. All the input necessary for any evaluation is provided directly by the user.
The following terms are used across the application:
A Program
represents a major at AUB. Examples include Computer Science, Physics, Biology, etc...
A Plan
represents a grouping for a set of requirements. Each Program
contains a set of plans.
For example, within the Computer Science program, we can have Graduation Requirements (2019-2020), Transfer Requirement (2019-2020), Graduation Requirements (2020-2021), Transfer Requirement (2020-2021), etc...
A Requirement
is a single rule that is taken from the AUB catalog and rewritten in Advizer terms. Each Requirement
has three fields:
title
— a meaningful title provided by the user (required)description
— usually being the catalog's wording copied as-is (optional)rule
— the equivalent form of the catalog's wording written in Advizer's context-free language (required)
Requirements are at the heart of the application. A Requirement
is valid if, and only if, it has a title
and a rule
AND the rule
is written in valid syntax.
As mentioned earlier, the rule
within a Requirement
must be written in valid Advizer syntax.
To achieve its goal of independence from the AUB system, Advizer has its own custom context-free language that is designed to transform any university requirement into syntax that can be interpreted into evaluation criteria for any given transcript.
For the same purpose also, transcripts are not acquired from AUB through any API. They are expected to be provided by the user. Users are expected to either download the unofficial transcripts as .html files to be uploaded to the tool, or copy & paste the page source of the unofficial transcripts.
With these notes in mind, this is how Advizer works:
- The user creates a set of programs
- Within each
Program
, the user creates a set of plans - Within each
Plan
, the user creates a set of rquirements corresponding to thatPlan
- On the Evaluation Tool page, the user provides at least one transcript, and at least one
Plan
and runs the evaluation - Evaluation results are considered unsaved applications with an
Application
representing the evaluation of one transcript against one set of requirements - Users are free to select and save as many applications to the database or simply view and discard them
The language implemented for Advizer allows the user to represent requirements as functions with parameters.
The specific syntax rules ensures that requirements can be processed for transcript evaluation. These rules, referred to as the grammar, decide whether the syntax used is legal or not. Users cannot save a requirement with invalid syntax.
All requirements are represented as Boolean expressions that evaluate to true
of false
. Each expression includes a function. Most functions require a course-set to be its parameter.
With these notes in mind, the grammar can roughly be represented as three layers. Following are these layers starting from the lowest level:
As mentioned earlier, most functions require a cours-set to be passed as a parameter. There are two types of course sets:
Before discussing course sets, note that a course is defined as:
subject code
where thesubject
can either be an AUB course subject likeCMPS, ENGL, ARAB, etc...
or the keywordallsub
which stands for "all subjects".
Provides a range that can be resolved to any number of courses. This range can either be:
- A single course
- ex:
cmps 200
- ex:
- A list of courses separated by commas
- ex:
cmps 200, cmps 212, nfsc 221
- ex:
- A range of course codes belonging to the same subject
- ex:
cmps 200-212
(Any cmps course with the code between200
and212
inclusive)
- ex:
- A range in the format
subject op code
op
is any of the following operators:>
,>=
,<
,<=
,==
,!=
- ex:
cmps >= 230
- Any combination of the preceding formats separated by commas
- ex:
cmps 200, cmps 210-212, cmps >= 230
- ex:
This is a subset of the Ranged Course Set. A fixed course set is simply one or more courses separated by commas.
Within Advizer's language, a requirement is represented as a function. Following are the supported functions:
- Checks if the grade of each course within a provided course-set meets a given range
- Written in the form:
grade[fcs] op LG
such that:fcs
stands for fixed course-setop
is one of the following operators:>
,>=
,==
LG
is a letter grade ranging fromD-
toA+
(case insensitive)
- Example:
grade[cmps 200, cmps 212] >= B
is equivalent to: "the grade of each of cmps 200 and cmps 212 is greater than or equal to B"
Note that the grade P is not a technically counted as a grade. When compared, it can be considered both greater than and equal to any other grade. Thus, if the transcript lists the grade of CMPS 200 as "P" and the rule is
grade[cmps 200] >= B
the expression will evaluate totrue
.
- Checks if each of the courses within a provided course-set has been completed
- Written in the form:
hasTaken[fcs]
such that:fcs
stands for fixed course-set
- Example:
hasTaken[cmps 200, cmps 212]
Note that
hasTaken[fcs]
is equivalent to writinggrade[fcs] >= D
- Checks if the grade of
x
number of courses within a provided course-set meets a given range - Written in the form:
gradeAny[x][cs] op LG
such that:x
is any positive integercs
is a course-set that represents a range of courses (more on its syntax later)op
is one of the following operators:>
,>=
,==
LG
is a letter grade ranging fromD-
toA+
(case insensitive)
- Example:
gradeAny[2][cmps] >= B
is equivalent to: "the grade of at least 2 courses of the subject CMPS is greater than or equal to B"
- Checks if a given number of courses within a provided course-set have been completed
- Written in the form:
hasTaken[x][cs]
such that:cs
stands for course set
- Example:
hasTakenAny[2][cmps >= 230]
Note that
hasTakenAny[x][cs]
is equivalent to writinggradeAny[x][cs] >= D
- Checks if the average of a provided course-set meets a given range
- If the no courses on the transcript are within the provided course-set, the evaluation resolves to
true
- The semantics of this function can be written as "if these courses are taken, there average should be..." - Courses with a P/NP grade or with a repeat status A are not included in the average computation
- Written in the form:
avg[cs] op x
such that:cs
is a course-set that represents a range of courses (more on its syntax later)op
is one of the following operators:>
,>=
,==
x
is a positive number in the range [0.00-4.00] or [40.00-100.00] (decimals are optional)
- Checks if the GPA on a transcript meets a given range
- Written in the form:
gpa op x
such that:op
is one of the following operators:>
,>=
,==
x
is a positive number in the range [0.00-4.00] or [40.00-100.00] (decimals are optional)
- Checks if the student has completed a given number of credits
- Written in the form:
hasTakenCrd[x]
such that:x
is any positive integer
- Used when the catalog requirement requires human interaction or when the current syntax is not capable of representing the requirement
- Written in the form:
manualCheck[comment]
such that:- A
comment
must be surrounded by either double quotes"
or single quotes'
- A
- The output of this expression is always
null
(neithertrue
norfalse
)
The language supports the three fundamental Boolean operators: and
, or
, & not
.
Any number of expressions written with the functions listed above can be combined into a single expression using or
& and
; or it can be negated using not
.
The order of precedence of the Boolean operators is as follows: not
> and
> or
.
In other words if we have the scenario exp1 or exp2 and exp3
, then exp2 and exp3
will be evaluated first.
The language supports parenthesis and they override the order of precendence. For example, if we have the scenario (exp1 or exp2) and exp3
, then exp1 or exp2
will be evaluated first.
The Evaluation Tool page has one main form with three input fields:
- The plans to be used in the evaluation
- The transcripts to be evaluated (.html file or direct input of html code)
- The list of acceptable GE Courses for the current evaluation (.csv files only)
All three input fields can take multiple values (multiple plans, multiple transcripts, and multiple GE courses files) at once.
There are two modes of evaluation:
In this mode, each of the selected plan is used separately to evaluate each of the provided transcripts.
When this mode of evaluation is chosen, the total number of applications created is the product of the number of transcripts and the number of plans selected.
In this mode, all the selected plans have their requirements merged into a single list, and that list of requirements is used to evaluate each of the provided transcripts.
When this mode of evaluation is chosen, the total number of applications created is the same as the number of transcripts provided; regardless of how many plans are merged together.
Upon selecting evaluation plans, the 'Requirements Set Table' will be filled with a list of requirements that are either grouped or presented as a single list depending on the evaluation mode.
Regardless of the evaluation mode, the user is able to select/deselect any number of the requirements in the list. Only the selected requirements are used in the evaluation.
The button to toggle between evaluation modes is found at the top right of the Requirements Set Table.
The evaluation of a transcript against a set of requirements is referred to as an application. Applications are not automatically saved upon evaluation. Users can select any number of the resulting applications to be stored in their account.
Upon saving an evaluation result, the following process occurs in order:
- An
Application ID
is computed using information about the applicant, the selected program, the selected plan, the selected requirements. - If the resulting ID is found in the database, then the found record is updated with the new evaluation results and the
final decision
field is reset topending
- Otherwise, a new application is created with the corresponding data and the
final decision
field set topending
- Once an application is created, it is encrypted using a 256-bit key that is uniquely generated for each user and never shared with the server, and then saved encrypted in the database.
Note here that applications are only accessible to their originator (even the system's admin cannot decrypt these records as they are treated as private information since they contain student names, desired major, and course grades).
Because the encryption/decryption key is only accessible to the user, resetting a forgotten password will lead to deleting the stored applications. This is by design to protect private information. The programs and plans will not be affected.
Each application, saved or unsaved, is viewable in a popup window. If the application is already saved, the top-right button allows viewing it in its own window. Otherwise, the top-right button is used to save the application.
There are four main sections in this page:
This section has to parts: the summary cards, and the detailed evaluation tree.
The evaluation shows the selected requirements with an icon representing one of the three states of requirements' evaluation:
- Satisfied ✅
- Unsatisfied ❌
- Undecided ❓
Requirements that are formulated as a conjunction of multiple functions, are expandable to show the evaluation result of each underlying component to accurately convey the root cause behind the final verdict.
This section contains details about the transcript and the plan. The student's name and ID are extracted automatically from the HTML transcript uploaded.
Details about the evaluation mode and the chosen plan are viewable below the applicant's details. Evaluation mode will either be Merged Requirements
or Separate Plans
.
The title of the selected plan will always be N/A
if the evaluation mode is Merged Requirements
.
If the evaluation mode is Separate Plans
there are two cases for the plan's title displayed:
- If one or more of the plan's requirements are deselected, then the plan's title is appended with the suffix: "(customized)"
- If all the plan's requirements were selected, the plan's title is displayed as-is
Evaluation result is the computed result by the evaluation tool. It has three possible values: incomplete
, complete
, and undecided
. The value cannot be changed manually by the user.
Final decision ****is the ultimate decision, made by the user, regarding the given application. It was established to override evaluation results in exceptional cases, and to give a final verdict when the evaluation result is undecided
.
There are four settings to control how evaluation results are displayed. All settings are on by default.
-
Collapsed view:
When off, expands the entire evaluation tree
When on, restores the evaluation tree to its previous state of expanded & collapsed items
-
Fewer ticks:
When off, displays the icon of the evaluation result for every line.
When on, displays icons only at the highest and lowest levels of the evaluation tree only
Sometimes showing all icons when several requirements are expanded leads to a confusing view
-
Minimal details:
When off, shows comments for every single evaluation result.
When on, comments for unsatisfied requirements only are shown.
-
Display titles:
When off, shows the requirement's rule at the root level as well as the sublevels (if any)
When on, shows the requirement's title at the root level, and rules at the sublevels (if any)