The features and normal method of operation for the project assignment website are documented here in this tutorial. The project assigment process work flow for a module/course is boken into the following stages:
- Creating the moduling using the admin interface
- Stage 0 : Configuring the project form, defining lecturer- and reviewer memberships.
- Stage 1 : Project entry and review
- Stage 2 : no longer used since the review and project entry stages are now merged
- Stage 3 : lecturers can specify student reservations for their projects.
- Stage 4 : project reservation confirmation from students.
- Stage 5 : students make their project selections
- Stage 6 : project allocation optimization
A brief tutorial is given, which covers all these stages. The majority of the work entail use of the project assignment website hosted at https://mecheng.up.ac.za Its also required that you use 3 personal email address, as dummy values for lecturers, reviewers and students so that you get a feel of what each type of user experiences when they use the website.
The project allocation process is designed to be controled from module administration page. This page, which is located under https://mecheng.up.ac.za/modules/, is where the administion of a project allocation / selection process take place. The module administration page does almost everything, please avoid using the Django admin interface unless otherwise instructed to do so in these docs. Incorrect usage of the Django admin page can cause serious damage.
From https://mecheng.up.ac.za/admin admin interface create a new module. The module field description, and values used in this tutorial are given in the following table:
| Field | Tutorial value | Description |
|---|---|---|
| Code | TP101 | The code for the module. i.e. the code for Mechanical Engineerigns Research Project is MSC412 |
| LongName | Tutorial Module | i.e. Research Project (2012) |
| Stage | 0 | Leave at 0, this value can be manually edited should it be desired that the stage be rolled back |
| Minimum number of projects for each lecturer | 3 | The default no. of projects which is requested for each lecturer to enter on system |
| Workload is no. of student and not no. of projects based. | Yes | In this tutorial, lecturers will be asked to create projects accomdate 3 students. |
| Minimum number of project choices per student | 5 | Students will be asked to selected at least this number of projects |
| Default Maximum students per project | 2 | |
| Maximum Maximum students per project | 3 | Prohit lecuters creating a project for more than 3 students can be allocated to |
With module created, proceed to module administration page under https://mecheng.up.ac.za/modules/ to proceed.
Beware be very careful when using the django admin interface, as if used incorrectly or malicously, the interface can destroy or corrupt data. If data munipulation is required, first check the module administration page https://mecheng.up.ac.za/modules/ for a solution before visiting the Django admin interface.
Often, its required that a facaulty member be involved in the project assignment process who is ignorant of the full details of how the website works. Its strongly recommended, that such a users should be added as non-staff, as to prevent them logging into the Django admin interface and damaging data accidently. To add such a module admin, use the Django admin interface https://mecheng.up.ac.za/admin to add a user (by default staff status should be turned off ). The email address of a user is very important, as all email communication he/she does on the website will use this email value for the From field.
From the TP101 - Tutorial Module admistration page located under https://mecheng.up.ac.za/modules/ , the stage 0 actions are available.
The project assignment website allows for module specific project forms. The forms layout needs to set using the Django admin interface. Follow the link on the administer module page under the Actions to edit the module definition
The various options available for the project entry form, are illustrated using the project entry form for the TP101 - Tutorial Module as an example. Under the module fields grouping, in the admin interface, the follow values are used
| Description | InputType | [Interger field] max_value, min_value [text/char field] max length | WidgetAttrs | Initial Value, OR comma seperated choices | LongDescription |
|---|---|---|---|---|---|
| Description | textArea | 3000 | cols=180 | Background, objectives, deadlines ... | Project Description |
| Category | ChoiceField | aeronautical, mechanical | |||
| Funding | IntegerField | 50000,0 | 0 | Funding available for experiments |
Save the data, then follow the Return to the website’s index. at the bottom of Django Admin page, as to quickly return to module adminstration page. Finally admire and test out your handiwork, using the preview project form link under the actions heading.
hint : A fast way of setting up and testing the project entry form is to use two browsers, each occupying different halves for the screen. Through the one browser edit the module fields, then hit save and continue editing, and from the other browser preview the new project form by refereshing it on the project form preview page.
Do not change the description field values, and input types past stage 0, as this will result in data loss and funky behaviour. For this reason, the preview project form link does not require authentication, allowing all involved staff to view and check the project entry form in stage 0. Thereby hopefully avoiding the need for late alterations.
CSV files should be used to define/update Lecturer, Student and Reviewer mememberships. Its advisable to download the template, and put the required information in to that template. After the CSV membership file is ready, use the links on the module administration page to update the memembership information on the website database.
Depending on the CSV type extra fields can be defined, as to influence certian aspects of the project assignment. In this tutorial, the following lecturer membership file is used
| title | initials | lastName | contactNo | picture | website | projectsRequired | |
|---|---|---|---|---|---|---|---|
| EmailField | CharField | CharField | CharField | CharField | URLField | URLField | IntegerField |
| ${personal_email_1} | Mr | A | Tree | 3 | |||
| ${personal_email_2} | Prof | B | Smart | 5 |
The reviewer mememberships for this tutorial are
| title | initials | lastName | contactNo | picture | website | Category | |
|---|---|---|---|---|---|---|---|
| EmailField | CharField | CharField | CharField | CharField | URLField | URLField | CharField |
| ${personal_email_2} | aeronautical | ||||||
| ${personal_email_3} | Ms | C | Yew | mechanical |
When Lecturers submit a project for review, the reviewer allocation scheme is used to assign a reviewer to the project. For this tutorial, following the specify reviewer allocation scheme link in the Module admin page will give two options
- All reviewers review each project</option>
- when reviewer and project match on ‘Category’
Select the second option for the purposes of this toturial. After the reviewer sheme is set, the option to intiate Stage 1 become available. Initiate stage 1, to proceed.
Cc email option use plain email address speration commas for this fields ie : bob.smith@bogus.emai, lee.smith@bogus.emai
To initiate stage 1, an email is sent out to all the lecturers to let them know that can enter projects. Since in this tutorial your personal email address have been used, you should these recieve emails which the lecturers will normally recieve. Follow the email links, and try out the system from a lecturers view point. Similary, send out emails to the reviewers, and log in as a reviewer and have a look around.
Once enough project are approved, initiate the project reservation stage. However, before you can do this the student memberships need to be defined. The student memberships used in this tutorial are
| studentID | title | initials | lastName | contactNo | picture | webpage | course | gradeAverage | |
|---|---|---|---|---|---|---|---|---|---|
| CharField | CharField | CharField | CharField | CharField | CharField | URLField | URLField | CharField | Integerfield |
| ${personal_email_1} | u1 | Mr | G | Hill | aeronautical | 70 | |||
| ${personal_email_2} | u3 | Mr | Z | Tree | mechanical | 40 | |||
| ${personal_email_3} | u2 | Mr | A | Figure | mechanical | 90 |
During this stage the Lecturers can specify if they would a project spot reserved for a particular student. Login as a lecturer as add a reservation. Error trapping here prevents both projects from being oversubscribed and a student from being assigned to multiple projects.
This stage allows students the oppertunity to cancel a reservation, in the case there has been a misunderstanding with the lecturer. After this stage, all the students who are not already assigned to a project will be allowed to specify their project choice. If may some time occur that advanced project selection rules are required:
By default students are allowed to select every project. However, in the past some modules have required specialized selection rules. To setup project selection rules, follow the edit module definition under the general action heading on the module administration page. Then add selection rules in the Selection rule grouping.
For this tutorial, we want to restrict aeronatical students on only selecting aeronatical projects. At the same time, mechanical students should be allowed to select both mechanical and aeronatical projects. For the membership and project definition used in this tutorial, these selection rules are achieved using the follow selection rule entrys
| Object1 | Attribute1 | LogicalOperator | Object2 | Attribute2 | Action |
|---|---|---|---|---|---|
| studentMembership | course | equals | constant | aeronautical | and next rule is satified |
| studentMembership | course | in not equal to | project | Category | then invalid selection |
In order to verfiy that the selection rules work, a check is done when follow the initializing the student selection stage link.
Students who have do not have projects reserved can now login to make there selections. Again the primary tool for communicating and chasing students is email. Once sufficient time has passed, and enough students have made the required number of selections the optimization stage can commence.
It may occur that a couple of students are delaying the whole process. In this event go to the optimization stage and allocate projects to rest of the students, then either
- edit the module difinition as to roll the project stage back to 5. Students which have been allocated to projects during the optimization stage are now treated as student which have a project reserved. or
- use the edit project assigments link under the general heading on the module admin page as to allocate the late students to projects directly.
The project allocation can be formulated as an optimization problem, with the objective of maximizing everyones happiness. Note that since the gradeAverage column was defined in the student CSV file, the is option to use it an unhapiness multiplier when downloading the optimization files. Download the optimization files, do the optimization then upload the results. Close the optimization.
Then email the students and lecturers. There login links will take them to their homepage, which will now show them the project allocation results.