CSC/ECE 517 Spring 2022 - E2243. Refactor student teams functionality

This page contains information about Expertiza Issue E2243. Refactor student teams functionality which was a project in CSC517 Spring 2022.

Please see below for a description of the design of the project.

Background

The Expertiza project is software to create reusable learning objects through peer review. It also supports team projects, and the submission of almost any document type, including URLs and wiki pages.

Users & Participants: Everyone who took the CSC517 OODD class at NC State is a user in Expertiza, and instructors can add users as participants in an assignment so that they can access it to contribute, make changes and submit their work to be graded.

Almost all of the works within Assignments is done by participants, not users. All the tables use participant_id to track contributions to assignments, except teams_users. In the documentation, it can be noted that the team_users table references users instead of participants. This anomaly in the teams_users relation causes problems with how student teams are rendered in the UI, and it doesn’t mix well with the new functionality that was recently introduced. The participant_id field should be added to the model, and references that use user_id should also incorporate participant_id. Ideally, the application should use only participant_id, but to handle the existing data in the database without running a massive migration, the application should be able to handle both old records that use user_id and new ones that shall, from after this project is completed, use participant_id instead.

Requirements

Changing the schema

• Create a column that would be called “participant_id”, which will be a foreign key that references the participants table.
• Use this participant_id field in all operations for teams going forward. There are a number of workflows involving teams we have examined and worked on, which are elaborated below.
• However, it is to be noted that this must also work with the existing functionality and data which makes use of user_id, so the code written must take both into account in its working.

Refactoring the teams rendering (/views/student_teams/view.html.erb)

The logic in the team's view (where participants can see their team members) that iterates and fetches information of all the team members and displays them would be refactored as this view is quite bloated and has lots of functionalities written on it. We have made partials and placed those functionality in their specific partials.

Other Changes

Updated logic for all the CRUD functionalities in teams_users controller (wherever applicable).

Fixed tests to incorporate the new logic as a result of using both user_id and participant_id in the teams_user logic.

Schema Changes

In teams_users table, we can add a new column participant_id which is a foreign key from participants table and remove the column user_id. We plan to remove the user_id column only after data migration since the user_id field is used predominantly in several other controllers in a variety of ways, and as such its removal must be done carefully.

The participant_id field in the the teams_users relation is computed as follows:

• Finding Assignment ID By Team ID

The teams_users table contains team_id, user_id and duty_id but not the participant_id. Since the same user_id can be associated with multiple participant_ids (since the same user can participate in multiple assignments and gets a unique participant_id in each assignment they take part in), we need to get the user_ids in the assignment for which we need the particular user's participant_id. For this reason, we need to first find the assignment_id.

• Finding Participant ID By Assignment ID and User ID

With the assignment_id retrieved, we can find the list of participant_ids that participated in the assignment, and using the user_id, get the participant_id which is saved in the participants table.

ER diagram for updated schema

Implementation

Main files which were changed are

• app/models/participant.rb
• app/models/team.rb
• app/models/teams_user.rb
• app/models/user.rb

