State Machine

You can think of the CoGS application as a kind of state machine, where each rotation goes through the following series of state transitions from being created to being completed.

NB: this depiction of the state machine is correct as of commit 12f814b (there have been some significant changes since then; refer to the source for details).

API call: users.create

• adds a new User to the database

API call: rotations.create

• adds a new ProjectGroup (i.e. a rotation) to the database
  • not student_viewable
  • not student_choosable
  • not student_uploadable
  • not can_finalise
  • not read_only
• mails all users with permission create_project (i.e. supervisors): supervisor_invite_{group.part}
• schedules the group deadlines:
  • supervisor_submit
  • student_invite
  • student_choice
  • student_complete
  • marking_complete

API call: projects.create

• fails if the rotation is read_only (i.e. after student_choice)
• adds a new Project to the database
• if the project has been pre-assigned to a student, sets that student's first_option to the new project

Deadline: supervisor_submit

• mails all users with permission create_project_groups (i.e. the Graduate Office): supervisor_submit_grad_office

Deadline: student_invite

• sets the latest rotation to be:
  • student_viewable
  • student_choosable
• mails all users with permission join_projects (i.e. students): student_invite_{group.part}

API call: users.vote

• fails if the user does not have permission join_projects (i.e. is not a student)
• fails if the project is already assigned to a student
• fails if the project belongs to the 3rd rotation and picking the project would mean that the student has not done any wetlab projects or any computational projects
• sets first_option, second_option, or third_option attribute on the user

Deadline: student_choice

• sets the latest rotation to be:
  • not student_choosable
  • student_uploadable
  • can_finalise
  • read_only
• mails all users with permission set_readonly (i.e. the Graduate Office): can_set_projects

API call: users.assign_projects

• fails if the user does not have permission view_all_submitted_projects (i.e. is not a Graduate Office member)
• unassigns students from all projects in the latest rotation
• reassigns students to projects as specified in the request

API call: users.unset_votes

• sets the latest rotation to be:
  • not student_choosable
  • student_uploadable
  • not can_finalise
• adds to each assigned student's priority (priority += 2^n-1-1, where n is the choice the student was assigned to, or 4 if none of the student's first 3 choices were selected)
• unsets first_option, second_option and third_option attributes on each student
• mails all students assigned to a project: project_selected_student
• mails all users with permission create_projects (i.e. supervisors):
  • all supervisors receive supervisor_student_project_list
  • supervisors who have created projects receive project_selected_supervisor

API call: projects.upload

• fails if the user is not the student assigned to the project
• fails if the project's grace period has passed
• saves the uploaded file to uploads/{student_id}/{series}_{part}_{project_id}.zip
  • if the uploaded file is too large and the project had been uploaded already, the existing file is partially overwritten
• if this is the first time the project has been uploaded:
  • sets project.uploaded
  • unsets project.grace_passed
  • if the project belongs to rotation 1 or 3, schedules grace_deadline for student_complete plus 3 days
  • if the project belongs to rotation 2, schedules grace_deadline for student_complete plus 1 day
  • if the project has no CoGS marker assigned:
    • mails all users with permission create_project_groups (i.e. the Graduate Office): cogs_not_found

Deadline: student_complete

• performs no action

Scheduled event: grace_deadline

• sets project.grace_passed
• mails the project's supervisor and CoGS marker (if they exist): student_uploaded
• schedules mark_project

API call: projects.mark

• fails if the user is not the project's supervisor or CoGS marker
• fails if the project's grace period has not passed
• fails if this user has already submitted a mark for this project
• adds a new ProjectGrade to the database
• sets the project's supervisor_feedback or cogs_feedback to the new grade
• mails the project's student and all users with permission create_project_groups (i.e. the Graduate Office): feedback_given

Deadline: marking_complete

• performs no action