As the project tries to introduce participant_id as a replacement of user_id, we've calculated all the details with both user_id and participant_id (whichever is available based on whether the data is old or new). We've also added comments everywhere to show the code snippets which need to be removed once user_id is deprecated. (Check for comments with #E2243)

Currently teams_user table has user_id or participant_id for now. So we've ensured that checks happen based on both the IDs unless user_id is removed. The default check is overridden to ensure newer datas which only have participant_id are also indexed and found using the function call here.

Code Snippet

TeamsUser.where(user_id: user_id).or(TeamsUser.where(participant_id: participant_id))

find_by_team_id_and_user_id

.where function makes a lot of DB calls when asked for user_id, we've introduced a module called "find_by_team_id_and_user_id()" which will override .where function. If user_id is not present in the table, it loads based on participant_id instead, as you can have only one as the key and not both.

So wherever .where is used,

TeamsUser.where('team_id = ? and user_id = ?', @team.id, @user.id), 

we've replaced it with

TeamsUser.find_by_team_id_and_user_id(@team.id, @user.id). 

This way instead of changing the query for every call, we've used a single function for all the calls, thereby implementing DRY principle.

add_participant_to_team

The existing function to add a member

add_member(user,team.parent_id)

adds user to a team based on the user_id and team_id.

We've introduced a new function called

add_participant_to_team(student, team.parent_id)

which adds participant(student) to a team based on participant_id(or user_id wherever participant_id is not available)

This function takes participant and team_id, and assigns that participant to a team. In future, once user_id is removed, add_participant_to_team can be used as a replacement.

Analysis

user_id exists as a foreign key in 2 relations - Participants and teams_users. Although they crrespond to same attribute, user_id alone cannot be used to find corresponding Participants because same user_id can exist for multiple Participants - due to Expertiza's design wherein for every assignment, every user is added to participant's table. Therefore Participant ID can be mapped to (assignment_id, user_id) pair.

View Changes and Refactoring

One of the requirements in E2243 is the refactoring of the student teams view in views/student_teams/view.html.erb

This view is quite cluttered and as a result, makes editing, understanding and extension difficult and tiresome for any future updates to the expertiza application. The code in this file can be modularized to obtain simpler and easier-to-understand, which is what we have achieved. The view was reafactored to incorporate partials, and some of the partials created as a result are:

• _invited_people.html.erb : partial for displaying the invited participants to the assignment team
• _display_advertisements.html.erb : partial for displaying advertisements in the view
• _send_invitaions.html.erb : partial for the send invitations functionality
• _received_invitations.html.erb : partial to display the received invitations for the current user

Please see the next sections for some screenshots of the UI related to the above described partials.

Impacted Files

• teams_users_controller.rb (expertiza/app/controller/teams_user_controller.rb)

We will be adding code here to compute the participant_id using the methodologies described above.

• teams_users.rb (expertiza/app/models/teams_user.rb)

The model will be updated (as can be seen in the ER diagram above) to have the participant_id added.

• teams_users(expertiza/app/views/teams_users)

The view will be updated to reflect the new name of the model, and contain new partials that make use of the participant_id field.

• teams_users_controller_spec.rb(expertiza/spec/controllers/teams_users_controller_spec.rb)

The test file for the controller will be modified so that existing test cases pass the new changes, and also introduce new test cases to increase test coverage.

Test Plan

Manual Testing

The changes in teams_users means we need to re-examine the flows and user stories through where teams_users is used. This, in practice, means that we manually have checked the different ways in which a team for an assignment can be created in expertiza, and other associated operations such as removal of a user from a team, addition of a new user, deletion of a team etc. This testing was necessary to ensure that the functionality in expertiza still worked as expected even after our refactoring was completed.

The main user stories we examined are:

1. Student creates a team: A student, newly added to an assignment, opens the application and goes to "my team" after opening the assignment on expertiza. He enters his team's name and the team is created.

2. Student joins a team: A student, is invited to join a team for an assignment, and accepts. He is added to an existing team, possibly created by another student or instructor.

3. Instructor creates a team manually: An instructor who wishes to create a team with certain students on it, chooses the assignment on expertiza, and clicks on the icon to add a new team and in the manual section, creates a new team by giving a team name. They add students or participants to the newly created team and can remove them too.

4. Instructor creates teams automatically: An instructor wishes to assign all the students involved in an assignment randomly to teams of a certain size. They open expertiza, choose the assignment, and then click on the icon to add a new team, and in the "create teams automatically" section, enter the team size they wish to use. The system then creates teams of the specified size, adding students randomly to teams which is reflected in both student and instructor views.

In addition to verifying team creation in all of the above scenarios, we also verified other operations such as addition of a team member after the team capacity was exhausted, deletion and re-addition of the same user, invitations to already existing participants in the same team etc and ensure the system was working as expected in these scenarios as well.

Automated Testing RSpec

Since this is a refactoring project, the scope of testing is limited to the changes made as part of refactoring and also to ensure that the existing test cases do not break or are modified accordingly. In all the existing test cases in expertiza/spec/controllers/teams_users_controller_spec.rb :

• object initialization
• #update_duties
• when user is added to assignment team
• when user is added to assignment team
• when user is added to course team
• when user is already on an assignment team
• when user is added to assignment team while on a team already
• when user is already on a course team

the new methods which use both participant_id and user_id have been incorporated as needed to ensure continued quality of the testing suite and maintenance of code coverage.

Fixed Test Files

After our refactoring, we noticed failing tests in the below files, and we have worked on fixing these to work with the new and updated functionality. The main issues were involving tests using the old methods for creating a team, adding participants to the team etc.

Models:

• spec/models/assignment_team_spec.rb
• spec/models/course_team_spec.rb
• spec/models/invitation_spec.rb
• spec/models/student_task_spec.rb
• spec/models/team_spec.rb

Helper:

• spec/helpers/authorization_helper_spec.rb
• spec/helpers/grades_helper_spec.rb
• spec/helpers/sign_up_sheet_helper_spec.rb

Controllers:

• spec/controllers/assessment360_controller_spec.rb
• spec/controllers/grades_controller_spec.rb
• spec/controllers/join_team_request_controller_spec.rb
• spec/controllers/student_teams_controller_spec.rb
• spec/controllers/lottery_controller_spec.rb
• spec/controllers/sign_up_sheet_controller_spec.rb
• spec/controllers/submitted_content_controller_spec.rb
• spec/controllers/teams_users_controller_spec.rb
• spec/controllers/invitations_controller_spec.rb

Future Scope

1. Create a migration to compute the participant_id field for all the rows in the teams_users table that currently have a user_id field.
2. Remove the user_id column from the teams_users table.
3. Rename the teams_user table to teams_participant so that this better reflects its new functionality and use cases in the system.
4. Modify functions which use user_id and replace them with functions using participant_id only (Note: Look for code comments with #E2243 for all the replacement functions)

Team Members

1. Ashok Kumar Selvam (aselvam@ncsu.edu)
2. Sri Athithya Kruth Babu (sbabu@ncsu.edu)
3. Subramanian Venkataraman (svenka25@ncsu.edu)

Mentor: Naman Shrimali

Code Details

Github Pull Request - https://github.com/expertiza/expertiza/pull/2391

Repo - https://github.com/sak1997/expertiza/tree/beta

Demo - https://drive.google.com/file/d/1zWnHJNgSkioMd_xmB2L-7wPM2_OP7yka/view?usp=sharing