Expertiza_Wiki - User contributions [en]

CSC/ECE 517 Spring 2025 - E2531 Refactor participants controller.rb

2025-04-27T20:00:28Z

Vkdodiya: /* Methods */

=Introduction=
From the project description: "This project aims to refactor the <code>participants_controller.rb</code> and its helper class, <code>participants_helper.rb</code>, in the Expertiza system. The focus will be on improving code structure by implementing DRY and SOLID principles, enhancing readability with meaningful comments and clear naming conventions, and ensuring robustness through comprehensive RSpec testing." Since this is a refactoring project, we will also be utilizing Large Language Models (LLMs) to aid in development. More information on how we used them can be found in the section below.

==Video Overview==

https://youtu.be/4kfz0hrmSg4

Note: In the video it shows the test file at the end, but does not mention a last-minute change that numbers all of the tests to make it much easier to keep track of each of the tests and which ones are passing.

=Use of Large Language Models (LLMs)=

For this project, we are using ChatGPT as an LLM helper in determining what issues there are within the code. The use of LLMs in this project will likely be limited to probing for potential issues that exist within the system.

Below we have organized the following prompts and a summary of the output in a table:

{| class="wikitable" style="margin-left:40px"
|-
! style="width: 25%" | Prompts !! LLM Output Summary
|-
| [Code from <code>participants_controller.rb</code>] Are there any ways where we can refactor the code to improve readability, DRYness, and clarity of error handling?
|| It recognized some of the issues we, as a team, had already identified and suggested fixes that were similar to what we outlined: Redundant JSON Rendering Code[https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2025_-_E2531_Refactor_participants_controller.rb#Simplifying_Redundant_JSON_Rendering_Code] and Simplifying the Assignment of Participant Fields[https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2025_-_E2531_Refactor_participants_controller.rb#Simplifying_the_Assignment_of_Participant_Fields]. Additionally, it suggested minor changes that we could implement, such as using <code>Participant.where(...)</code> instead of <code>Participant.all</code> to filter out the code more efficiently instead of getting all database instances every time, as well as the use of strong parameters in <code>add()</code> and <code>update_authorization()</code> to avoid having to implement custom parsing techniques. It also recommends renaming the <code>add()</code> function to something more specific in relation to its purpose (adding a <code>Participant</code> to an <code>Assignment</code>.
|-
| Potential Redundant Tests in <code>participants_controller_spec.rb</code>
|| The tests on line 222 and 231 are redundant as only the authorization differs. (Note: This should be investigated to see whether or not this is necessary)
|-
| Checking for issues with the current testing files
|| The "Get Participant by ID call" test was returning a 201 status code instead of the more suitable 200 code
|}

For more detailed information on what prompts we used and the output we got, please visit the page here: [https://docs.google.com/document/d/105_U_Coky-edx7n-tFhD2B5RqmVXxEsKPW_qUaf7bQU/edit?usp=sharing].

=Requirements=
Objectives:
<ul>
<li>Apply DRY principles to eliminate redundant code.</li>
<li>Ensure adherence to SOLID principles for better maintainability.</li>
<li>Use appropriate design patterns to optimize code architecture.</li>
<li>Write clear, informative comments and use meaningful naming conventions.</li>
<li>Test the refactored code extensively with RSpec to verify functionality.</li>
</ul>
Deliverables:
<ul>
<li>Refactored code for participants_controller.rb and helper class.</li>
<li>Comprehensive test suite and coverage report.</li>
<li>Updated and detailed documentation.</li>
<li>Video demonstration of the API functionality.</li>
</ul>

==Existing Issues==
<ul>
<li>There are some API functions that are currently not functioning properly, making it somewhat difficult to test</li>
<li>Some API functions are not returning the correct HTML status messages (e.g. test on line 136 returns 201 instead of 200)</li>
<li>Documentation and comments can be somewhat vague</li>
<ul>
<li>In-line comments should be more descriptive, explaining what the code does in more details</li>
<li>Tests are not described via comments, but in name alone; some more descriptive comments that explain the tests in more detail would be ideal</li>
</ul>
<li>Eliminate instances of redundant code</li>
<li>The method naming should be more descriptive</li>

</ul>

=Design / Proposed Solution=

Based on the previous implementation's controller diagram, we have created a new version that contains our proposed changes and modifications to <code>participants_controller.rb</code>.

[[File:Participants_controller_refactor_v1.2.png]]

==Simplifying Redundant JSON Rendering Code==

Many of the functions in the current implementation contain a conditional if-else statement that determines what HTML status code is returned alongside any necessary values that are requested. Due to its simple nature, it might be possible to reduce the amount of space this takes up by implementing a private helper method that would shorten the process.

Example:

<syntaxhighlight lang=ruby line> if participants.nil?
render json: participants.errors, status: :unprocessable_entity
else
render json: participants, status: :ok
end</syntaxhighlight>

==Simplifying the Assignment of Participant Fields==

The <code>add()</code> and <code>update()</code> both take up a significant amount of space to assign values to database fields and are essentially the same in functionality (in terms of this specific section. We can remove redundancy by creating a method that can remove this redundancy.

Example

<syntaxhighlight lang=ruby line> permissions = retrieve_participant_permissions(authorization)

participant.authorization = authorization
participant.can_submit = permissions[:can_submit]
participant.can_review = permissions[:can_review]
participant.can_take_quiz = permissions[:can_take_quiz]
participant.can_mentor = permissions[:can_mentor]</syntaxhighlight>

==Provide More Clarity in Function Names==

There are some functions that are somewhat unclear/vague in <code>participants_controller.rb</code>. For example, the <code>list_user_participants()</code> and <code>list_assignment_participants()</code>.

=== - Suggested Method Name Improvements ===

{| class="wikitable"
! Old Method Name
! New Method Name
! Notes
|-
| <code>list_user_participants</code>
| <code>render_participants_by_user_id</code>
| Clearer and more descriptive
|-
| <code>list_assignment_participants</code>
| <code>render_participants_by_assignment_id</code>
| Clearer and more descriptive and is consistent with the other get method
|-
| <code>add</code>
| <code>add_participant_to_assignment</code>
| Describes both creation and authorization setup of participant to assignment
|-
| <code>filter_user_participants</code>
| <code>filter_participants_by_user</code>
| Highlights the purpose of the method
|-
| <code>filter_assignment_participants</code>
| <code>filter_participants_by_assignment</code>
| Highlights the purpose of the method

|}

==Improve Documentation and Comments==

Some of the documentation and in-line comments can be somewhat vague. This can lead to misconceptions about how some functions work or how some of the code can function. Below are potential improvements we plan to make for function descriptions, though these may change with the final implementation.

=== Improved Method Comments ===

{| class="wikitable"
! Method
! Original Comment
! Refactored Comment
|-
| render_participants_by_user_id
| Return a list of participants for a given user
| Retrieves all participants associated with the specified user ID
|-
| render_participants_by_assignment_id
| Return a list of participants for a given assignment
| Retrieves all participants linked to the specified assignment ID
|-
| show
| Return a specified participant
| Fetch and return the participant with the given ID
|-
| add_participant_to_assignment
| Assign the specified authorization to the participant and add them to an assignment
| Creates a new participant for a given assignment and assigns appropriate authorization and permissions
|-
| update_authorization
| Update the specified participant to the specified authorization
| Updates the participant’s authorization role and related permissions
|-
| destroy
| Delete a participant
| Deletes the participant identified by the given ID and returns a confirmation message
|-
| participant_params
| Permitted parameters for creating a Participant object
| Strong parameters: list of attributes allowed for participant creation or update
|-
| filter_participants_by_user
| Filters participants based on the provided user. Returns participants ordered by their IDs
| Returns a sorted list of participants filtered by user, if provided
|-
| filter_participants_by_assignment
| Filters participants based on the provided assignment. Returns participants ordered by their IDs
| Returns a sorted list of participants filtered by assignment, if provided
|-
| validate_authorization
| Validates that the authorization parameter is present and is one of the following valid authorizations: reader, reviewer, submitter, mentor
| Ensures authorization param is valid and returns it in lowercase; otherwise returns error response
|-
| find_user / find_assignment / find_participant
| Finds a user/assignment/participant by ID and returns it
| Fetches the corresponding record by ID; renders a not-found error if record does not exist
|}

==Proposed Testing Changes==

<ul>
<li>Add more descriptive comments for tests</li>
<li>Add test that checks that authorizations are updated correctly</li>
<li>Add test that checks that inputted path parameters are not missing and valid inputs</li>
<li>Tests at Line 222 and Line 231 are redundant, as the only difference in the test is the authorization, which would not affect what happens if a participant is not found</li>
</ul>

=Implementation=

As this is a refactoring project, most of our work on the codebase involved cleaning up the current codebase to better align with foundational code style principles rather than introducing any of kind of new functionality. Our primary focus is to make the code more readable and easier to work with than before. We also took the liberty of fixing some minor errors that we found along the way.

==Changelog==

<ul>
<li>Naming changes to multiple functions for better clarity and consistency</li>
<li>Changed HTML status message for <code>show()</code> from 201 (Created) to 200 (OK) as it is a better fit</li>
<li>Created the <code>assign_participant_permissions()</code> method</li>
<li>Introduced two additional tests and removed a redundant one (see Testing Plan for more details)</li>
<li>Removed redundant queries to <code>Participant.all()</code> in both filtering methods</li>
<li>Updated method comments to be more descriptive (see comments table in Design)</li>
</ul>

==Function Name Changes==

The previous implementation had several functions that were strangely named or had names that could be easily misconstrued. The name changes remain the same from the proposal and design section, but for the purpose of clarity, the rationale for each of the functions will be provided below.

===<code>list_user_participants</code> and <code>list_assignment_participants</code>===

These two functions are meant to render a list of participants given a <code>User</code> or <code>Assignment</code> respectively. Based on the name alone, it is difficult to tell that the function would render a User/Assignment or Participants. In order to remedy this, we chose the names <code>render_participants_by_user_id</code> and <code>render_participants_by_assignment_id</code>. The word "list" was replaced by "render" in order to better denote that it is rendering something (json in this case) and the "by" is added to emphasize that the User and Assignment are being used as parameters to search for the Participants. This provides a much clearer picture of what these functions should do compared to before.

===<code>add</code>===

The <code>add</code> function's name was too vague to be particularly useful in identifying its purpose. To be more accurate, the function was meant to add the user to a given assignment, which would return a participant from the assignment's <code>add_participant</code> function. The new name of the function provides much more context to what it does (<code>add_participant_to_assignment</code>).

===<code>filter_user_participants</code> and <code>filter_assignment_participants</code>===

Similar to the list methods that were previously mentioned, it is difficult to tell what exactly these two functions do. While it can be easily seen that it filters something, what is being filtered can be easily mistaken (e.g. does it filter users by participants or participants by users?). The new names, <code>filter_participants_by_user</code> and <code>filter_participants_by_assignment</code> are much clearer in defining that the User and Assignment are being used as the filter parameters for the function.

==HTML Status Code Change for <code>GET</code> Call==

The status code being used for this was previously 201, denoting "successful creation". We have corrected this to a simple 200 code, which signifies an "ok" status message. This issue was actually identified by ChatGPT while we were dowsing for potential issues.

Test modified

<syntaxhighlight lang=ruby line>
# Tests whether a participant returns properly if provided with a valid Participant ID
response '200', 'Returns a participant' do
let(:id) { participant2.id }

run_test! do |response|
data = JSON.parse(response.body)
expect(data['user_id']).to eq(studenta.id)
expect(data['assignment_id']).to eq(assignment2.id)
end
end
</syntaxhighlight>

==Redundant <code>Participant.all</code> Queries Removed==

This issue was initially caught by the LLM, ChatGPT, that the team was using in order to find potential issues. We found that simply using <code>Participant.where()</code> removed the need for the <code>Participant.all</code> query entirely while changing nothing else about the function, reducing the amount of queries necessary to call the filtering methods, <code>filter_participants_by_user</code> and <code>filter_participants_by_assignment</code>.

Example:

<syntaxhighlight lang=ruby line>
# New function
def filter_participants_by_user(user)
participants = Participant.where(user_id: user.id) if user # This would simply get the participants given the proper user ID
participants.order(:id)
end

# Old function
def filter_participants_by_user(user)
participants = Participant.all() # This would obtain the entire list of participants rather than just the necessary ones
participants = participants.where(user_id: user.id) if user
participants.order(:id)
end
</syntaxhighlight>

==New Private Method: <code>assign_participant_permissions()</code>==

The reasoning behind the addition of this method is because of a repeated piece of code that existed in the previous implementation:

<syntaxhighlight lang=ruby line>
permissions = retrieve_participant_permissions(authorization)

participant.authorization = authorization
participant.can_submit = permissions[:can_submit]
participant.can_review = permissions[:can_review]
participant.can_take_quiz = permissions[:can_take_quiz]
participant.can_mentor = permissions[:can_mentor]
</syntaxhighlight>

This was repeated in two different contexts: when the Participant was updated or created. This is a violation of the DRY principle, as the same code is repeated multiple times where it could have been reduced to make it more easily readable. In order to resolve this issue, we simply turned this code snippet into a private method that can be called within <code>participants_controller.rb</code>:

<syntaxhighlight lang=ruby line>
# An authorization string containing the participant's role is taken and used to determine
# what permissions will be allocated to the participant. Each of these permissions will
# then be assigned to the Participant's database permission attributes.
#
# @param [String] authorization: An authorization string that represents the participant's role
# @param [Participant] participant: The participant whose authorization permissions are being updated
def assign_participant_permissions(authorization, participant)
# Call helper method from participants_helper to retrieve a dictionary containing the
# appropriate permission boolean values for the role specified by the authorization string
permissions = retrieve_participant_permissions(authorization)

# Assigns each of the boolean permission values to their respective database counterparts
participant.authorization = authorization
participant.can_submit = permissions[:can_submit]
participant.can_review = permissions[:can_review]
participant.can_take_quiz = permissions[:can_take_quiz]
participant.can_mentor = permissions[:can_mentor]
end
</syntaxhighlight>

===Description:===

An authorization string containing the participant's role is taken and used to determine what permissions will be allocated to the participant. Each of these permissions will then be assigned to the Participant's database permission attributes.

===Parameters:===

<ul>
<li><code>authorization</code>: An authorization string that represents the participant's role. This can be either reader, reviewer, submitter, or mentor.</li>
<li><code>participant</code>: The participant whose attributes are being updated. This is passed in to be modified by the function to be used to assign each of the participant's attribute values that are representative of its assigned role.</li>
</ul>

===Behavior===

<ul>
<li>Use <code>retrieve_participant_permissions</code> from <code>participants_helper</code> in order to get all necessary permission boolean values for a given participant role</li>
<li>Assign each of the permission boolean values (<code>can_submit</code>, <code>can_review</code>, <code>can_take_quiz</code>, <code>can_mentor</code>)</li> from the helper method to their respective database attribute counterparts in Participant
</ul>

==Post-Demo Changes==

There were three notable topics that were brought up during the final demo presentation:

<ul>
<li>The renaming of <code>get_participants_by_user</code> and <code>get_participants_by_assignment</code> to something more suitable to its purpose in rendering the JSON of a list of participants</li>
<li>Consider the application of <code>find_user</code> and <code>find_assignment</code></li> within <code>participants_controller</code>
<li>Update the wiki to provide descriptions for each of the methods included in <code>participants_controller</code> (See Methods subsection in the Implementation section)</li>
</ul>

===Renaming <code>get_participants_by_user</code> and <code>get_participants_by_assignment</code>===

These two functions were renamed (once again) to something that better fit the functionality and purpose of the function. Since these functions are meant to render the lists of participants gotten from their respective parameters and use the ID values for each, both of the functions were renamed to <code>render_participants_by_user_id</code> and <code>render_participants_by_assignment_id</code> respectively. The renaming of the filter methods was also brought up, but those functions actually do use the objects themselves as parameters, so have been left as is for the time being.

===<code>find_user</code> and <code>find_assignment</code></li> within <code>participants_controller</code>===

We reconsidered the use of these methods within the controller since it was somewhat odd that it would have these methods. However, we concluded that, since the find methods are helper methods that are private and not open to be used by other parts of the code, to be fine to leave as is. This is mostly because they are simple helper methods that get the current user and assignment and return them, rendering an error if they do not exist.

==Methods==

===<code>render_participants_by_user_id</code>===

Description

Fetches all participants associated with the specified user. Primarily used to retrieve the list of participants which are equate to the user ID.

Parameters

<ul>
<li><code>user_id [Integer]</code>: ID of the user</li>
</ul>

Returns

<ul>
<li>200 OK: A JSON array of participant objects</li>
<li>401 Unauthorized: If the user is not authorized for the action</li>
<li>404 Not Found: If the user does not exist</li>
<li>422 Unprocessable Entity: If the query fails unexpectedly</li>
</ul>

Notable Changes

<ul>
<li>Renamed from <code>list_user_participants</code> to <code>render_participants_by_user_id</code></li>
</ul>
Code

<syntaxhighlight lang=ruby line>
def render_participants_by_user_id
user = find_user if params[:user_id].present?
return if params[:user_id].present? && user.nil?

participants = filter_participants_by_user(user)

if participants.nil?
render json: participants.errors, status: :unprocessable_entity
else
render json: participants, status: :ok
end
end
</syntaxhighlight>

===<code>render_participants_by_assignment_id</code>===

Description

Fetches all participants associated with a specific assignment. Primarily used to retrieve the list of participants enrolled in an assignment for administrative purposes

Parameters

<ul> <li><code>assignment_id [Integer]</code>: ID of the assignment</li> </ul>

Returns

<ul> <li>200 OK: A JSON array of participant objects</li> <li>401 Unauthorized: If the user is not authorized for the action</li> <li>404 Not Found: If the assignment does not exist</li> <li>422 Unprocessable Entity: If the query fails unexpectedly</li> </ul>

Notable Changes

<ul> <li>Renamed from <code>list_assignment_participants</code> to <code>render_participants_by_assignment_id</code></li> </ul>

Code

<syntaxhighlight lang=ruby line>
def render_participants_by_assignment_id
assignment = find_assignment if params[:assignment_id].present?
return if params[:assignment_id].present? && assignment.nil?

participants = filter_participants_by_assignment(assignment)

if participants.nil?
render json: participants.errors, status: :unprocessable_entity
else
render json: participants, status: :ok
end
end
</syntaxhighlight>

===<code>show</code>===

Description

Fetches the details of a specific participant by their ID. Provides all attributes related to the participant, useful for detailed user tracking.

Parameters

<ul> <li><code>id [Integer]</code>: ID of the participant</li> </ul>

Returns

<ul> <li>200 OK: JSON representation of the participant</li> <li>401 Unauthorized: If the user is not authorized</li> <li>404 Not Found: If the participant does not exist</li> <li>422 Unprocessable Entity: If the lookup fails</li> </ul>

Notable Changes

<ul> <li>Standardized participant lookup to return proper HTTP codes</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def show
participant = Participant.find(params[:id])

if participant.nil?
render json: participant.errors, status: :unprocessable_entity
else
render json: participant, status: :ok
end
end
</syntaxhighlight>

===<code>add_participant_to_assignment</code>===

Description

Adds a user as a participant to an assignment with the specified authorization (role and permissions). This method ensures that appropriate permission settings are applied based on the participant's assigned role.

Parameters

<ul> <li><code>participant[user_id] [Integer]</code>: ID of the user</li> <li><code>participant[assignment_id] [Integer]</code>: ID of the assignment</li> <li><code>authorization [String]</code>: Role assigned to the participant (reader, reviewer, submitter, mentor)</li> </ul>

Returns

<ul> <li>201 Created: Participant successfully added</li> <li>404 Not Found: If user or assignment is not found</li> <li>422 Unprocessable Entity: If authorization is invalid or save fails</li> </ul>

Notable Changes

<ul> <li>The naming convention was made similar to other methods</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def add_participant_to_assignment
user = find_user
return unless user

assignment = find_assignment
return unless assignment

authorization = validate_authorization
return unless authorization

participant = assignment.add_participant(user)
assign_participant_permissions(authorization, participant)

if participant.save
render json: participant, status: :created
else
render json: participant.errors, status: :unprocessable_entity
end
end
</syntaxhighlight>

===<code>update_authorization</code>===

Description

Updates the authorization (role) of an existing participant. Used when a participant's responsibilities or privileges within an assignment change and need to be updated.

Parameters

<ul> <li><code>id [Integer]</code>: ID of the participant</li> <li><code>authorization [String]</code>: New role to assign (reader, reviewer, submitter, mentor)</li> </ul>

Returns

<ul> <li>201 Created: Authorization updated successfully</li> <li>401 Unauthorized: If the user is not authorized</li> <li>404 Not Found: If participant is not found</li> <li>422 Unprocessable Entity: If authorization is invalid</li> </ul>

Notable Changes

<ul> <li>Added validation for authorization role values</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def update_authorization
participant = find_participant
return unless participant

authorization = validate_authorization
return unless authorization

assign_participant_permissions(authorization, participant)

if participant.save
render json: participant, status: :created
else
render json: participant.errors, status: :unprocessable_entity
end
end
</syntaxhighlight>

===<code>destroy</code>===

Description

Deletes a participant from the system. Optionally includes assignment and team context in the success message. This helps maintain clean records by removing users who drop out or are mistakenly added.

Parameters

<ul> <li><code>id [Integer]</code>: ID of the participant</li> <li><code>assignment_id [Integer] (optional)</code></li> <li><code>team_id [Integer] (optional)</code></li> </ul>

Returns

<ul> <li>200 OK: Success message indicating deletion</li> <li>401 Unauthorized: If the user is not authorized</li> <li>404 Not Found: If participant is not found</li> <li>422 Unprocessable Entity: If deletion fails</li> </ul>

Notable Changes

<ul> <li>Enhanced success message based on team/assignment presence</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def destroy
participant = Participant.find_by(id: params[:id])

if participant.nil?
render json: { error: 'Not Found' }, status: :not_found
elsif participant.destroy
successful_deletion_message = if params[:team_id].nil?
"Participant #{params[:id]} in Assignment #{params[:assignment_id]} has been deleted successfully!"
else
"Participant #{params[:id]} in Team #{params[:team_id]} of Assignment #{params[:assignment_id]} has been deleted successfully!"
end
render json: { message: successful_deletion_message }, status: :ok
else
render json: participant.errors, status: :unprocessable_entity
end
end
</syntaxhighlight>

===<code>participants_params</code>===

Description

Defines the strong parameters allowed when creating or updating a participant. Ensures only permitted and validated fields are processed to protect against malicious data injection.

Parameters

<ul> <li><code>participant</code>: Hash containing fields like user_id, assignment_id, authorization, etc.</li> </ul>

Returns

<ul> <li>Permitted parameter hash for participant creation/update</li> </ul>

Notable Changes

<ul> <li>Updated to include all permission and assignment-related fields</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def participant_params
params.require(:participant).permit(:user_id, :assignment_id, :authorization, :can_submit,
:can_review, :can_take_quiz, :can_mentor, :handle,
:team_id, :join_team_request_id, :permission_granted,
:topic, :current_stage, :stage_deadline)
end
</syntaxhighlight>

===<code>filter_participants_by_user</code>===

Description

Fetches participants associated with a given user, ordered by ID. Primarily used when displaying all participations of a single user across different assignments.

Parameters

<ul> <li><code>user [User]</code>: User object</li> </ul>

Returns

<ul> <li>Ordered list of participants for the user</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def filter_participants_by_user(user)
participants = Participant.where(user_id: user.id) if user
participants.order(:id)
end
</syntaxhighlight>

===<code>filter_participants_by_assignment</code>===

Description

Fetches participants associated with a given assignment, ordered by ID. Helps instructors or admins manage the list of all users participating in a particular assignment.
Parameters

<ul> <li><code>assignment [Assignment]</code>: Assignment object</li> </ul>

Returns

<ul> <li>Ordered list of participants for the assignment</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def filter_participants_by_assignment(assignment)
participants = Participant.where(assignment_id: assignment.id) if assignment
participants.order(:id)
end
</syntaxhighlight>

===<code>find_user</code>===

Description

Finds a user based on the provided user_id. Validates the existence of the user before performing operations like adding or retrieving participants

Parameters

<ul> <li><code>user_id [Integer]</code>: ID of the user</li> </ul>

Returns

<ul> <li>User object if found</li> <li>404 error if not found</li> </ul>

Notable Changes

<ul> <li>Centralized user lookup and error handling</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def find_user
user_id = params[:user_id]
user = User.find_by(id: user_id)
render json: { error: 'User not found' }, status: :not_found unless user
user
end
</syntaxhighlight>

===<code>find_assignment</code>===

Description

Finds an assignment based on the provided assignment_id. Ensures that participant-related actions are linked to a valid and existing assignment record.

Parameters

<ul> <li><code>assignment_id [Integer]</code>: ID of the assignment</li> </ul>

Returns

<ul> <li>Assignment object if found</li> <li>404 error if not found</li> </ul>

Notable Changes

<ul> <li>Centralized assignment lookup and error handling</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def find_assignment
assignment_id = params[:assignment_id]
assignment = Assignment.find_by(id: assignment_id)
render json: { error: 'Assignment not found' }, status: :not_found unless assignment
assignment
end
</syntaxhighlight>

===<code>find_participant</code>===

Description

Finds a participant based on the provided ID. Used internally to validate the participant’s presence before operations like update, show, or delete.

Parameters

<ul> <li><code>id [Integer]</code>: ID of the participant</li> </ul>

Returns

<ul> <li>Participant object if found</li> <li>404 error if not found</li> </ul>

Notable Changes

<ul> <li>Centralized participant lookup and error handling</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def find_participant
participant_id = params[:id]
participant = Participant.find_by(id: participant_id)
render json: { error: 'Participant not found' }, status: :not_found unless participant
participant
end
</syntaxhighlight>

===<code>assign_participant_permissions</code>===

Description

Assigns permission flags to a participant based on the authorization role provided. It automatically maps permissions like can_submit, can_review, can_take_quiz, and can_mentor depending on the assigned role.

Parameters

<ul> <li><code>authorization [String]</code>: Role to assign</li> <li><code>participant [Participant]</code>: Participant object</li> </ul>

Returns

<ul> <li>Participant object with updated permissions</li> </ul>

Notable Changes

<ul> <li>Added dynamic permission setting based on role</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def assign_participant_permissions(authorization, participant)
# Call helper method from participants_helper to retrieve a dictionary containing the
# appropriate permission boolean values for the role specified by the authorization string
permissions = retrieve_participant_permissions(authorization)

# Assigns each of the boolean permission values to their respective database counterparts
participant.authorization = authorization
participant.can_submit = permissions[:can_submit]
participant.can_review = permissions[:can_review]
participant.can_take_quiz = permissions[:can_take_quiz]
participant.can_mentor = permissions[:can_mentor]
end
</syntaxhighlight>

===<code>validate_authorization</code>===

Description

Validates that the authorization string is present and one of the accepted roles. Ensures role-based access integrity by allowing only predefined, valid roles to be assigned to participants.

Parameters

<ul> <li><code>authorization [String]</code>: Authorization role</li> </ul>

Returns

<ul> <li>Validated authorization string</li> <li>422 error if invalid</li> </ul>

Notable Changes

<ul> <li>Standardized authorization validation across endpoints</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def validate_authorization
valid_authorizations = %w[reader reviewer submitter mentor]
authorization = params[:authorization]
authorization = authorization.downcase if authorization.present?

unless authorization
render json: { error: 'authorization is required' }, status: :unprocessable_entity
return
end

unless valid_authorizations.include?(authorization)
render json: { error: 'authorization not valid. Valid authorizations are: Reader, Reviewer, Submitter, Mentor' },
status: :unprocessable_entity
return
end

authorization
end
</syntaxhighlight>

=Testing Plan=

Of this implementation, also existing 25 tests are passing. We have also given each test their respective IDs within <code>participants_controller_spec.rb</code> as well so that they may be more easily identifiable. For more information about the previous testing plan, please refer to the previous implementation's page here: [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2484._Reimplement_participants_controller.rb]

Below are any modifications to the existing test file (<code>participants_controller_spec.rb</code>) that we have made during the course of this project, alongside the descriptions and rationales behind them:

==Tests==

Below are the tests that are included in this implementation. We have updated the test descriptions to include more accurate and detailed information about each of the tests as well. Any tests that have been modified or new will be specified as such:

{| class="wikitable" style="margin-left:40px"
|-
! Test ID !! Test Description
|-
| 1 || Retrieve participants by valid user ID (should return participant data)
|-
| 2 || Retrieve participants by user ID with no participants (should return empty array)
|-
| 3 || Retrieve participants with non-existent user ID (should return 'User not found')
|-
| 4 || Retrieve participants by user ID with invalid token (should return 'Not Authorized')
|-
| 5 || Retrieve participants by valid assignment ID (should return participant data)
|-
| 6 || Retrieve participants by non-existent assignment ID (should return 'Assignment not found')
|-
| 7 || Retrieve participants by assignment ID with invalid token (should return 'Not Authorized')
|-
| 8 || Retrieve a participant by valid ID (should return participant details)
|-
| 9 || Retrieve a participant by non-existent ID (should return 'Not Found')
|-
| 10 || Retrieve a participant by ID with invalid token (should return 'Not Authorized')
|-
| 11 || Delete a participant by valid ID (should return deletion success message)
|-
| 12 || Delete a participant by non-existent ID (should return 'Not Found')
|-
| 13 || Delete a participant by ID with invalid token (should return 'Not Authorized')
|-
| 14 || Update participant authorization with valid data (should return updated authorization)
|-
| 15 || Update participant authorization with non-existent participant ID (should return 'Participant not found')
|-
| 16 || Update participant authorization with invalid role (should return 'authorization not valid')
|-
| 17 || Update participant authorization with invalid token (should return 'Not Authorized')
|-
| 18 || Add a participant successfully (should return participant data with authorization)
|-
| 19 || Add a participant that already exists (should return duplicate participant error)
|-
| 20 || Add a participant with non-existent user ID (should return 'User not found')
|-
| 21 || Add a participant with non-existent assignment ID (should return 'Assignment not found')
|-
| 22 || Add a participant with invalid authorization (should return 'authorization not valid')
|-
| 23 || Add a participant with unsupported authorization format (should return 'authorization not valid')
|-
| 24 (NEW) || Add a participant missing user_id in request body (should return 'User not found')
|-
| 25 (NEW) || Add a participant missing assignment_id in request body (should return 'Assignment not found')
|}

==Removed Tests==

These are any tests that we have modified or removed from the previous testing plan. If the test ID is denoted by (Previously), that means that the ID shown was part of the previous implementation's testing plan.

{| class="wikitable" style="margin-left:40px"
|-
! Test ID !! Modification Description
|-
| (Previously) 22 || This test was removed as it was redundant. While it is important to check the authorization of the participant that would be invalid, the invalid ID used for this test is a duplicate of the previous test, meaning the result is guaranteed to match that of the previous test regardless of what is meant to be tested.
|}

=Next Steps=

Being able to implement this could potentially simplify rendering to the view somewhat in that it could handle simple HTML status code handling. Below are some examples of implementations to serve as a point of reference:

===Example 1===

<syntaxhighlight lang=ruby line>
# Checks if a target object (participant or participants) is not nil and then renders the object.
# If the object is nil, renders the object errors and sends a not_found_status and if the object
# exists, renders the object and sends a success status
# not_found_status default: :unprocessable_entity (422)
# success_status default: :ok (200)
def render_object_or_error(object, not_found_status: :unprocessable_entity, success_status: :ok)
if object.nil?
render json: { error: 'Resource not found' }, status: not_found_status
elsif object.respond_to?(:errors) && object.errors.any?
render json: object.errors, status: :unprocessable_entity
else
render json: object, status: success_status
end
</syntaxhighlight>

This example is modeled to be specific to the most common use case for this function in the <code>participants_controller.rb</code> by returning the default 422 and 200 error and success codes that are used by three instances of JSON rendering where it checks for whether a list of participants or a single participant is nil. These default values for the status codes are mainly to cover those instances, but could be changed to something else if necessary. The <code>object</code> parameter is representative of the object that was meant to be rendered given the success or failure of the operation.

===Example 2===

<syntaxhighlight lang=ruby line>
def render_object_if(conditional, object, error_status, success_status)
if conditional
render json: { error: 'Resource not found' }, status: error_status
else
render json: object, status: success_status
end
</syntaxhighlight>

This example is a more generic implementation of the function, mandating the error and success status codes rather than providing default values. The point of this was to emphasize readability when glancing over the use of this function. For example, being able to tell that seeing the function being used would immediately tell the reader what the success and failure states were immediately without having to find and inspect the function itself. The <code>conditional</code> parameter would also allow the function to act similarly to a more readable ternary statement made for rendering.

Implementing this successfully would reduce the amount of repetitive code being used within the controller, as the if-else view rendering is very common in <code>participants_controller.rb</code>. We were unable to implement it within our given timeframe, so we opted to divert our focus on other, important tasks that we needed to do.

=Team=
'''Mentor'''

*Aniruddha Rajnekar <aarajnek@ncsu.edu>

'''Students'''

*Akhil Adusumilli <aadusum@ncsu.edu>

*Vansh Dodiya <vkdodiya@ncsu.edu>

*Brian Huynh <bhhuynh@ncsu.edu>

= Relevant Links =

Pull Request [https://github.com/expertiza/reimplementation-back-end/pull/192] 
GitHub Repository [https://github.com/Vansh17/refactoring-participants-controller.git] 
GitHub Project Board [https://github.com/users/Vansh17/projects/2] 
<code>participants_controller.rb</code> in Old Expertiza [https://github.com/expertiza/expertiza/blob/main/app/controllers/participants_controller.rb] 
<code>participants_helper.rb</code> in Old Expertiza [https://github.com/expertiza/expertiza/blob/main/app/helpers/participants_helper.rb]

CSC/ECE 517 Spring 2025 - E2531 Refactor participants controller.rb

2025-04-27T19:43:36Z

Vkdodiya: /* add_participant_to_assignment */

=Introduction=
From the project description: "This project aims to refactor the <code>participants_controller.rb</code> and its helper class, <code>participants_helper.rb</code>, in the Expertiza system. The focus will be on improving code structure by implementing DRY and SOLID principles, enhancing readability with meaningful comments and clear naming conventions, and ensuring robustness through comprehensive RSpec testing." Since this is a refactoring project, we will also be utilizing Large Language Models (LLMs) to aid in development. More information on how we used them can be found in the section below.

==Video Overview==

https://youtu.be/4kfz0hrmSg4

Note: In the video it shows the test file at the end, but does not mention a last-minute change that numbers all of the tests to make it much easier to keep track of each of the tests and which ones are passing.

=Use of Large Language Models (LLMs)=

For this project, we are using ChatGPT as an LLM helper in determining what issues there are within the code. The use of LLMs in this project will likely be limited to probing for potential issues that exist within the system.

Below we have organized the following prompts and a summary of the output in a table:

{| class="wikitable" style="margin-left:40px"
|-
! style="width: 25%" | Prompts !! LLM Output Summary
|-
| [Code from <code>participants_controller.rb</code>] Are there any ways where we can refactor the code to improve readability, DRYness, and clarity of error handling?
|| It recognized some of the issues we, as a team, had already identified and suggested fixes that were similar to what we outlined: Redundant JSON Rendering Code[https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2025_-_E2531_Refactor_participants_controller.rb#Simplifying_Redundant_JSON_Rendering_Code] and Simplifying the Assignment of Participant Fields[https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2025_-_E2531_Refactor_participants_controller.rb#Simplifying_the_Assignment_of_Participant_Fields]. Additionally, it suggested minor changes that we could implement, such as using <code>Participant.where(...)</code> instead of <code>Participant.all</code> to filter out the code more efficiently instead of getting all database instances every time, as well as the use of strong parameters in <code>add()</code> and <code>update_authorization()</code> to avoid having to implement custom parsing techniques. It also recommends renaming the <code>add()</code> function to something more specific in relation to its purpose (adding a <code>Participant</code> to an <code>Assignment</code>.
|-
| Potential Redundant Tests in <code>participants_controller_spec.rb</code>
|| The tests on line 222 and 231 are redundant as only the authorization differs. (Note: This should be investigated to see whether or not this is necessary)
|-
| Checking for issues with the current testing files
|| The "Get Participant by ID call" test was returning a 201 status code instead of the more suitable 200 code
|}

For more detailed information on what prompts we used and the output we got, please visit the page here: [https://docs.google.com/document/d/105_U_Coky-edx7n-tFhD2B5RqmVXxEsKPW_qUaf7bQU/edit?usp=sharing].

=Requirements=
Objectives:
<ul>
<li>Apply DRY principles to eliminate redundant code.</li>
<li>Ensure adherence to SOLID principles for better maintainability.</li>
<li>Use appropriate design patterns to optimize code architecture.</li>
<li>Write clear, informative comments and use meaningful naming conventions.</li>
<li>Test the refactored code extensively with RSpec to verify functionality.</li>
</ul>
Deliverables:
<ul>
<li>Refactored code for participants_controller.rb and helper class.</li>
<li>Comprehensive test suite and coverage report.</li>
<li>Updated and detailed documentation.</li>
<li>Video demonstration of the API functionality.</li>
</ul>

==Existing Issues==
<ul>
<li>There are some API functions that are currently not functioning properly, making it somewhat difficult to test</li>
<li>Some API functions are not returning the correct HTML status messages (e.g. test on line 136 returns 201 instead of 200)</li>
<li>Documentation and comments can be somewhat vague</li>
<ul>
<li>In-line comments should be more descriptive, explaining what the code does in more details</li>
<li>Tests are not described via comments, but in name alone; some more descriptive comments that explain the tests in more detail would be ideal</li>
</ul>
<li>Eliminate instances of redundant code</li>
<li>The method naming should be more descriptive</li>

</ul>

=Design / Proposed Solution=

Based on the previous implementation's controller diagram, we have created a new version that contains our proposed changes and modifications to <code>participants_controller.rb</code>.

[[File:Participants_controller_refactor_v1.2.png]]

==Simplifying Redundant JSON Rendering Code==

Many of the functions in the current implementation contain a conditional if-else statement that determines what HTML status code is returned alongside any necessary values that are requested. Due to its simple nature, it might be possible to reduce the amount of space this takes up by implementing a private helper method that would shorten the process.

Example:

<syntaxhighlight lang=ruby line> if participants.nil?
render json: participants.errors, status: :unprocessable_entity
else
render json: participants, status: :ok
end</syntaxhighlight>

==Simplifying the Assignment of Participant Fields==

The <code>add()</code> and <code>update()</code> both take up a significant amount of space to assign values to database fields and are essentially the same in functionality (in terms of this specific section. We can remove redundancy by creating a method that can remove this redundancy.

Example

<syntaxhighlight lang=ruby line> permissions = retrieve_participant_permissions(authorization)

participant.authorization = authorization
participant.can_submit = permissions[:can_submit]
participant.can_review = permissions[:can_review]
participant.can_take_quiz = permissions[:can_take_quiz]
participant.can_mentor = permissions[:can_mentor]</syntaxhighlight>

==Provide More Clarity in Function Names==

There are some functions that are somewhat unclear/vague in <code>participants_controller.rb</code>. For example, the <code>list_user_participants()</code> and <code>list_assignment_participants()</code>.

=== - Suggested Method Name Improvements ===

{| class="wikitable"
! Old Method Name
! New Method Name
! Notes
|-
| <code>list_user_participants</code>
| <code>render_participants_by_user_id</code>
| Clearer and more descriptive
|-
| <code>list_assignment_participants</code>
| <code>render_participants_by_assignment_id</code>
| Clearer and more descriptive and is consistent with the other get method
|-
| <code>add</code>
| <code>add_participant_to_assignment</code>
| Describes both creation and authorization setup of participant to assignment
|-
| <code>filter_user_participants</code>
| <code>filter_participants_by_user</code>
| Highlights the purpose of the method
|-
| <code>filter_assignment_participants</code>
| <code>filter_participants_by_assignment</code>
| Highlights the purpose of the method

|}

==Improve Documentation and Comments==

Some of the documentation and in-line comments can be somewhat vague. This can lead to misconceptions about how some functions work or how some of the code can function. Below are potential improvements we plan to make for function descriptions, though these may change with the final implementation.

=== Improved Method Comments ===

{| class="wikitable"
! Method
! Original Comment
! Refactored Comment
|-
| render_participants_by_user_id
| Return a list of participants for a given user
| Retrieves all participants associated with the specified user ID
|-
| render_participants_by_assignment_id
| Return a list of participants for a given assignment
| Retrieves all participants linked to the specified assignment ID
|-
| show
| Return a specified participant
| Fetch and return the participant with the given ID
|-
| add_participant_to_assignment
| Assign the specified authorization to the participant and add them to an assignment
| Creates a new participant for a given assignment and assigns appropriate authorization and permissions
|-
| update_authorization
| Update the specified participant to the specified authorization
| Updates the participant’s authorization role and related permissions
|-
| destroy
| Delete a participant
| Deletes the participant identified by the given ID and returns a confirmation message
|-
| participant_params
| Permitted parameters for creating a Participant object
| Strong parameters: list of attributes allowed for participant creation or update
|-
| filter_participants_by_user
| Filters participants based on the provided user. Returns participants ordered by their IDs
| Returns a sorted list of participants filtered by user, if provided
|-
| filter_participants_by_assignment
| Filters participants based on the provided assignment. Returns participants ordered by their IDs
| Returns a sorted list of participants filtered by assignment, if provided
|-
| validate_authorization
| Validates that the authorization parameter is present and is one of the following valid authorizations: reader, reviewer, submitter, mentor
| Ensures authorization param is valid and returns it in lowercase; otherwise returns error response
|-
| find_user / find_assignment / find_participant
| Finds a user/assignment/participant by ID and returns it
| Fetches the corresponding record by ID; renders a not-found error if record does not exist
|}

==Proposed Testing Changes==

<ul>
<li>Add more descriptive comments for tests</li>
<li>Add test that checks that authorizations are updated correctly</li>
<li>Add test that checks that inputted path parameters are not missing and valid inputs</li>
<li>Tests at Line 222 and Line 231 are redundant, as the only difference in the test is the authorization, which would not affect what happens if a participant is not found</li>
</ul>

=Implementation=

As this is a refactoring project, most of our work on the codebase involved cleaning up the current codebase to better align with foundational code style principles rather than introducing any of kind of new functionality. Our primary focus is to make the code more readable and easier to work with than before. We also took the liberty of fixing some minor errors that we found along the way.

==Changelog==

<ul>
<li>Naming changes to multiple functions for better clarity and consistency</li>
<li>Changed HTML status message for <code>show()</code> from 201 (Created) to 200 (OK) as it is a better fit</li>
<li>Created the <code>assign_participant_permissions()</code> method</li>
<li>Introduced two additional tests and removed a redundant one (see Testing Plan for more details)</li>
<li>Removed redundant queries to <code>Participant.all()</code> in both filtering methods</li>
<li>Updated method comments to be more descriptive (see comments table in Design)</li>
</ul>

==Function Name Changes==

The previous implementation had several functions that were strangely named or had names that could be easily misconstrued. The name changes remain the same from the proposal and design section, but for the purpose of clarity, the rationale for each of the functions will be provided below.

===<code>list_user_participants</code> and <code>list_assignment_participants</code>===

These two functions are meant to render a list of participants given a <code>User</code> or <code>Assignment</code> respectively. Based on the name alone, it is difficult to tell that the function would render a User/Assignment or Participants. In order to remedy this, we chose the names <code>render_participants_by_user_id</code> and <code>render_participants_by_assignment_id</code>. The word "list" was replaced by "render" in order to better denote that it is rendering something (json in this case) and the "by" is added to emphasize that the User and Assignment are being used as parameters to search for the Participants. This provides a much clearer picture of what these functions should do compared to before.

===<code>add</code>===

The <code>add</code> function's name was too vague to be particularly useful in identifying its purpose. To be more accurate, the function was meant to add the user to a given assignment, which would return a participant from the assignment's <code>add_participant</code> function. The new name of the function provides much more context to what it does (<code>add_participant_to_assignment</code>).

===<code>filter_user_participants</code> and <code>filter_assignment_participants</code>===

Similar to the list methods that were previously mentioned, it is difficult to tell what exactly these two functions do. While it can be easily seen that it filters something, what is being filtered can be easily mistaken (e.g. does it filter users by participants or participants by users?). The new names, <code>filter_participants_by_user</code> and <code>filter_participants_by_assignment</code> are much clearer in defining that the User and Assignment are being used as the filter parameters for the function.

==HTML Status Code Change for <code>GET</code> Call==

The status code being used for this was previously 201, denoting "successful creation". We have corrected this to a simple 200 code, which signifies an "ok" status message. This issue was actually identified by ChatGPT while we were dowsing for potential issues.

Test modified

<syntaxhighlight lang=ruby line>
# Tests whether a participant returns properly if provided with a valid Participant ID
response '200', 'Returns a participant' do
let(:id) { participant2.id }

run_test! do |response|
data = JSON.parse(response.body)
expect(data['user_id']).to eq(studenta.id)
expect(data['assignment_id']).to eq(assignment2.id)
end
end
</syntaxhighlight>

==Redundant <code>Participant.all</code> Queries Removed==

This issue was initially caught by the LLM, ChatGPT, that the team was using in order to find potential issues. We found that simply using <code>Participant.where()</code> removed the need for the <code>Participant.all</code> query entirely while changing nothing else about the function, reducing the amount of queries necessary to call the filtering methods, <code>filter_participants_by_user</code> and <code>filter_participants_by_assignment</code>.

Example:

<syntaxhighlight lang=ruby line>
# New function
def filter_participants_by_user(user)
participants = Participant.where(user_id: user.id) if user # This would simply get the participants given the proper user ID
participants.order(:id)
end

# Old function
def filter_participants_by_user(user)
participants = Participant.all() # This would obtain the entire list of participants rather than just the necessary ones
participants = participants.where(user_id: user.id) if user
participants.order(:id)
end
</syntaxhighlight>

==New Private Method: <code>assign_participant_permissions()</code>==

The reasoning behind the addition of this method is because of a repeated piece of code that existed in the previous implementation:

<syntaxhighlight lang=ruby line>
permissions = retrieve_participant_permissions(authorization)

participant.authorization = authorization
participant.can_submit = permissions[:can_submit]
participant.can_review = permissions[:can_review]
participant.can_take_quiz = permissions[:can_take_quiz]
participant.can_mentor = permissions[:can_mentor]
</syntaxhighlight>

This was repeated in two different contexts: when the Participant was updated or created. This is a violation of the DRY principle, as the same code is repeated multiple times where it could have been reduced to make it more easily readable. In order to resolve this issue, we simply turned this code snippet into a private method that can be called within <code>participants_controller.rb</code>:

<syntaxhighlight lang=ruby line>
# An authorization string containing the participant's role is taken and used to determine
# what permissions will be allocated to the participant. Each of these permissions will
# then be assigned to the Participant's database permission attributes.
#
# @param [String] authorization: An authorization string that represents the participant's role
# @param [Participant] participant: The participant whose authorization permissions are being updated
def assign_participant_permissions(authorization, participant)
# Call helper method from participants_helper to retrieve a dictionary containing the
# appropriate permission boolean values for the role specified by the authorization string
permissions = retrieve_participant_permissions(authorization)

# Assigns each of the boolean permission values to their respective database counterparts
participant.authorization = authorization
participant.can_submit = permissions[:can_submit]
participant.can_review = permissions[:can_review]
participant.can_take_quiz = permissions[:can_take_quiz]
participant.can_mentor = permissions[:can_mentor]
end
</syntaxhighlight>

===Description:===

An authorization string containing the participant's role is taken and used to determine what permissions will be allocated to the participant. Each of these permissions will then be assigned to the Participant's database permission attributes.

===Parameters:===

<ul>
<li><code>authorization</code>: An authorization string that represents the participant's role. This can be either reader, reviewer, submitter, or mentor.</li>
<li><code>participant</code>: The participant whose attributes are being updated. This is passed in to be modified by the function to be used to assign each of the participant's attribute values that are representative of its assigned role.</li>
</ul>

===Behavior===

<ul>
<li>Use <code>retrieve_participant_permissions</code> from <code>participants_helper</code> in order to get all necessary permission boolean values for a given participant role</li>
<li>Assign each of the permission boolean values (<code>can_submit</code>, <code>can_review</code>, <code>can_take_quiz</code>, <code>can_mentor</code>)</li> from the helper method to their respective database attribute counterparts in Participant
</ul>

==Post-Demo Changes==

There were three notable topics that were brought up during the final demo presentation:

<ul>
<li>The renaming of <code>get_participants_by_user</code> and <code>get_participants_by_assignment</code> to something more suitable to its purpose in rendering the JSON of a list of participants</li>
<li>Consider the application of <code>find_user</code> and <code>find_assignment</code></li> within <code>participants_controller</code>
<li>Update the wiki to provide descriptions for each of the methods included in <code>participants_controller</code> (See Methods subsection in the Implementation section)</li>
</ul>

===Renaming <code>get_participants_by_user</code> and <code>get_participants_by_assignment</code>===

These two functions were renamed (once again) to something that better fit the functionality and purpose of the function. Since these functions are meant to render the lists of participants gotten from their respective parameters and use the ID values for each, both of the functions were renamed to <code>render_participants_by_user_id</code> and <code>render_participants_by_assignment_id</code> respectively. The renaming of the filter methods was also brought up, but those functions actually do use the objects themselves as parameters, so have been left as is for the time being.

===<code>find_user</code> and <code>find_assignment</code></li> within <code>participants_controller</code>===

We reconsidered the use of these methods within the controller since it was somewhat odd that it would have these methods. However, we concluded that, since the find methods are helper methods that are private and not open to be used by other parts of the code, to be fine to leave as is. This is mostly because they are simple helper methods that get the current user and assignment and return them, rendering an error if they do not exist.

==Methods==

===<code>render_participants_by_user_id</code>===

Description

Fetches all participants associated with the specified user.

Parameters

<ul>
<li><code>user_id [Integer]</code>: ID of the user</li>
</ul>

Returns

<ul>
<li>200 OK: A JSON array of participant objects</li>
<li>401 Unauthorized: If the user is not authorized for the action</li>
<li>404 Not Found: If the user does not exist</li>
<li>422 Unprocessable Entity: If the query fails unexpectedly</li>
</ul>

Notable Changes

<ul>
<li>Renamed from <code>list_user_participants</code> to <code>render_participants_by_user_id</code></li>
</ul>
Code

<syntaxhighlight lang=ruby line>
def render_participants_by_user_id
user = find_user if params[:user_id].present?
return if params[:user_id].present? && user.nil?

participants = filter_participants_by_user(user)

if participants.nil?
render json: participants.errors, status: :unprocessable_entity
else
render json: participants, status: :ok
end
end
</syntaxhighlight>

===<code>render_participants_by_assignment_id</code>===

Description

Fetches all participants associated with a specific assignment.

Parameters

<ul> <li><code>assignment_id [Integer]</code>: ID of the assignment</li> </ul>

Returns

<ul> <li>200 OK: A JSON array of participant objects</li> <li>401 Unauthorized: If the user is not authorized for the action</li> <li>404 Not Found: If the assignment does not exist</li> <li>422 Unprocessable Entity: If the query fails unexpectedly</li> </ul>

Notable Changes

<ul> <li>Renamed from <code>list_assignment_participants</code> to <code>render_participants_by_assignment_id</code></li> </ul>

Code

<syntaxhighlight lang=ruby line>
def render_participants_by_assignment_id
assignment = find_assignment if params[:assignment_id].present?
return if params[:assignment_id].present? && assignment.nil?

participants = filter_participants_by_assignment(assignment)

if participants.nil?
render json: participants.errors, status: :unprocessable_entity
else
render json: participants, status: :ok
end
end
</syntaxhighlight>

===<code>show</code>===

Description

Fetches the details of a specific participant by their ID.

Parameters

<ul> <li><code>id [Integer]</code>: ID of the participant</li> </ul>

Returns

<ul> <li>200 OK: JSON representation of the participant</li> <li>401 Unauthorized: If the user is not authorized</li> <li>404 Not Found: If the participant does not exist</li> <li>422 Unprocessable Entity: If the lookup fails</li> </ul>

Notable Changes

<ul> <li>Standardized participant lookup to return proper HTTP codes</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def show
participant = Participant.find(params[:id])

if participant.nil?
render json: participant.errors, status: :unprocessable_entity
else
render json: participant, status: :ok
end
end
</syntaxhighlight>

===<code>add_participant_to_assignment</code>===

Description

Adds a user as a participant to an assignment with the specified authorization (role and permissions).

Parameters

<ul> <li><code>participant[user_id] [Integer]</code>: ID of the user</li> <li><code>participant[assignment_id] [Integer]</code>: ID of the assignment</li> <li><code>authorization [String]</code>: Role assigned to the participant (reader, reviewer, submitter, mentor)</li> </ul>

Returns

<ul> <li>201 Created: Participant successfully added</li> <li>404 Not Found: If user or assignment is not found</li> <li>422 Unprocessable Entity: If authorization is invalid or save fails</li> </ul>

Notable Changes

<ul> <li>The naming convention was made similar to other methods</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def add_participant_to_assignment
user = find_user
return unless user

assignment = find_assignment
return unless assignment

authorization = validate_authorization
return unless authorization

participant = assignment.add_participant(user)
assign_participant_permissions(authorization, participant)

if participant.save
render json: participant, status: :created
else
render json: participant.errors, status: :unprocessable_entity
end
end
</syntaxhighlight>

===<code>update_authorization</code>===

Description

Updates the authorization (role) of an existing participant.

Parameters

<ul> <li><code>id [Integer]</code>: ID of the participant</li> <li><code>authorization [String]</code>: New role to assign (reader, reviewer, submitter, mentor)</li> </ul>

Returns

<ul> <li>201 Created: Authorization updated successfully</li> <li>401 Unauthorized: If the user is not authorized</li> <li>404 Not Found: If participant is not found</li> <li>422 Unprocessable Entity: If authorization is invalid</li> </ul>

Notable Changes

<ul> <li>Added validation for authorization role values</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def update_authorization
participant = find_participant
return unless participant

authorization = validate_authorization
return unless authorization

assign_participant_permissions(authorization, participant)

if participant.save
render json: participant, status: :created
else
render json: participant.errors, status: :unprocessable_entity
end
end
</syntaxhighlight>

===<code>destroy</code>===

Description

Deletes a participant from the system. Optionally includes assignment and team context in the success message.

Parameters

<ul> <li><code>id [Integer]</code>: ID of the participant</li> <li><code>assignment_id [Integer] (optional)</code></li> <li><code>team_id [Integer] (optional)</code></li> </ul>

Returns

<ul> <li>200 OK: Success message indicating deletion</li> <li>401 Unauthorized: If the user is not authorized</li> <li>404 Not Found: If participant is not found</li> <li>422 Unprocessable Entity: If deletion fails</li> </ul>

Notable Changes

<ul> <li>Enhanced success message based on team/assignment presence</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def destroy
participant = Participant.find_by(id: params[:id])

if participant.nil?
render json: { error: 'Not Found' }, status: :not_found
elsif participant.destroy
successful_deletion_message = if params[:team_id].nil?
"Participant #{params[:id]} in Assignment #{params[:assignment_id]} has been deleted successfully!"
else
"Participant #{params[:id]} in Team #{params[:team_id]} of Assignment #{params[:assignment_id]} has been deleted successfully!"
end
render json: { message: successful_deletion_message }, status: :ok
else
render json: participant.errors, status: :unprocessable_entity
end
end
</syntaxhighlight>

===<code>participants_params</code>===

Description

Defines the strong parameters allowed when creating or updating a participant.

Parameters

<ul> <li><code>participant</code>: Hash containing fields like user_id, assignment_id, authorization, etc.</li> </ul>

Returns

<ul> <li>Permitted parameter hash for participant creation/update</li> </ul>

Notable Changes

<ul> <li>Updated to include all permission and assignment-related fields</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def participant_params
params.require(:participant).permit(:user_id, :assignment_id, :authorization, :can_submit,
:can_review, :can_take_quiz, :can_mentor, :handle,
:team_id, :join_team_request_id, :permission_granted,
:topic, :current_stage, :stage_deadline)
end
</syntaxhighlight>

===<code>filter_participants_by_user</code>===

Description

Fetches participants associated with a given user, ordered by ID.

Parameters

<ul> <li><code>user [User]</code>: User object</li> </ul>

Returns

<ul> <li>Ordered list of participants for the user</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def filter_participants_by_user(user)
participants = Participant.where(user_id: user.id) if user
participants.order(:id)
end
</syntaxhighlight>

===<code>filter_participants_by_assignment</code>===

Description

Fetches participants associated with a given assignment, ordered by ID.

Parameters

<ul> <li><code>assignment [Assignment]</code>: Assignment object</li> </ul>

Returns

<ul> <li>Ordered list of participants for the assignment</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def filter_participants_by_assignment(assignment)
participants = Participant.where(assignment_id: assignment.id) if assignment
participants.order(:id)
end
</syntaxhighlight>

===<code>find_user</code>===

Description

Finds a user based on the provided user_id.

Parameters

<ul> <li><code>user_id [Integer]</code>: ID of the user</li> </ul>

Returns

<ul> <li>User object if found</li> <li>404 error if not found</li> </ul>

Notable Changes

<ul> <li>Centralized user lookup and error handling</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def find_user
user_id = params[:user_id]
user = User.find_by(id: user_id)
render json: { error: 'User not found' }, status: :not_found unless user
user
end
</syntaxhighlight>

===<code>find_assignment</code>===

Description

Finds an assignment based on the provided assignment_id.

Parameters

<ul> <li><code>assignment_id [Integer]</code>: ID of the assignment</li> </ul>

Returns

<ul> <li>Assignment object if found</li> <li>404 error if not found</li> </ul>

Notable Changes

<ul> <li>Centralized assignment lookup and error handling</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def find_assignment
assignment_id = params[:assignment_id]
assignment = Assignment.find_by(id: assignment_id)
render json: { error: 'Assignment not found' }, status: :not_found unless assignment
assignment
end
</syntaxhighlight>

===<code>find_participant</code>===

Description

Finds a participant based on the provided ID.

Parameters

<ul> <li><code>id [Integer]</code>: ID of the participant</li> </ul>

Returns

<ul> <li>Participant object if found</li> <li>404 error if not found</li> </ul>

Notable Changes

<ul> <li>Centralized participant lookup and error handling</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def find_participant
participant_id = params[:id]
participant = Participant.find_by(id: participant_id)
render json: { error: 'Participant not found' }, status: :not_found unless participant
participant
end
</syntaxhighlight>

===<code>assign_participant_permissions</code>===

Description

Assigns permission flags to a participant based on the authorization role provided.

Parameters

<ul> <li><code>authorization [String]</code>: Role to assign</li> <li><code>participant [Participant]</code>: Participant object</li> </ul>

Returns

<ul> <li>Participant object with updated permissions</li> </ul>

Notable Changes

<ul> <li>Added dynamic permission setting based on role</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def assign_participant_permissions(authorization, participant)
# Call helper method from participants_helper to retrieve a dictionary containing the
# appropriate permission boolean values for the role specified by the authorization string
permissions = retrieve_participant_permissions(authorization)

# Assigns each of the boolean permission values to their respective database counterparts
participant.authorization = authorization
participant.can_submit = permissions[:can_submit]
participant.can_review = permissions[:can_review]
participant.can_take_quiz = permissions[:can_take_quiz]
participant.can_mentor = permissions[:can_mentor]
end
</syntaxhighlight>

===<code>validate_authorization</code>===

Description

Validates that the authorization string is present and one of the accepted roles.

Parameters

<ul> <li><code>authorization [String]</code>: Authorization role</li> </ul>

Returns

<ul> <li>Validated authorization string</li> <li>422 error if invalid</li> </ul>

Notable Changes

<ul> <li>Standardized authorization validation across endpoints</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def validate_authorization
valid_authorizations = %w[reader reviewer submitter mentor]
authorization = params[:authorization]
authorization = authorization.downcase if authorization.present?

unless authorization
render json: { error: 'authorization is required' }, status: :unprocessable_entity
return
end

unless valid_authorizations.include?(authorization)
render json: { error: 'authorization not valid. Valid authorizations are: Reader, Reviewer, Submitter, Mentor' },
status: :unprocessable_entity
return
end

authorization
end
</syntaxhighlight>

=Testing Plan=

Of this implementation, also existing 25 tests are passing. We have also given each test their respective IDs within <code>participants_controller_spec.rb</code> as well so that they may be more easily identifiable. For more information about the previous testing plan, please refer to the previous implementation's page here: [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2484._Reimplement_participants_controller.rb]

Below are any modifications to the existing test file (<code>participants_controller_spec.rb</code>) that we have made during the course of this project, alongside the descriptions and rationales behind them:

==Tests==

Below are the tests that are included in this implementation. We have updated the test descriptions to include more accurate and detailed information about each of the tests as well. Any tests that have been modified or new will be specified as such:

{| class="wikitable" style="margin-left:40px"
|-
! Test ID !! Test Description
|-
| 1 || Retrieve participants by valid user ID (should return participant data)
|-
| 2 || Retrieve participants by user ID with no participants (should return empty array)
|-
| 3 || Retrieve participants with non-existent user ID (should return 'User not found')
|-
| 4 || Retrieve participants by user ID with invalid token (should return 'Not Authorized')
|-
| 5 || Retrieve participants by valid assignment ID (should return participant data)
|-
| 6 || Retrieve participants by non-existent assignment ID (should return 'Assignment not found')
|-
| 7 || Retrieve participants by assignment ID with invalid token (should return 'Not Authorized')
|-
| 8 || Retrieve a participant by valid ID (should return participant details)
|-
| 9 || Retrieve a participant by non-existent ID (should return 'Not Found')
|-
| 10 || Retrieve a participant by ID with invalid token (should return 'Not Authorized')
|-
| 11 || Delete a participant by valid ID (should return deletion success message)
|-
| 12 || Delete a participant by non-existent ID (should return 'Not Found')
|-
| 13 || Delete a participant by ID with invalid token (should return 'Not Authorized')
|-
| 14 || Update participant authorization with valid data (should return updated authorization)
|-
| 15 || Update participant authorization with non-existent participant ID (should return 'Participant not found')
|-
| 16 || Update participant authorization with invalid role (should return 'authorization not valid')
|-
| 17 || Update participant authorization with invalid token (should return 'Not Authorized')
|-
| 18 || Add a participant successfully (should return participant data with authorization)
|-
| 19 || Add a participant that already exists (should return duplicate participant error)
|-
| 20 || Add a participant with non-existent user ID (should return 'User not found')
|-
| 21 || Add a participant with non-existent assignment ID (should return 'Assignment not found')
|-
| 22 || Add a participant with invalid authorization (should return 'authorization not valid')
|-
| 23 || Add a participant with unsupported authorization format (should return 'authorization not valid')
|-
| 24 (NEW) || Add a participant missing user_id in request body (should return 'User not found')
|-
| 25 (NEW) || Add a participant missing assignment_id in request body (should return 'Assignment not found')
|}

==Removed Tests==

These are any tests that we have modified or removed from the previous testing plan. If the test ID is denoted by (Previously), that means that the ID shown was part of the previous implementation's testing plan.

{| class="wikitable" style="margin-left:40px"
|-
! Test ID !! Modification Description
|-
| (Previously) 22 || This test was removed as it was redundant. While it is important to check the authorization of the participant that would be invalid, the invalid ID used for this test is a duplicate of the previous test, meaning the result is guaranteed to match that of the previous test regardless of what is meant to be tested.
|}

=Next Steps=

Being able to implement this could potentially simplify rendering to the view somewhat in that it could handle simple HTML status code handling. Below are some examples of implementations to serve as a point of reference:

===Example 1===

<syntaxhighlight lang=ruby line>
# Checks if a target object (participant or participants) is not nil and then renders the object.
# If the object is nil, renders the object errors and sends a not_found_status and if the object
# exists, renders the object and sends a success status
# not_found_status default: :unprocessable_entity (422)
# success_status default: :ok (200)
def render_object_or_error(object, not_found_status: :unprocessable_entity, success_status: :ok)
if object.nil?
render json: { error: 'Resource not found' }, status: not_found_status
elsif object.respond_to?(:errors) && object.errors.any?
render json: object.errors, status: :unprocessable_entity
else
render json: object, status: success_status
end
</syntaxhighlight>

This example is modeled to be specific to the most common use case for this function in the <code>participants_controller.rb</code> by returning the default 422 and 200 error and success codes that are used by three instances of JSON rendering where it checks for whether a list of participants or a single participant is nil. These default values for the status codes are mainly to cover those instances, but could be changed to something else if necessary. The <code>object</code> parameter is representative of the object that was meant to be rendered given the success or failure of the operation.

===Example 2===

<syntaxhighlight lang=ruby line>
def render_object_if(conditional, object, error_status, success_status)
if conditional
render json: { error: 'Resource not found' }, status: error_status
else
render json: object, status: success_status
end
</syntaxhighlight>

This example is a more generic implementation of the function, mandating the error and success status codes rather than providing default values. The point of this was to emphasize readability when glancing over the use of this function. For example, being able to tell that seeing the function being used would immediately tell the reader what the success and failure states were immediately without having to find and inspect the function itself. The <code>conditional</code> parameter would also allow the function to act similarly to a more readable ternary statement made for rendering.

Implementing this successfully would reduce the amount of repetitive code being used within the controller, as the if-else view rendering is very common in <code>participants_controller.rb</code>. We were unable to implement it within our given timeframe, so we opted to divert our focus on other, important tasks that we needed to do.

=Team=
'''Mentor'''

*Aniruddha Rajnekar <aarajnek@ncsu.edu>

'''Students'''

*Akhil Adusumilli <aadusum@ncsu.edu>

*Vansh Dodiya <vkdodiya@ncsu.edu>

*Brian Huynh <bhhuynh@ncsu.edu>

= Relevant Links =

Pull Request [https://github.com/expertiza/reimplementation-back-end/pull/192] 
GitHub Repository [https://github.com/Vansh17/refactoring-participants-controller.git] 
GitHub Project Board [https://github.com/users/Vansh17/projects/2] 
<code>participants_controller.rb</code> in Old Expertiza [https://github.com/expertiza/expertiza/blob/main/app/controllers/participants_controller.rb] 
<code>participants_helper.rb</code> in Old Expertiza [https://github.com/expertiza/expertiza/blob/main/app/helpers/participants_helper.rb]

CSC/ECE 517 Spring 2025 - E2531 Refactor participants controller.rb

2025-04-27T19:41:56Z

Vkdodiya: /* filter_participants_by_user */

=Introduction=
From the project description: "This project aims to refactor the <code>participants_controller.rb</code> and its helper class, <code>participants_helper.rb</code>, in the Expertiza system. The focus will be on improving code structure by implementing DRY and SOLID principles, enhancing readability with meaningful comments and clear naming conventions, and ensuring robustness through comprehensive RSpec testing." Since this is a refactoring project, we will also be utilizing Large Language Models (LLMs) to aid in development. More information on how we used them can be found in the section below.

==Video Overview==

https://youtu.be/4kfz0hrmSg4

Note: In the video it shows the test file at the end, but does not mention a last-minute change that numbers all of the tests to make it much easier to keep track of each of the tests and which ones are passing.

=Use of Large Language Models (LLMs)=

For this project, we are using ChatGPT as an LLM helper in determining what issues there are within the code. The use of LLMs in this project will likely be limited to probing for potential issues that exist within the system.

Below we have organized the following prompts and a summary of the output in a table:

{| class="wikitable" style="margin-left:40px"
|-
! style="width: 25%" | Prompts !! LLM Output Summary
|-
| [Code from <code>participants_controller.rb</code>] Are there any ways where we can refactor the code to improve readability, DRYness, and clarity of error handling?
|| It recognized some of the issues we, as a team, had already identified and suggested fixes that were similar to what we outlined: Redundant JSON Rendering Code[https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2025_-_E2531_Refactor_participants_controller.rb#Simplifying_Redundant_JSON_Rendering_Code] and Simplifying the Assignment of Participant Fields[https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2025_-_E2531_Refactor_participants_controller.rb#Simplifying_the_Assignment_of_Participant_Fields]. Additionally, it suggested minor changes that we could implement, such as using <code>Participant.where(...)</code> instead of <code>Participant.all</code> to filter out the code more efficiently instead of getting all database instances every time, as well as the use of strong parameters in <code>add()</code> and <code>update_authorization()</code> to avoid having to implement custom parsing techniques. It also recommends renaming the <code>add()</code> function to something more specific in relation to its purpose (adding a <code>Participant</code> to an <code>Assignment</code>.
|-
| Potential Redundant Tests in <code>participants_controller_spec.rb</code>
|| The tests on line 222 and 231 are redundant as only the authorization differs. (Note: This should be investigated to see whether or not this is necessary)
|-
| Checking for issues with the current testing files
|| The "Get Participant by ID call" test was returning a 201 status code instead of the more suitable 200 code
|}

For more detailed information on what prompts we used and the output we got, please visit the page here: [https://docs.google.com/document/d/105_U_Coky-edx7n-tFhD2B5RqmVXxEsKPW_qUaf7bQU/edit?usp=sharing].

=Requirements=
Objectives:
<ul>
<li>Apply DRY principles to eliminate redundant code.</li>
<li>Ensure adherence to SOLID principles for better maintainability.</li>
<li>Use appropriate design patterns to optimize code architecture.</li>
<li>Write clear, informative comments and use meaningful naming conventions.</li>
<li>Test the refactored code extensively with RSpec to verify functionality.</li>
</ul>
Deliverables:
<ul>
<li>Refactored code for participants_controller.rb and helper class.</li>
<li>Comprehensive test suite and coverage report.</li>
<li>Updated and detailed documentation.</li>
<li>Video demonstration of the API functionality.</li>
</ul>

==Existing Issues==
<ul>
<li>There are some API functions that are currently not functioning properly, making it somewhat difficult to test</li>
<li>Some API functions are not returning the correct HTML status messages (e.g. test on line 136 returns 201 instead of 200)</li>
<li>Documentation and comments can be somewhat vague</li>
<ul>
<li>In-line comments should be more descriptive, explaining what the code does in more details</li>
<li>Tests are not described via comments, but in name alone; some more descriptive comments that explain the tests in more detail would be ideal</li>
</ul>
<li>Eliminate instances of redundant code</li>
<li>The method naming should be more descriptive</li>

</ul>

=Design / Proposed Solution=

Based on the previous implementation's controller diagram, we have created a new version that contains our proposed changes and modifications to <code>participants_controller.rb</code>.

[[File:Participants_controller_refactor_v1.2.png]]

==Simplifying Redundant JSON Rendering Code==

Many of the functions in the current implementation contain a conditional if-else statement that determines what HTML status code is returned alongside any necessary values that are requested. Due to its simple nature, it might be possible to reduce the amount of space this takes up by implementing a private helper method that would shorten the process.

Example:

<syntaxhighlight lang=ruby line> if participants.nil?
render json: participants.errors, status: :unprocessable_entity
else
render json: participants, status: :ok
end</syntaxhighlight>

==Simplifying the Assignment of Participant Fields==

The <code>add()</code> and <code>update()</code> both take up a significant amount of space to assign values to database fields and are essentially the same in functionality (in terms of this specific section. We can remove redundancy by creating a method that can remove this redundancy.

Example

<syntaxhighlight lang=ruby line> permissions = retrieve_participant_permissions(authorization)

participant.authorization = authorization
participant.can_submit = permissions[:can_submit]
participant.can_review = permissions[:can_review]
participant.can_take_quiz = permissions[:can_take_quiz]
participant.can_mentor = permissions[:can_mentor]</syntaxhighlight>

==Provide More Clarity in Function Names==

There are some functions that are somewhat unclear/vague in <code>participants_controller.rb</code>. For example, the <code>list_user_participants()</code> and <code>list_assignment_participants()</code>.

=== - Suggested Method Name Improvements ===

{| class="wikitable"
! Old Method Name
! New Method Name
! Notes
|-
| <code>list_user_participants</code>
| <code>render_participants_by_user_id</code>
| Clearer and more descriptive
|-
| <code>list_assignment_participants</code>
| <code>render_participants_by_assignment_id</code>
| Clearer and more descriptive and is consistent with the other get method
|-
| <code>add</code>
| <code>add_participant_to_assignment</code>
| Describes both creation and authorization setup of participant to assignment
|-
| <code>filter_user_participants</code>
| <code>filter_participants_by_user</code>
| Highlights the purpose of the method
|-
| <code>filter_assignment_participants</code>
| <code>filter_participants_by_assignment</code>
| Highlights the purpose of the method

|}

==Improve Documentation and Comments==

Some of the documentation and in-line comments can be somewhat vague. This can lead to misconceptions about how some functions work or how some of the code can function. Below are potential improvements we plan to make for function descriptions, though these may change with the final implementation.

=== Improved Method Comments ===

{| class="wikitable"
! Method
! Original Comment
! Refactored Comment
|-
| render_participants_by_user_id
| Return a list of participants for a given user
| Retrieves all participants associated with the specified user ID
|-
| render_participants_by_assignment_id
| Return a list of participants for a given assignment
| Retrieves all participants linked to the specified assignment ID
|-
| show
| Return a specified participant
| Fetch and return the participant with the given ID
|-
| add_participant_to_assignment
| Assign the specified authorization to the participant and add them to an assignment
| Creates a new participant for a given assignment and assigns appropriate authorization and permissions
|-
| update_authorization
| Update the specified participant to the specified authorization
| Updates the participant’s authorization role and related permissions
|-
| destroy
| Delete a participant
| Deletes the participant identified by the given ID and returns a confirmation message
|-
| participant_params
| Permitted parameters for creating a Participant object
| Strong parameters: list of attributes allowed for participant creation or update
|-
| filter_participants_by_user
| Filters participants based on the provided user. Returns participants ordered by their IDs
| Returns a sorted list of participants filtered by user, if provided
|-
| filter_participants_by_assignment
| Filters participants based on the provided assignment. Returns participants ordered by their IDs
| Returns a sorted list of participants filtered by assignment, if provided
|-
| validate_authorization
| Validates that the authorization parameter is present and is one of the following valid authorizations: reader, reviewer, submitter, mentor
| Ensures authorization param is valid and returns it in lowercase; otherwise returns error response
|-
| find_user / find_assignment / find_participant
| Finds a user/assignment/participant by ID and returns it
| Fetches the corresponding record by ID; renders a not-found error if record does not exist
|}

==Proposed Testing Changes==

<ul>
<li>Add more descriptive comments for tests</li>
<li>Add test that checks that authorizations are updated correctly</li>
<li>Add test that checks that inputted path parameters are not missing and valid inputs</li>
<li>Tests at Line 222 and Line 231 are redundant, as the only difference in the test is the authorization, which would not affect what happens if a participant is not found</li>
</ul>

=Implementation=

As this is a refactoring project, most of our work on the codebase involved cleaning up the current codebase to better align with foundational code style principles rather than introducing any of kind of new functionality. Our primary focus is to make the code more readable and easier to work with than before. We also took the liberty of fixing some minor errors that we found along the way.

==Changelog==

<ul>
<li>Naming changes to multiple functions for better clarity and consistency</li>
<li>Changed HTML status message for <code>show()</code> from 201 (Created) to 200 (OK) as it is a better fit</li>
<li>Created the <code>assign_participant_permissions()</code> method</li>
<li>Introduced two additional tests and removed a redundant one (see Testing Plan for more details)</li>
<li>Removed redundant queries to <code>Participant.all()</code> in both filtering methods</li>
<li>Updated method comments to be more descriptive (see comments table in Design)</li>
</ul>

==Function Name Changes==

The previous implementation had several functions that were strangely named or had names that could be easily misconstrued. The name changes remain the same from the proposal and design section, but for the purpose of clarity, the rationale for each of the functions will be provided below.

===<code>list_user_participants</code> and <code>list_assignment_participants</code>===

These two functions are meant to render a list of participants given a <code>User</code> or <code>Assignment</code> respectively. Based on the name alone, it is difficult to tell that the function would render a User/Assignment or Participants. In order to remedy this, we chose the names <code>render_participants_by_user_id</code> and <code>render_participants_by_assignment_id</code>. The word "list" was replaced by "render" in order to better denote that it is rendering something (json in this case) and the "by" is added to emphasize that the User and Assignment are being used as parameters to search for the Participants. This provides a much clearer picture of what these functions should do compared to before.

===<code>add</code>===

The <code>add</code> function's name was too vague to be particularly useful in identifying its purpose. To be more accurate, the function was meant to add the user to a given assignment, which would return a participant from the assignment's <code>add_participant</code> function. The new name of the function provides much more context to what it does (<code>add_participant_to_assignment</code>).

===<code>filter_user_participants</code> and <code>filter_assignment_participants</code>===

Similar to the list methods that were previously mentioned, it is difficult to tell what exactly these two functions do. While it can be easily seen that it filters something, what is being filtered can be easily mistaken (e.g. does it filter users by participants or participants by users?). The new names, <code>filter_participants_by_user</code> and <code>filter_participants_by_assignment</code> are much clearer in defining that the User and Assignment are being used as the filter parameters for the function.

==HTML Status Code Change for <code>GET</code> Call==

The status code being used for this was previously 201, denoting "successful creation". We have corrected this to a simple 200 code, which signifies an "ok" status message. This issue was actually identified by ChatGPT while we were dowsing for potential issues.

Test modified

<syntaxhighlight lang=ruby line>
# Tests whether a participant returns properly if provided with a valid Participant ID
response '200', 'Returns a participant' do
let(:id) { participant2.id }

run_test! do |response|
data = JSON.parse(response.body)
expect(data['user_id']).to eq(studenta.id)
expect(data['assignment_id']).to eq(assignment2.id)
end
end
</syntaxhighlight>

==Redundant <code>Participant.all</code> Queries Removed==

This issue was initially caught by the LLM, ChatGPT, that the team was using in order to find potential issues. We found that simply using <code>Participant.where()</code> removed the need for the <code>Participant.all</code> query entirely while changing nothing else about the function, reducing the amount of queries necessary to call the filtering methods, <code>filter_participants_by_user</code> and <code>filter_participants_by_assignment</code>.

Example:

<syntaxhighlight lang=ruby line>
# New function
def filter_participants_by_user(user)
participants = Participant.where(user_id: user.id) if user # This would simply get the participants given the proper user ID
participants.order(:id)
end

# Old function
def filter_participants_by_user(user)
participants = Participant.all() # This would obtain the entire list of participants rather than just the necessary ones
participants = participants.where(user_id: user.id) if user
participants.order(:id)
end
</syntaxhighlight>

==New Private Method: <code>assign_participant_permissions()</code>==

The reasoning behind the addition of this method is because of a repeated piece of code that existed in the previous implementation:

<syntaxhighlight lang=ruby line>
permissions = retrieve_participant_permissions(authorization)

participant.authorization = authorization
participant.can_submit = permissions[:can_submit]
participant.can_review = permissions[:can_review]
participant.can_take_quiz = permissions[:can_take_quiz]
participant.can_mentor = permissions[:can_mentor]
</syntaxhighlight>

This was repeated in two different contexts: when the Participant was updated or created. This is a violation of the DRY principle, as the same code is repeated multiple times where it could have been reduced to make it more easily readable. In order to resolve this issue, we simply turned this code snippet into a private method that can be called within <code>participants_controller.rb</code>:

<syntaxhighlight lang=ruby line>
# An authorization string containing the participant's role is taken and used to determine
# what permissions will be allocated to the participant. Each of these permissions will
# then be assigned to the Participant's database permission attributes.
#
# @param [String] authorization: An authorization string that represents the participant's role
# @param [Participant] participant: The participant whose authorization permissions are being updated
def assign_participant_permissions(authorization, participant)
# Call helper method from participants_helper to retrieve a dictionary containing the
# appropriate permission boolean values for the role specified by the authorization string
permissions = retrieve_participant_permissions(authorization)

# Assigns each of the boolean permission values to their respective database counterparts
participant.authorization = authorization
participant.can_submit = permissions[:can_submit]
participant.can_review = permissions[:can_review]
participant.can_take_quiz = permissions[:can_take_quiz]
participant.can_mentor = permissions[:can_mentor]
end
</syntaxhighlight>

===Description:===

An authorization string containing the participant's role is taken and used to determine what permissions will be allocated to the participant. Each of these permissions will then be assigned to the Participant's database permission attributes.

===Parameters:===

<ul>
<li><code>authorization</code>: An authorization string that represents the participant's role. This can be either reader, reviewer, submitter, or mentor.</li>
<li><code>participant</code>: The participant whose attributes are being updated. This is passed in to be modified by the function to be used to assign each of the participant's attribute values that are representative of its assigned role.</li>
</ul>

===Behavior===

<ul>
<li>Use <code>retrieve_participant_permissions</code> from <code>participants_helper</code> in order to get all necessary permission boolean values for a given participant role</li>
<li>Assign each of the permission boolean values (<code>can_submit</code>, <code>can_review</code>, <code>can_take_quiz</code>, <code>can_mentor</code>)</li> from the helper method to their respective database attribute counterparts in Participant
</ul>

==Post-Demo Changes==

There were three notable topics that were brought up during the final demo presentation:

<ul>
<li>The renaming of <code>get_participants_by_user</code> and <code>get_participants_by_assignment</code> to something more suitable to its purpose in rendering the JSON of a list of participants</li>
<li>Consider the application of <code>find_user</code> and <code>find_assignment</code></li> within <code>participants_controller</code>
<li>Update the wiki to provide descriptions for each of the methods included in <code>participants_controller</code> (See Methods subsection in the Implementation section)</li>
</ul>

===Renaming <code>get_participants_by_user</code> and <code>get_participants_by_assignment</code>===

These two functions were renamed (once again) to something that better fit the functionality and purpose of the function. Since these functions are meant to render the lists of participants gotten from their respective parameters and use the ID values for each, both of the functions were renamed to <code>render_participants_by_user_id</code> and <code>render_participants_by_assignment_id</code> respectively. The renaming of the filter methods was also brought up, but those functions actually do use the objects themselves as parameters, so have been left as is for the time being.

===<code>find_user</code> and <code>find_assignment</code></li> within <code>participants_controller</code>===

We reconsidered the use of these methods within the controller since it was somewhat odd that it would have these methods. However, we concluded that, since the find methods are helper methods that are private and not open to be used by other parts of the code, to be fine to leave as is. This is mostly because they are simple helper methods that get the current user and assignment and return them, rendering an error if they do not exist.

==Methods==

===<code>render_participants_by_user_id</code>===

Description

Fetches all participants associated with the specified user.

Parameters

<ul>
<li><code>user_id [Integer]</code>: ID of the user</li>
</ul>

Returns

<ul>
<li>200 OK: A JSON array of participant objects</li>
<li>401 Unauthorized: If the user is not authorized for the action</li>
<li>404 Not Found: If the user does not exist</li>
<li>422 Unprocessable Entity: If the query fails unexpectedly</li>
</ul>

Notable Changes

<ul>
<li>Renamed from <code>list_user_participants</code> to <code>render_participants_by_user_id</code></li>
</ul>
Code

<syntaxhighlight lang=ruby line>
def render_participants_by_user_id
user = find_user if params[:user_id].present?
return if params[:user_id].present? && user.nil?

participants = filter_participants_by_user(user)

if participants.nil?
render json: participants.errors, status: :unprocessable_entity
else
render json: participants, status: :ok
end
end
</syntaxhighlight>

===<code>render_participants_by_assignment_id</code>===

Description

Fetches all participants associated with a specific assignment.

Parameters

<ul> <li><code>assignment_id [Integer]</code>: ID of the assignment</li> </ul>

Returns

<ul> <li>200 OK: A JSON array of participant objects</li> <li>401 Unauthorized: If the user is not authorized for the action</li> <li>404 Not Found: If the assignment does not exist</li> <li>422 Unprocessable Entity: If the query fails unexpectedly</li> </ul>

Notable Changes

<ul> <li>Renamed from <code>list_assignment_participants</code> to <code>render_participants_by_assignment_id</code></li> </ul>

Code

<syntaxhighlight lang=ruby line>
def render_participants_by_assignment_id
assignment = find_assignment if params[:assignment_id].present?
return if params[:assignment_id].present? && assignment.nil?

participants = filter_participants_by_assignment(assignment)

if participants.nil?
render json: participants.errors, status: :unprocessable_entity
else
render json: participants, status: :ok
end
end
</syntaxhighlight>

===<code>show</code>===

Description

Fetches the details of a specific participant by their ID.

Parameters

<ul> <li><code>id [Integer]</code>: ID of the participant</li> </ul>

Returns

<ul> <li>200 OK: JSON representation of the participant</li> <li>401 Unauthorized: If the user is not authorized</li> <li>404 Not Found: If the participant does not exist</li> <li>422 Unprocessable Entity: If the lookup fails</li> </ul>

Notable Changes

<ul> <li>Standardized participant lookup to return proper HTTP codes</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def show
participant = Participant.find(params[:id])

if participant.nil?
render json: participant.errors, status: :unprocessable_entity
else
render json: participant, status: :ok
end
end
</syntaxhighlight>

===<code>add_participant_to_assignment</code>===

Description

Adds a user as a participant to an assignment with the specified authorization (role and permissions).

Parameters

<ul> <li><code>participant[user_id] [Integer]</code>: ID of the user</li> <li><code>participant[assignment_id] [Integer]</code>: ID of the assignment</li> <li><code>authorization [String]</code>: Role assigned to the participant (reader, reviewer, submitter, mentor)</li> </ul>

Returns

<ul> <li>201 Created: Participant successfully added</li> <li>404 Not Found: If user or assignment is not found</li> <li>422 Unprocessable Entity: If authorization is invalid or save fails</li> </ul>

Notable Changes

<ul> <li>Introduced role-based permission assignment during participant creation</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def add_participant_to_assignment
user = find_user
return unless user

assignment = find_assignment
return unless assignment

authorization = validate_authorization
return unless authorization

participant = assignment.add_participant(user)
assign_participant_permissions(authorization, participant)

if participant.save
render json: participant, status: :created
else
render json: participant.errors, status: :unprocessable_entity
end
end
</syntaxhighlight>

===<code>update_authorization</code>===

Description

Updates the authorization (role) of an existing participant.

Parameters

<ul> <li><code>id [Integer]</code>: ID of the participant</li> <li><code>authorization [String]</code>: New role to assign (reader, reviewer, submitter, mentor)</li> </ul>

Returns

<ul> <li>201 Created: Authorization updated successfully</li> <li>401 Unauthorized: If the user is not authorized</li> <li>404 Not Found: If participant is not found</li> <li>422 Unprocessable Entity: If authorization is invalid</li> </ul>

Notable Changes

<ul> <li>Added validation for authorization role values</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def update_authorization
participant = find_participant
return unless participant

authorization = validate_authorization
return unless authorization

assign_participant_permissions(authorization, participant)

if participant.save
render json: participant, status: :created
else
render json: participant.errors, status: :unprocessable_entity
end
end
</syntaxhighlight>

===<code>destroy</code>===

Description

Deletes a participant from the system. Optionally includes assignment and team context in the success message.

Parameters

<ul> <li><code>id [Integer]</code>: ID of the participant</li> <li><code>assignment_id [Integer] (optional)</code></li> <li><code>team_id [Integer] (optional)</code></li> </ul>

Returns

<ul> <li>200 OK: Success message indicating deletion</li> <li>401 Unauthorized: If the user is not authorized</li> <li>404 Not Found: If participant is not found</li> <li>422 Unprocessable Entity: If deletion fails</li> </ul>

Notable Changes

<ul> <li>Enhanced success message based on team/assignment presence</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def destroy
participant = Participant.find_by(id: params[:id])

if participant.nil?
render json: { error: 'Not Found' }, status: :not_found
elsif participant.destroy
successful_deletion_message = if params[:team_id].nil?
"Participant #{params[:id]} in Assignment #{params[:assignment_id]} has been deleted successfully!"
else
"Participant #{params[:id]} in Team #{params[:team_id]} of Assignment #{params[:assignment_id]} has been deleted successfully!"
end
render json: { message: successful_deletion_message }, status: :ok
else
render json: participant.errors, status: :unprocessable_entity
end
end
</syntaxhighlight>

===<code>participants_params</code>===

Description

Defines the strong parameters allowed when creating or updating a participant.

Parameters

<ul> <li><code>participant</code>: Hash containing fields like user_id, assignment_id, authorization, etc.</li> </ul>

Returns

<ul> <li>Permitted parameter hash for participant creation/update</li> </ul>

Notable Changes

<ul> <li>Updated to include all permission and assignment-related fields</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def participant_params
params.require(:participant).permit(:user_id, :assignment_id, :authorization, :can_submit,
:can_review, :can_take_quiz, :can_mentor, :handle,
:team_id, :join_team_request_id, :permission_granted,
:topic, :current_stage, :stage_deadline)
end
</syntaxhighlight>

===<code>filter_participants_by_user</code>===

Description

Fetches participants associated with a given user, ordered by ID.

Parameters

<ul> <li><code>user [User]</code>: User object</li> </ul>

Returns

<ul> <li>Ordered list of participants for the user</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def filter_participants_by_user(user)
participants = Participant.where(user_id: user.id) if user
participants.order(:id)
end
</syntaxhighlight>

===<code>filter_participants_by_assignment</code>===

Description

Fetches participants associated with a given assignment, ordered by ID.

Parameters

<ul> <li><code>assignment [Assignment]</code>: Assignment object</li> </ul>

Returns

<ul> <li>Ordered list of participants for the assignment</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def filter_participants_by_assignment(assignment)
participants = Participant.where(assignment_id: assignment.id) if assignment
participants.order(:id)
end
</syntaxhighlight>

===<code>find_user</code>===

Description

Finds a user based on the provided user_id.

Parameters

<ul> <li><code>user_id [Integer]</code>: ID of the user</li> </ul>

Returns

<ul> <li>User object if found</li> <li>404 error if not found</li> </ul>

Notable Changes

<ul> <li>Centralized user lookup and error handling</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def find_user
user_id = params[:user_id]
user = User.find_by(id: user_id)
render json: { error: 'User not found' }, status: :not_found unless user
user
end
</syntaxhighlight>

===<code>find_assignment</code>===

Description

Finds an assignment based on the provided assignment_id.

Parameters

<ul> <li><code>assignment_id [Integer]</code>: ID of the assignment</li> </ul>

Returns

<ul> <li>Assignment object if found</li> <li>404 error if not found</li> </ul>

Notable Changes

<ul> <li>Centralized assignment lookup and error handling</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def find_assignment
assignment_id = params[:assignment_id]
assignment = Assignment.find_by(id: assignment_id)
render json: { error: 'Assignment not found' }, status: :not_found unless assignment
assignment
end
</syntaxhighlight>

===<code>find_participant</code>===

Description

Finds a participant based on the provided ID.

Parameters

<ul> <li><code>id [Integer]</code>: ID of the participant</li> </ul>

Returns

<ul> <li>Participant object if found</li> <li>404 error if not found</li> </ul>

Notable Changes

<ul> <li>Centralized participant lookup and error handling</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def find_participant
participant_id = params[:id]
participant = Participant.find_by(id: participant_id)
render json: { error: 'Participant not found' }, status: :not_found unless participant
participant
end
</syntaxhighlight>

===<code>assign_participant_permissions</code>===

Description

Assigns permission flags to a participant based on the authorization role provided.

Parameters

<ul> <li><code>authorization [String]</code>: Role to assign</li> <li><code>participant [Participant]</code>: Participant object</li> </ul>

Returns

<ul> <li>Participant object with updated permissions</li> </ul>

Notable Changes

<ul> <li>Added dynamic permission setting based on role</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def assign_participant_permissions(authorization, participant)
# Call helper method from participants_helper to retrieve a dictionary containing the
# appropriate permission boolean values for the role specified by the authorization string
permissions = retrieve_participant_permissions(authorization)

# Assigns each of the boolean permission values to their respective database counterparts
participant.authorization = authorization
participant.can_submit = permissions[:can_submit]
participant.can_review = permissions[:can_review]
participant.can_take_quiz = permissions[:can_take_quiz]
participant.can_mentor = permissions[:can_mentor]
end
</syntaxhighlight>

===<code>validate_authorization</code>===

Description

Validates that the authorization string is present and one of the accepted roles.

Parameters

<ul> <li><code>authorization [String]</code>: Authorization role</li> </ul>

Returns

<ul> <li>Validated authorization string</li> <li>422 error if invalid</li> </ul>

Notable Changes

<ul> <li>Standardized authorization validation across endpoints</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def validate_authorization
valid_authorizations = %w[reader reviewer submitter mentor]
authorization = params[:authorization]
authorization = authorization.downcase if authorization.present?

unless authorization
render json: { error: 'authorization is required' }, status: :unprocessable_entity
return
end

unless valid_authorizations.include?(authorization)
render json: { error: 'authorization not valid. Valid authorizations are: Reader, Reviewer, Submitter, Mentor' },
status: :unprocessable_entity
return
end

authorization
end
</syntaxhighlight>

=Testing Plan=

Of this implementation, also existing 25 tests are passing. We have also given each test their respective IDs within <code>participants_controller_spec.rb</code> as well so that they may be more easily identifiable. For more information about the previous testing plan, please refer to the previous implementation's page here: [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2484._Reimplement_participants_controller.rb]

Below are any modifications to the existing test file (<code>participants_controller_spec.rb</code>) that we have made during the course of this project, alongside the descriptions and rationales behind them:

==Tests==

Below are the tests that are included in this implementation. We have updated the test descriptions to include more accurate and detailed information about each of the tests as well. Any tests that have been modified or new will be specified as such:

{| class="wikitable" style="margin-left:40px"
|-
! Test ID !! Test Description
|-
| 1 || Retrieve participants by valid user ID (should return participant data)
|-
| 2 || Retrieve participants by user ID with no participants (should return empty array)
|-
| 3 || Retrieve participants with non-existent user ID (should return 'User not found')
|-
| 4 || Retrieve participants by user ID with invalid token (should return 'Not Authorized')
|-
| 5 || Retrieve participants by valid assignment ID (should return participant data)
|-
| 6 || Retrieve participants by non-existent assignment ID (should return 'Assignment not found')
|-
| 7 || Retrieve participants by assignment ID with invalid token (should return 'Not Authorized')
|-
| 8 || Retrieve a participant by valid ID (should return participant details)
|-
| 9 || Retrieve a participant by non-existent ID (should return 'Not Found')
|-
| 10 || Retrieve a participant by ID with invalid token (should return 'Not Authorized')
|-
| 11 || Delete a participant by valid ID (should return deletion success message)
|-
| 12 || Delete a participant by non-existent ID (should return 'Not Found')
|-
| 13 || Delete a participant by ID with invalid token (should return 'Not Authorized')
|-
| 14 || Update participant authorization with valid data (should return updated authorization)
|-
| 15 || Update participant authorization with non-existent participant ID (should return 'Participant not found')
|-
| 16 || Update participant authorization with invalid role (should return 'authorization not valid')
|-
| 17 || Update participant authorization with invalid token (should return 'Not Authorized')
|-
| 18 || Add a participant successfully (should return participant data with authorization)
|-
| 19 || Add a participant that already exists (should return duplicate participant error)
|-
| 20 || Add a participant with non-existent user ID (should return 'User not found')
|-
| 21 || Add a participant with non-existent assignment ID (should return 'Assignment not found')
|-
| 22 || Add a participant with invalid authorization (should return 'authorization not valid')
|-
| 23 || Add a participant with unsupported authorization format (should return 'authorization not valid')
|-
| 24 (NEW) || Add a participant missing user_id in request body (should return 'User not found')
|-
| 25 (NEW) || Add a participant missing assignment_id in request body (should return 'Assignment not found')
|}

==Removed Tests==

These are any tests that we have modified or removed from the previous testing plan. If the test ID is denoted by (Previously), that means that the ID shown was part of the previous implementation's testing plan.

{| class="wikitable" style="margin-left:40px"
|-
! Test ID !! Modification Description
|-
| (Previously) 22 || This test was removed as it was redundant. While it is important to check the authorization of the participant that would be invalid, the invalid ID used for this test is a duplicate of the previous test, meaning the result is guaranteed to match that of the previous test regardless of what is meant to be tested.
|}

=Next Steps=

Being able to implement this could potentially simplify rendering to the view somewhat in that it could handle simple HTML status code handling. Below are some examples of implementations to serve as a point of reference:

===Example 1===

<syntaxhighlight lang=ruby line>
# Checks if a target object (participant or participants) is not nil and then renders the object.
# If the object is nil, renders the object errors and sends a not_found_status and if the object
# exists, renders the object and sends a success status
# not_found_status default: :unprocessable_entity (422)
# success_status default: :ok (200)
def render_object_or_error(object, not_found_status: :unprocessable_entity, success_status: :ok)
if object.nil?
render json: { error: 'Resource not found' }, status: not_found_status
elsif object.respond_to?(:errors) && object.errors.any?
render json: object.errors, status: :unprocessable_entity
else
render json: object, status: success_status
end
</syntaxhighlight>

This example is modeled to be specific to the most common use case for this function in the <code>participants_controller.rb</code> by returning the default 422 and 200 error and success codes that are used by three instances of JSON rendering where it checks for whether a list of participants or a single participant is nil. These default values for the status codes are mainly to cover those instances, but could be changed to something else if necessary. The <code>object</code> parameter is representative of the object that was meant to be rendered given the success or failure of the operation.

===Example 2===

<syntaxhighlight lang=ruby line>
def render_object_if(conditional, object, error_status, success_status)
if conditional
render json: { error: 'Resource not found' }, status: error_status
else
render json: object, status: success_status
end
</syntaxhighlight>

This example is a more generic implementation of the function, mandating the error and success status codes rather than providing default values. The point of this was to emphasize readability when glancing over the use of this function. For example, being able to tell that seeing the function being used would immediately tell the reader what the success and failure states were immediately without having to find and inspect the function itself. The <code>conditional</code> parameter would also allow the function to act similarly to a more readable ternary statement made for rendering.

Implementing this successfully would reduce the amount of repetitive code being used within the controller, as the if-else view rendering is very common in <code>participants_controller.rb</code>. We were unable to implement it within our given timeframe, so we opted to divert our focus on other, important tasks that we needed to do.

=Team=
'''Mentor'''

*Aniruddha Rajnekar <aarajnek@ncsu.edu>

'''Students'''

*Akhil Adusumilli <aadusum@ncsu.edu>

*Vansh Dodiya <vkdodiya@ncsu.edu>

*Brian Huynh <bhhuynh@ncsu.edu>

= Relevant Links =

Pull Request [https://github.com/expertiza/reimplementation-back-end/pull/192] 
GitHub Repository [https://github.com/Vansh17/refactoring-participants-controller.git] 
GitHub Project Board [https://github.com/users/Vansh17/projects/2] 
<code>participants_controller.rb</code> in Old Expertiza [https://github.com/expertiza/expertiza/blob/main/app/controllers/participants_controller.rb] 
<code>participants_helper.rb</code> in Old Expertiza [https://github.com/expertiza/expertiza/blob/main/app/helpers/participants_helper.rb]

CSC/ECE 517 Spring 2025 - E2531 Refactor participants controller.rb

2025-04-27T19:41:12Z

Vkdodiya: /* filter_participants_by_assignment */

=Introduction=
From the project description: "This project aims to refactor the <code>participants_controller.rb</code> and its helper class, <code>participants_helper.rb</code>, in the Expertiza system. The focus will be on improving code structure by implementing DRY and SOLID principles, enhancing readability with meaningful comments and clear naming conventions, and ensuring robustness through comprehensive RSpec testing." Since this is a refactoring project, we will also be utilizing Large Language Models (LLMs) to aid in development. More information on how we used them can be found in the section below.

==Video Overview==

https://youtu.be/4kfz0hrmSg4

Note: In the video it shows the test file at the end, but does not mention a last-minute change that numbers all of the tests to make it much easier to keep track of each of the tests and which ones are passing.

=Use of Large Language Models (LLMs)=

For this project, we are using ChatGPT as an LLM helper in determining what issues there are within the code. The use of LLMs in this project will likely be limited to probing for potential issues that exist within the system.

Below we have organized the following prompts and a summary of the output in a table:

{| class="wikitable" style="margin-left:40px"
|-
! style="width: 25%" | Prompts !! LLM Output Summary
|-
| [Code from <code>participants_controller.rb</code>] Are there any ways where we can refactor the code to improve readability, DRYness, and clarity of error handling?
|| It recognized some of the issues we, as a team, had already identified and suggested fixes that were similar to what we outlined: Redundant JSON Rendering Code[https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2025_-_E2531_Refactor_participants_controller.rb#Simplifying_Redundant_JSON_Rendering_Code] and Simplifying the Assignment of Participant Fields[https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2025_-_E2531_Refactor_participants_controller.rb#Simplifying_the_Assignment_of_Participant_Fields]. Additionally, it suggested minor changes that we could implement, such as using <code>Participant.where(...)</code> instead of <code>Participant.all</code> to filter out the code more efficiently instead of getting all database instances every time, as well as the use of strong parameters in <code>add()</code> and <code>update_authorization()</code> to avoid having to implement custom parsing techniques. It also recommends renaming the <code>add()</code> function to something more specific in relation to its purpose (adding a <code>Participant</code> to an <code>Assignment</code>.
|-
| Potential Redundant Tests in <code>participants_controller_spec.rb</code>
|| The tests on line 222 and 231 are redundant as only the authorization differs. (Note: This should be investigated to see whether or not this is necessary)
|-
| Checking for issues with the current testing files
|| The "Get Participant by ID call" test was returning a 201 status code instead of the more suitable 200 code
|}

For more detailed information on what prompts we used and the output we got, please visit the page here: [https://docs.google.com/document/d/105_U_Coky-edx7n-tFhD2B5RqmVXxEsKPW_qUaf7bQU/edit?usp=sharing].

=Requirements=
Objectives:
<ul>
<li>Apply DRY principles to eliminate redundant code.</li>
<li>Ensure adherence to SOLID principles for better maintainability.</li>
<li>Use appropriate design patterns to optimize code architecture.</li>
<li>Write clear, informative comments and use meaningful naming conventions.</li>
<li>Test the refactored code extensively with RSpec to verify functionality.</li>
</ul>
Deliverables:
<ul>
<li>Refactored code for participants_controller.rb and helper class.</li>
<li>Comprehensive test suite and coverage report.</li>
<li>Updated and detailed documentation.</li>
<li>Video demonstration of the API functionality.</li>
</ul>

==Existing Issues==
<ul>
<li>There are some API functions that are currently not functioning properly, making it somewhat difficult to test</li>
<li>Some API functions are not returning the correct HTML status messages (e.g. test on line 136 returns 201 instead of 200)</li>
<li>Documentation and comments can be somewhat vague</li>
<ul>
<li>In-line comments should be more descriptive, explaining what the code does in more details</li>
<li>Tests are not described via comments, but in name alone; some more descriptive comments that explain the tests in more detail would be ideal</li>
</ul>
<li>Eliminate instances of redundant code</li>
<li>The method naming should be more descriptive</li>

</ul>

=Design / Proposed Solution=

Based on the previous implementation's controller diagram, we have created a new version that contains our proposed changes and modifications to <code>participants_controller.rb</code>.

[[File:Participants_controller_refactor_v1.2.png]]

==Simplifying Redundant JSON Rendering Code==

Many of the functions in the current implementation contain a conditional if-else statement that determines what HTML status code is returned alongside any necessary values that are requested. Due to its simple nature, it might be possible to reduce the amount of space this takes up by implementing a private helper method that would shorten the process.

Example:

<syntaxhighlight lang=ruby line> if participants.nil?
render json: participants.errors, status: :unprocessable_entity
else
render json: participants, status: :ok
end</syntaxhighlight>

==Simplifying the Assignment of Participant Fields==

The <code>add()</code> and <code>update()</code> both take up a significant amount of space to assign values to database fields and are essentially the same in functionality (in terms of this specific section. We can remove redundancy by creating a method that can remove this redundancy.

Example

<syntaxhighlight lang=ruby line> permissions = retrieve_participant_permissions(authorization)

participant.authorization = authorization
participant.can_submit = permissions[:can_submit]
participant.can_review = permissions[:can_review]
participant.can_take_quiz = permissions[:can_take_quiz]
participant.can_mentor = permissions[:can_mentor]</syntaxhighlight>

==Provide More Clarity in Function Names==

There are some functions that are somewhat unclear/vague in <code>participants_controller.rb</code>. For example, the <code>list_user_participants()</code> and <code>list_assignment_participants()</code>.

=== - Suggested Method Name Improvements ===

{| class="wikitable"
! Old Method Name
! New Method Name
! Notes
|-
| <code>list_user_participants</code>
| <code>render_participants_by_user_id</code>
| Clearer and more descriptive
|-
| <code>list_assignment_participants</code>
| <code>render_participants_by_assignment_id</code>
| Clearer and more descriptive and is consistent with the other get method
|-
| <code>add</code>
| <code>add_participant_to_assignment</code>
| Describes both creation and authorization setup of participant to assignment
|-
| <code>filter_user_participants</code>
| <code>filter_participants_by_user</code>
| Highlights the purpose of the method
|-
| <code>filter_assignment_participants</code>
| <code>filter_participants_by_assignment</code>
| Highlights the purpose of the method

|}

==Improve Documentation and Comments==

Some of the documentation and in-line comments can be somewhat vague. This can lead to misconceptions about how some functions work or how some of the code can function. Below are potential improvements we plan to make for function descriptions, though these may change with the final implementation.

=== Improved Method Comments ===

{| class="wikitable"
! Method
! Original Comment
! Refactored Comment
|-
| render_participants_by_user_id
| Return a list of participants for a given user
| Retrieves all participants associated with the specified user ID
|-
| render_participants_by_assignment_id
| Return a list of participants for a given assignment
| Retrieves all participants linked to the specified assignment ID
|-
| show
| Return a specified participant
| Fetch and return the participant with the given ID
|-
| add_participant_to_assignment
| Assign the specified authorization to the participant and add them to an assignment
| Creates a new participant for a given assignment and assigns appropriate authorization and permissions
|-
| update_authorization
| Update the specified participant to the specified authorization
| Updates the participant’s authorization role and related permissions
|-
| destroy
| Delete a participant
| Deletes the participant identified by the given ID and returns a confirmation message
|-
| participant_params
| Permitted parameters for creating a Participant object
| Strong parameters: list of attributes allowed for participant creation or update
|-
| filter_participants_by_user
| Filters participants based on the provided user. Returns participants ordered by their IDs
| Returns a sorted list of participants filtered by user, if provided
|-
| filter_participants_by_assignment
| Filters participants based on the provided assignment. Returns participants ordered by their IDs
| Returns a sorted list of participants filtered by assignment, if provided
|-
| validate_authorization
| Validates that the authorization parameter is present and is one of the following valid authorizations: reader, reviewer, submitter, mentor
| Ensures authorization param is valid and returns it in lowercase; otherwise returns error response
|-
| find_user / find_assignment / find_participant
| Finds a user/assignment/participant by ID and returns it
| Fetches the corresponding record by ID; renders a not-found error if record does not exist
|}

==Proposed Testing Changes==

<ul>
<li>Add more descriptive comments for tests</li>
<li>Add test that checks that authorizations are updated correctly</li>
<li>Add test that checks that inputted path parameters are not missing and valid inputs</li>
<li>Tests at Line 222 and Line 231 are redundant, as the only difference in the test is the authorization, which would not affect what happens if a participant is not found</li>
</ul>

=Implementation=

As this is a refactoring project, most of our work on the codebase involved cleaning up the current codebase to better align with foundational code style principles rather than introducing any of kind of new functionality. Our primary focus is to make the code more readable and easier to work with than before. We also took the liberty of fixing some minor errors that we found along the way.

==Changelog==

<ul>
<li>Naming changes to multiple functions for better clarity and consistency</li>
<li>Changed HTML status message for <code>show()</code> from 201 (Created) to 200 (OK) as it is a better fit</li>
<li>Created the <code>assign_participant_permissions()</code> method</li>
<li>Introduced two additional tests and removed a redundant one (see Testing Plan for more details)</li>
<li>Removed redundant queries to <code>Participant.all()</code> in both filtering methods</li>
<li>Updated method comments to be more descriptive (see comments table in Design)</li>
</ul>

==Function Name Changes==

The previous implementation had several functions that were strangely named or had names that could be easily misconstrued. The name changes remain the same from the proposal and design section, but for the purpose of clarity, the rationale for each of the functions will be provided below.

===<code>list_user_participants</code> and <code>list_assignment_participants</code>===

These two functions are meant to render a list of participants given a <code>User</code> or <code>Assignment</code> respectively. Based on the name alone, it is difficult to tell that the function would render a User/Assignment or Participants. In order to remedy this, we chose the names <code>render_participants_by_user_id</code> and <code>render_participants_by_assignment_id</code>. The word "list" was replaced by "render" in order to better denote that it is rendering something (json in this case) and the "by" is added to emphasize that the User and Assignment are being used as parameters to search for the Participants. This provides a much clearer picture of what these functions should do compared to before.

===<code>add</code>===

The <code>add</code> function's name was too vague to be particularly useful in identifying its purpose. To be more accurate, the function was meant to add the user to a given assignment, which would return a participant from the assignment's <code>add_participant</code> function. The new name of the function provides much more context to what it does (<code>add_participant_to_assignment</code>).

===<code>filter_user_participants</code> and <code>filter_assignment_participants</code>===

Similar to the list methods that were previously mentioned, it is difficult to tell what exactly these two functions do. While it can be easily seen that it filters something, what is being filtered can be easily mistaken (e.g. does it filter users by participants or participants by users?). The new names, <code>filter_participants_by_user</code> and <code>filter_participants_by_assignment</code> are much clearer in defining that the User and Assignment are being used as the filter parameters for the function.

==HTML Status Code Change for <code>GET</code> Call==

The status code being used for this was previously 201, denoting "successful creation". We have corrected this to a simple 200 code, which signifies an "ok" status message. This issue was actually identified by ChatGPT while we were dowsing for potential issues.

Test modified

<syntaxhighlight lang=ruby line>
# Tests whether a participant returns properly if provided with a valid Participant ID
response '200', 'Returns a participant' do
let(:id) { participant2.id }

run_test! do |response|
data = JSON.parse(response.body)
expect(data['user_id']).to eq(studenta.id)
expect(data['assignment_id']).to eq(assignment2.id)
end
end
</syntaxhighlight>

==Redundant <code>Participant.all</code> Queries Removed==

This issue was initially caught by the LLM, ChatGPT, that the team was using in order to find potential issues. We found that simply using <code>Participant.where()</code> removed the need for the <code>Participant.all</code> query entirely while changing nothing else about the function, reducing the amount of queries necessary to call the filtering methods, <code>filter_participants_by_user</code> and <code>filter_participants_by_assignment</code>.

Example:

<syntaxhighlight lang=ruby line>
# New function
def filter_participants_by_user(user)
participants = Participant.where(user_id: user.id) if user # This would simply get the participants given the proper user ID
participants.order(:id)
end

# Old function
def filter_participants_by_user(user)
participants = Participant.all() # This would obtain the entire list of participants rather than just the necessary ones
participants = participants.where(user_id: user.id) if user
participants.order(:id)
end
</syntaxhighlight>

==New Private Method: <code>assign_participant_permissions()</code>==

The reasoning behind the addition of this method is because of a repeated piece of code that existed in the previous implementation:

<syntaxhighlight lang=ruby line>
permissions = retrieve_participant_permissions(authorization)

participant.authorization = authorization
participant.can_submit = permissions[:can_submit]
participant.can_review = permissions[:can_review]
participant.can_take_quiz = permissions[:can_take_quiz]
participant.can_mentor = permissions[:can_mentor]
</syntaxhighlight>

This was repeated in two different contexts: when the Participant was updated or created. This is a violation of the DRY principle, as the same code is repeated multiple times where it could have been reduced to make it more easily readable. In order to resolve this issue, we simply turned this code snippet into a private method that can be called within <code>participants_controller.rb</code>:

<syntaxhighlight lang=ruby line>
# An authorization string containing the participant's role is taken and used to determine
# what permissions will be allocated to the participant. Each of these permissions will
# then be assigned to the Participant's database permission attributes.
#
# @param [String] authorization: An authorization string that represents the participant's role
# @param [Participant] participant: The participant whose authorization permissions are being updated
def assign_participant_permissions(authorization, participant)
# Call helper method from participants_helper to retrieve a dictionary containing the
# appropriate permission boolean values for the role specified by the authorization string
permissions = retrieve_participant_permissions(authorization)

# Assigns each of the boolean permission values to their respective database counterparts
participant.authorization = authorization
participant.can_submit = permissions[:can_submit]
participant.can_review = permissions[:can_review]
participant.can_take_quiz = permissions[:can_take_quiz]
participant.can_mentor = permissions[:can_mentor]
end
</syntaxhighlight>

===Description:===

An authorization string containing the participant's role is taken and used to determine what permissions will be allocated to the participant. Each of these permissions will then be assigned to the Participant's database permission attributes.

===Parameters:===

<ul>
<li><code>authorization</code>: An authorization string that represents the participant's role. This can be either reader, reviewer, submitter, or mentor.</li>
<li><code>participant</code>: The participant whose attributes are being updated. This is passed in to be modified by the function to be used to assign each of the participant's attribute values that are representative of its assigned role.</li>
</ul>

===Behavior===

<ul>
<li>Use <code>retrieve_participant_permissions</code> from <code>participants_helper</code> in order to get all necessary permission boolean values for a given participant role</li>
<li>Assign each of the permission boolean values (<code>can_submit</code>, <code>can_review</code>, <code>can_take_quiz</code>, <code>can_mentor</code>)</li> from the helper method to their respective database attribute counterparts in Participant
</ul>

==Post-Demo Changes==

There were three notable topics that were brought up during the final demo presentation:

<ul>
<li>The renaming of <code>get_participants_by_user</code> and <code>get_participants_by_assignment</code> to something more suitable to its purpose in rendering the JSON of a list of participants</li>
<li>Consider the application of <code>find_user</code> and <code>find_assignment</code></li> within <code>participants_controller</code>
<li>Update the wiki to provide descriptions for each of the methods included in <code>participants_controller</code> (See Methods subsection in the Implementation section)</li>
</ul>

===Renaming <code>get_participants_by_user</code> and <code>get_participants_by_assignment</code>===

These two functions were renamed (once again) to something that better fit the functionality and purpose of the function. Since these functions are meant to render the lists of participants gotten from their respective parameters and use the ID values for each, both of the functions were renamed to <code>render_participants_by_user_id</code> and <code>render_participants_by_assignment_id</code> respectively. The renaming of the filter methods was also brought up, but those functions actually do use the objects themselves as parameters, so have been left as is for the time being.

===<code>find_user</code> and <code>find_assignment</code></li> within <code>participants_controller</code>===

We reconsidered the use of these methods within the controller since it was somewhat odd that it would have these methods. However, we concluded that, since the find methods are helper methods that are private and not open to be used by other parts of the code, to be fine to leave as is. This is mostly because they are simple helper methods that get the current user and assignment and return them, rendering an error if they do not exist.

==Methods==

===<code>render_participants_by_user_id</code>===

Description

Fetches all participants associated with the specified user.

Parameters

<ul>
<li><code>user_id [Integer]</code>: ID of the user</li>
</ul>

Returns

<ul>
<li>200 OK: A JSON array of participant objects</li>
<li>401 Unauthorized: If the user is not authorized for the action</li>
<li>404 Not Found: If the user does not exist</li>
<li>422 Unprocessable Entity: If the query fails unexpectedly</li>
</ul>

Notable Changes

<ul>
<li>Renamed from <code>list_user_participants</code> to <code>render_participants_by_user_id</code></li>
</ul>
Code

<syntaxhighlight lang=ruby line>
def render_participants_by_user_id
user = find_user if params[:user_id].present?
return if params[:user_id].present? && user.nil?

participants = filter_participants_by_user(user)

if participants.nil?
render json: participants.errors, status: :unprocessable_entity
else
render json: participants, status: :ok
end
end
</syntaxhighlight>

===<code>render_participants_by_assignment_id</code>===

Description

Fetches all participants associated with a specific assignment.

Parameters

<ul> <li><code>assignment_id [Integer]</code>: ID of the assignment</li> </ul>

Returns

<ul> <li>200 OK: A JSON array of participant objects</li> <li>401 Unauthorized: If the user is not authorized for the action</li> <li>404 Not Found: If the assignment does not exist</li> <li>422 Unprocessable Entity: If the query fails unexpectedly</li> </ul>

Notable Changes

<ul> <li>Renamed from <code>list_assignment_participants</code> to <code>render_participants_by_assignment_id</code></li> </ul>

Code

<syntaxhighlight lang=ruby line>
def render_participants_by_assignment_id
assignment = find_assignment if params[:assignment_id].present?
return if params[:assignment_id].present? && assignment.nil?

participants = filter_participants_by_assignment(assignment)

if participants.nil?
render json: participants.errors, status: :unprocessable_entity
else
render json: participants, status: :ok
end
end
</syntaxhighlight>

===<code>show</code>===

Description

Fetches the details of a specific participant by their ID.

Parameters

<ul> <li><code>id [Integer]</code>: ID of the participant</li> </ul>

Returns

<ul> <li>200 OK: JSON representation of the participant</li> <li>401 Unauthorized: If the user is not authorized</li> <li>404 Not Found: If the participant does not exist</li> <li>422 Unprocessable Entity: If the lookup fails</li> </ul>

Notable Changes

<ul> <li>Standardized participant lookup to return proper HTTP codes</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def show
participant = Participant.find(params[:id])

if participant.nil?
render json: participant.errors, status: :unprocessable_entity
else
render json: participant, status: :ok
end
end
</syntaxhighlight>

===<code>add_participant_to_assignment</code>===

Description

Adds a user as a participant to an assignment with the specified authorization (role and permissions).

Parameters

<ul> <li><code>participant[user_id] [Integer]</code>: ID of the user</li> <li><code>participant[assignment_id] [Integer]</code>: ID of the assignment</li> <li><code>authorization [String]</code>: Role assigned to the participant (reader, reviewer, submitter, mentor)</li> </ul>

Returns

<ul> <li>201 Created: Participant successfully added</li> <li>404 Not Found: If user or assignment is not found</li> <li>422 Unprocessable Entity: If authorization is invalid or save fails</li> </ul>

Notable Changes

<ul> <li>Introduced role-based permission assignment during participant creation</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def add_participant_to_assignment
user = find_user
return unless user

assignment = find_assignment
return unless assignment

authorization = validate_authorization
return unless authorization

participant = assignment.add_participant(user)
assign_participant_permissions(authorization, participant)

if participant.save
render json: participant, status: :created
else
render json: participant.errors, status: :unprocessable_entity
end
end
</syntaxhighlight>

===<code>update_authorization</code>===

Description

Updates the authorization (role) of an existing participant.

Parameters

<ul> <li><code>id [Integer]</code>: ID of the participant</li> <li><code>authorization [String]</code>: New role to assign (reader, reviewer, submitter, mentor)</li> </ul>

Returns

<ul> <li>201 Created: Authorization updated successfully</li> <li>401 Unauthorized: If the user is not authorized</li> <li>404 Not Found: If participant is not found</li> <li>422 Unprocessable Entity: If authorization is invalid</li> </ul>

Notable Changes

<ul> <li>Added validation for authorization role values</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def update_authorization
participant = find_participant
return unless participant

authorization = validate_authorization
return unless authorization

assign_participant_permissions(authorization, participant)

if participant.save
render json: participant, status: :created
else
render json: participant.errors, status: :unprocessable_entity
end
end
</syntaxhighlight>

===<code>destroy</code>===

Description

Deletes a participant from the system. Optionally includes assignment and team context in the success message.

Parameters

<ul> <li><code>id [Integer]</code>: ID of the participant</li> <li><code>assignment_id [Integer] (optional)</code></li> <li><code>team_id [Integer] (optional)</code></li> </ul>

Returns

<ul> <li>200 OK: Success message indicating deletion</li> <li>401 Unauthorized: If the user is not authorized</li> <li>404 Not Found: If participant is not found</li> <li>422 Unprocessable Entity: If deletion fails</li> </ul>

Notable Changes

<ul> <li>Enhanced success message based on team/assignment presence</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def destroy
participant = Participant.find_by(id: params[:id])

if participant.nil?
render json: { error: 'Not Found' }, status: :not_found
elsif participant.destroy
successful_deletion_message = if params[:team_id].nil?
"Participant #{params[:id]} in Assignment #{params[:assignment_id]} has been deleted successfully!"
else
"Participant #{params[:id]} in Team #{params[:team_id]} of Assignment #{params[:assignment_id]} has been deleted successfully!"
end
render json: { message: successful_deletion_message }, status: :ok
else
render json: participant.errors, status: :unprocessable_entity
end
end
</syntaxhighlight>

===<code>participants_params</code>===

Description

Defines the strong parameters allowed when creating or updating a participant.

Parameters

<ul> <li><code>participant</code>: Hash containing fields like user_id, assignment_id, authorization, etc.</li> </ul>

Returns

<ul> <li>Permitted parameter hash for participant creation/update</li> </ul>

Notable Changes

<ul> <li>Updated to include all permission and assignment-related fields</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def participant_params
params.require(:participant).permit(:user_id, :assignment_id, :authorization, :can_submit,
:can_review, :can_take_quiz, :can_mentor, :handle,
:team_id, :join_team_request_id, :permission_granted,
:topic, :current_stage, :stage_deadline)
end
</syntaxhighlight>

===<code>filter_participants_by_user</code>===

Description

Fetches participants associated with a given user, ordered by ID.

Parameters

<ul> <li><code>user [User]</code>: User object</li> </ul>

Returns

<ul> <li>Ordered list of participants for the user</li> </ul>

Notable Changes

<ul> <li>None</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def filter_participants_by_user(user)
participants = Participant.where(user_id: user.id) if user
participants.order(:id)
end
</syntaxhighlight>

===<code>filter_participants_by_assignment</code>===

Description

Fetches participants associated with a given assignment, ordered by ID.

Parameters

<ul> <li><code>assignment [Assignment]</code>: Assignment object</li> </ul>

Returns

<ul> <li>Ordered list of participants for the assignment</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def filter_participants_by_assignment(assignment)
participants = Participant.where(assignment_id: assignment.id) if assignment
participants.order(:id)
end
</syntaxhighlight>

===<code>find_user</code>===

Description

Finds a user based on the provided user_id.

Parameters

<ul> <li><code>user_id [Integer]</code>: ID of the user</li> </ul>

Returns

<ul> <li>User object if found</li> <li>404 error if not found</li> </ul>

Notable Changes

<ul> <li>Centralized user lookup and error handling</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def find_user
user_id = params[:user_id]
user = User.find_by(id: user_id)
render json: { error: 'User not found' }, status: :not_found unless user
user
end
</syntaxhighlight>

===<code>find_assignment</code>===

Description

Finds an assignment based on the provided assignment_id.

Parameters

<ul> <li><code>assignment_id [Integer]</code>: ID of the assignment</li> </ul>

Returns

<ul> <li>Assignment object if found</li> <li>404 error if not found</li> </ul>

Notable Changes

<ul> <li>Centralized assignment lookup and error handling</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def find_assignment
assignment_id = params[:assignment_id]
assignment = Assignment.find_by(id: assignment_id)
render json: { error: 'Assignment not found' }, status: :not_found unless assignment
assignment
end
</syntaxhighlight>

===<code>find_participant</code>===

Description

Finds a participant based on the provided ID.

Parameters

<ul> <li><code>id [Integer]</code>: ID of the participant</li> </ul>

Returns

<ul> <li>Participant object if found</li> <li>404 error if not found</li> </ul>

Notable Changes

<ul> <li>Centralized participant lookup and error handling</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def find_participant
participant_id = params[:id]
participant = Participant.find_by(id: participant_id)
render json: { error: 'Participant not found' }, status: :not_found unless participant
participant
end
</syntaxhighlight>

===<code>assign_participant_permissions</code>===

Description

Assigns permission flags to a participant based on the authorization role provided.

Parameters

<ul> <li><code>authorization [String]</code>: Role to assign</li> <li><code>participant [Participant]</code>: Participant object</li> </ul>

Returns

<ul> <li>Participant object with updated permissions</li> </ul>

Notable Changes

<ul> <li>Added dynamic permission setting based on role</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def assign_participant_permissions(authorization, participant)
# Call helper method from participants_helper to retrieve a dictionary containing the
# appropriate permission boolean values for the role specified by the authorization string
permissions = retrieve_participant_permissions(authorization)

# Assigns each of the boolean permission values to their respective database counterparts
participant.authorization = authorization
participant.can_submit = permissions[:can_submit]
participant.can_review = permissions[:can_review]
participant.can_take_quiz = permissions[:can_take_quiz]
participant.can_mentor = permissions[:can_mentor]
end
</syntaxhighlight>

===<code>validate_authorization</code>===

Description

Validates that the authorization string is present and one of the accepted roles.

Parameters

<ul> <li><code>authorization [String]</code>: Authorization role</li> </ul>

Returns

<ul> <li>Validated authorization string</li> <li>422 error if invalid</li> </ul>

Notable Changes

<ul> <li>Standardized authorization validation across endpoints</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def validate_authorization
valid_authorizations = %w[reader reviewer submitter mentor]
authorization = params[:authorization]
authorization = authorization.downcase if authorization.present?

unless authorization
render json: { error: 'authorization is required' }, status: :unprocessable_entity
return
end

unless valid_authorizations.include?(authorization)
render json: { error: 'authorization not valid. Valid authorizations are: Reader, Reviewer, Submitter, Mentor' },
status: :unprocessable_entity
return
end

authorization
end
</syntaxhighlight>

=Testing Plan=

Of this implementation, also existing 25 tests are passing. We have also given each test their respective IDs within <code>participants_controller_spec.rb</code> as well so that they may be more easily identifiable. For more information about the previous testing plan, please refer to the previous implementation's page here: [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2484._Reimplement_participants_controller.rb]

Below are any modifications to the existing test file (<code>participants_controller_spec.rb</code>) that we have made during the course of this project, alongside the descriptions and rationales behind them:

==Tests==

Below are the tests that are included in this implementation. We have updated the test descriptions to include more accurate and detailed information about each of the tests as well. Any tests that have been modified or new will be specified as such:

{| class="wikitable" style="margin-left:40px"
|-
! Test ID !! Test Description
|-
| 1 || Retrieve participants by valid user ID (should return participant data)
|-
| 2 || Retrieve participants by user ID with no participants (should return empty array)
|-
| 3 || Retrieve participants with non-existent user ID (should return 'User not found')
|-
| 4 || Retrieve participants by user ID with invalid token (should return 'Not Authorized')
|-
| 5 || Retrieve participants by valid assignment ID (should return participant data)
|-
| 6 || Retrieve participants by non-existent assignment ID (should return 'Assignment not found')
|-
| 7 || Retrieve participants by assignment ID with invalid token (should return 'Not Authorized')
|-
| 8 || Retrieve a participant by valid ID (should return participant details)
|-
| 9 || Retrieve a participant by non-existent ID (should return 'Not Found')
|-
| 10 || Retrieve a participant by ID with invalid token (should return 'Not Authorized')
|-
| 11 || Delete a participant by valid ID (should return deletion success message)
|-
| 12 || Delete a participant by non-existent ID (should return 'Not Found')
|-
| 13 || Delete a participant by ID with invalid token (should return 'Not Authorized')
|-
| 14 || Update participant authorization with valid data (should return updated authorization)
|-
| 15 || Update participant authorization with non-existent participant ID (should return 'Participant not found')
|-
| 16 || Update participant authorization with invalid role (should return 'authorization not valid')
|-
| 17 || Update participant authorization with invalid token (should return 'Not Authorized')
|-
| 18 || Add a participant successfully (should return participant data with authorization)
|-
| 19 || Add a participant that already exists (should return duplicate participant error)
|-
| 20 || Add a participant with non-existent user ID (should return 'User not found')
|-
| 21 || Add a participant with non-existent assignment ID (should return 'Assignment not found')
|-
| 22 || Add a participant with invalid authorization (should return 'authorization not valid')
|-
| 23 || Add a participant with unsupported authorization format (should return 'authorization not valid')
|-
| 24 (NEW) || Add a participant missing user_id in request body (should return 'User not found')
|-
| 25 (NEW) || Add a participant missing assignment_id in request body (should return 'Assignment not found')
|}

==Removed Tests==

These are any tests that we have modified or removed from the previous testing plan. If the test ID is denoted by (Previously), that means that the ID shown was part of the previous implementation's testing plan.

{| class="wikitable" style="margin-left:40px"
|-
! Test ID !! Modification Description
|-
| (Previously) 22 || This test was removed as it was redundant. While it is important to check the authorization of the participant that would be invalid, the invalid ID used for this test is a duplicate of the previous test, meaning the result is guaranteed to match that of the previous test regardless of what is meant to be tested.
|}

=Next Steps=

Being able to implement this could potentially simplify rendering to the view somewhat in that it could handle simple HTML status code handling. Below are some examples of implementations to serve as a point of reference:

===Example 1===

<syntaxhighlight lang=ruby line>
# Checks if a target object (participant or participants) is not nil and then renders the object.
# If the object is nil, renders the object errors and sends a not_found_status and if the object
# exists, renders the object and sends a success status
# not_found_status default: :unprocessable_entity (422)
# success_status default: :ok (200)
def render_object_or_error(object, not_found_status: :unprocessable_entity, success_status: :ok)
if object.nil?
render json: { error: 'Resource not found' }, status: not_found_status
elsif object.respond_to?(:errors) && object.errors.any?
render json: object.errors, status: :unprocessable_entity
else
render json: object, status: success_status
end
</syntaxhighlight>

This example is modeled to be specific to the most common use case for this function in the <code>participants_controller.rb</code> by returning the default 422 and 200 error and success codes that are used by three instances of JSON rendering where it checks for whether a list of participants or a single participant is nil. These default values for the status codes are mainly to cover those instances, but could be changed to something else if necessary. The <code>object</code> parameter is representative of the object that was meant to be rendered given the success or failure of the operation.

===Example 2===

<syntaxhighlight lang=ruby line>
def render_object_if(conditional, object, error_status, success_status)
if conditional
render json: { error: 'Resource not found' }, status: error_status
else
render json: object, status: success_status
end
</syntaxhighlight>

This example is a more generic implementation of the function, mandating the error and success status codes rather than providing default values. The point of this was to emphasize readability when glancing over the use of this function. For example, being able to tell that seeing the function being used would immediately tell the reader what the success and failure states were immediately without having to find and inspect the function itself. The <code>conditional</code> parameter would also allow the function to act similarly to a more readable ternary statement made for rendering.

Implementing this successfully would reduce the amount of repetitive code being used within the controller, as the if-else view rendering is very common in <code>participants_controller.rb</code>. We were unable to implement it within our given timeframe, so we opted to divert our focus on other, important tasks that we needed to do.

=Team=
'''Mentor'''

*Aniruddha Rajnekar <aarajnek@ncsu.edu>

'''Students'''

*Akhil Adusumilli <aadusum@ncsu.edu>

*Vansh Dodiya <vkdodiya@ncsu.edu>

*Brian Huynh <bhhuynh@ncsu.edu>

= Relevant Links =

Pull Request [https://github.com/expertiza/reimplementation-back-end/pull/192] 
GitHub Repository [https://github.com/Vansh17/refactoring-participants-controller.git] 
GitHub Project Board [https://github.com/users/Vansh17/projects/2] 
<code>participants_controller.rb</code> in Old Expertiza [https://github.com/expertiza/expertiza/blob/main/app/controllers/participants_controller.rb] 
<code>participants_helper.rb</code> in Old Expertiza [https://github.com/expertiza/expertiza/blob/main/app/helpers/participants_helper.rb]

CSC/ECE 517 Spring 2025 - E2531 Refactor participants controller.rb

2025-04-27T19:32:37Z

Vkdodiya: /* Methods (TEMP) */

=Introduction=
From the project description: "This project aims to refactor the <code>participants_controller.rb</code> and its helper class, <code>participants_helper.rb</code>, in the Expertiza system. The focus will be on improving code structure by implementing DRY and SOLID principles, enhancing readability with meaningful comments and clear naming conventions, and ensuring robustness through comprehensive RSpec testing." Since this is a refactoring project, we will also be utilizing Large Language Models (LLMs) to aid in development. More information on how we used them can be found in the section below.

==Video Overview==

https://youtu.be/4kfz0hrmSg4

Note: In the video it shows the test file at the end, but does not mention a last-minute change that numbers all of the tests to make it much easier to keep track of each of the tests and which ones are passing.

=Use of Large Language Models (LLMs)=

For this project, we are using ChatGPT as an LLM helper in determining what issues there are within the code. The use of LLMs in this project will likely be limited to probing for potential issues that exist within the system.

Below we have organized the following prompts and a summary of the output in a table:

{| class="wikitable" style="margin-left:40px"
|-
! style="width: 25%" | Prompts !! LLM Output Summary
|-
| [Code from <code>participants_controller.rb</code>] Are there any ways where we can refactor the code to improve readability, DRYness, and clarity of error handling?
|| It recognized some of the issues we, as a team, had already identified and suggested fixes that were similar to what we outlined: Redundant JSON Rendering Code[https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2025_-_E2531_Refactor_participants_controller.rb#Simplifying_Redundant_JSON_Rendering_Code] and Simplifying the Assignment of Participant Fields[https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2025_-_E2531_Refactor_participants_controller.rb#Simplifying_the_Assignment_of_Participant_Fields]. Additionally, it suggested minor changes that we could implement, such as using <code>Participant.where(...)</code> instead of <code>Participant.all</code> to filter out the code more efficiently instead of getting all database instances every time, as well as the use of strong parameters in <code>add()</code> and <code>update_authorization()</code> to avoid having to implement custom parsing techniques. It also recommends renaming the <code>add()</code> function to something more specific in relation to its purpose (adding a <code>Participant</code> to an <code>Assignment</code>.
|-
| Potential Redundant Tests in <code>participants_controller_spec.rb</code>
|| The tests on line 222 and 231 are redundant as only the authorization differs. (Note: This should be investigated to see whether or not this is necessary)
|-
| Checking for issues with the current testing files
|| The "Get Participant by ID call" test was returning a 201 status code instead of the more suitable 200 code
|}

For more detailed information on what prompts we used and the output we got, please visit the page here: [https://docs.google.com/document/d/105_U_Coky-edx7n-tFhD2B5RqmVXxEsKPW_qUaf7bQU/edit?usp=sharing].

=Requirements=
Objectives:
<ul>
<li>Apply DRY principles to eliminate redundant code.</li>
<li>Ensure adherence to SOLID principles for better maintainability.</li>
<li>Use appropriate design patterns to optimize code architecture.</li>
<li>Write clear, informative comments and use meaningful naming conventions.</li>
<li>Test the refactored code extensively with RSpec to verify functionality.</li>
</ul>
Deliverables:
<ul>
<li>Refactored code for participants_controller.rb and helper class.</li>
<li>Comprehensive test suite and coverage report.</li>
<li>Updated and detailed documentation.</li>
<li>Video demonstration of the API functionality.</li>
</ul>

==Existing Issues==
<ul>
<li>There are some API functions that are currently not functioning properly, making it somewhat difficult to test</li>
<li>Some API functions are not returning the correct HTML status messages (e.g. test on line 136 returns 201 instead of 200)</li>
<li>Documentation and comments can be somewhat vague</li>
<ul>
<li>In-line comments should be more descriptive, explaining what the code does in more details</li>
<li>Tests are not described via comments, but in name alone; some more descriptive comments that explain the tests in more detail would be ideal</li>
</ul>
<li>Eliminate instances of redundant code</li>
<li>The method naming should be more descriptive</li>

</ul>

=Design / Proposed Solution=

Based on the previous implementation's controller diagram, we have created a new version that contains our proposed changes and modifications to <code>participants_controller.rb</code>.

[[File:Participants_controller_refactor_v1.2.png]]

==Simplifying Redundant JSON Rendering Code==

Many of the functions in the current implementation contain a conditional if-else statement that determines what HTML status code is returned alongside any necessary values that are requested. Due to its simple nature, it might be possible to reduce the amount of space this takes up by implementing a private helper method that would shorten the process.

Example:

<syntaxhighlight lang=ruby line> if participants.nil?
render json: participants.errors, status: :unprocessable_entity
else
render json: participants, status: :ok
end</syntaxhighlight>

==Simplifying the Assignment of Participant Fields==

The <code>add()</code> and <code>update()</code> both take up a significant amount of space to assign values to database fields and are essentially the same in functionality (in terms of this specific section. We can remove redundancy by creating a method that can remove this redundancy.

Example

<syntaxhighlight lang=ruby line> permissions = retrieve_participant_permissions(authorization)

participant.authorization = authorization
participant.can_submit = permissions[:can_submit]
participant.can_review = permissions[:can_review]
participant.can_take_quiz = permissions[:can_take_quiz]
participant.can_mentor = permissions[:can_mentor]</syntaxhighlight>

==Provide More Clarity in Function Names==

There are some functions that are somewhat unclear/vague in <code>participants_controller.rb</code>. For example, the <code>list_user_participants()</code> and <code>list_assignment_participants()</code>.

=== - Suggested Method Name Improvements ===

{| class="wikitable"
! Old Method Name
! New Method Name
! Notes
|-
| <code>list_user_participants</code>
| <code>render_participants_by_user_id</code>
| Clearer and more descriptive
|-
| <code>list_assignment_participants</code>
| <code>render_participants_by_assignment_id</code>
| Clearer and more descriptive and is consistent with the other get method
|-
| <code>add</code>
| <code>add_participant_to_assignment</code>
| Describes both creation and authorization setup of participant to assignment
|-
| <code>filter_user_participants</code>
| <code>filter_participants_by_user</code>
| Highlights the purpose of the method
|-
| <code>filter_assignment_participants</code>
| <code>filter_participants_by_assignment</code>
| Highlights the purpose of the method

|}

==Improve Documentation and Comments==

Some of the documentation and in-line comments can be somewhat vague. This can lead to misconceptions about how some functions work or how some of the code can function. Below are potential improvements we plan to make for function descriptions, though these may change with the final implementation.

=== Improved Method Comments ===

{| class="wikitable"
! Method
! Original Comment
! Refactored Comment
|-
| render_participants_by_user_id
| Return a list of participants for a given user
| Retrieves all participants associated with the specified user ID
|-
| render_participants_by_assignment_id
| Return a list of participants for a given assignment
| Retrieves all participants linked to the specified assignment ID
|-
| show
| Return a specified participant
| Fetch and return the participant with the given ID
|-
| add_participant_to_assignment
| Assign the specified authorization to the participant and add them to an assignment
| Creates a new participant for a given assignment and assigns appropriate authorization and permissions
|-
| update_authorization
| Update the specified participant to the specified authorization
| Updates the participant’s authorization role and related permissions
|-
| destroy
| Delete a participant
| Deletes the participant identified by the given ID and returns a confirmation message
|-
| participant_params
| Permitted parameters for creating a Participant object
| Strong parameters: list of attributes allowed for participant creation or update
|-
| filter_participants_by_user
| Filters participants based on the provided user. Returns participants ordered by their IDs
| Returns a sorted list of participants filtered by user, if provided
|-
| filter_participants_by_assignment
| Filters participants based on the provided assignment. Returns participants ordered by their IDs
| Returns a sorted list of participants filtered by assignment, if provided
|-
| validate_authorization
| Validates that the authorization parameter is present and is one of the following valid authorizations: reader, reviewer, submitter, mentor
| Ensures authorization param is valid and returns it in lowercase; otherwise returns error response
|-
| find_user / find_assignment / find_participant
| Finds a user/assignment/participant by ID and returns it
| Fetches the corresponding record by ID; renders a not-found error if record does not exist
|}

==Proposed Testing Changes==

<ul>
<li>Add more descriptive comments for tests</li>
<li>Add test that checks that authorizations are updated correctly</li>
<li>Add test that checks that inputted path parameters are not missing and valid inputs</li>
<li>Tests at Line 222 and Line 231 are redundant, as the only difference in the test is the authorization, which would not affect what happens if a participant is not found</li>
</ul>

=Implementation=

As this is a refactoring project, most of our work on the codebase involved cleaning up the current codebase to better align with foundational code style principles rather than introducing any of kind of new functionality. Our primary focus is to make the code more readable and easier to work with than before. We also took the liberty of fixing some minor errors that we found along the way.

==Changelog==

<ul>
<li>Naming changes to multiple functions for better clarity and consistency</li>
<li>Changed HTML status message for <code>show()</code> from 201 (Created) to 200 (OK) as it is a better fit</li>
<li>Created the <code>assign_participant_permissions()</code> method</li>
<li>Introduced two additional tests and removed a redundant one (see Testing Plan for more details)</li>
<li>Removed redundant queries to <code>Participant.all()</code> in both filtering methods</li>
<li>Updated method comments to be more descriptive (see comments table in Design)</li>
</ul>

==Function Name Changes==

The previous implementation had several functions that were strangely named or had names that could be easily misconstrued. The name changes remain the same from the proposal and design section, but for the purpose of clarity, the rationale for each of the functions will be provided below.

===<code>list_user_participants</code> and <code>list_assignment_participants</code>===

These two functions are meant to render a list of participants given a <code>User</code> or <code>Assignment</code> respectively. Based on the name alone, it is difficult to tell that the function would render a User/Assignment or Participants. In order to remedy this, we chose the names <code>render_participants_by_user_id</code> and <code>render_participants_by_assignment_id</code>. The word "list" was replaced by "render" in order to better denote that it is rendering something (json in this case) and the "by" is added to emphasize that the User and Assignment are being used as parameters to search for the Participants. This provides a much clearer picture of what these functions should do compared to before.

===<code>add</code>===

The <code>add</code> function's name was too vague to be particularly useful in identifying its purpose. To be more accurate, the function was meant to add the user to a given assignment, which would return a participant from the assignment's <code>add_participant</code> function. The new name of the function provides much more context to what it does (<code>add_participant_to_assignment</code>).

===<code>filter_user_participants</code> and <code>filter_assignment_participants</code>===

Similar to the list methods that were previously mentioned, it is difficult to tell what exactly these two functions do. While it can be easily seen that it filters something, what is being filtered can be easily mistaken (e.g. does it filter users by participants or participants by users?). The new names, <code>filter_participants_by_user</code> and <code>filter_participants_by_assignment</code> are much clearer in defining that the User and Assignment are being used as the filter parameters for the function.

==HTML Status Code Change for <code>GET</code> Call==

The status code being used for this was previously 201, denoting "successful creation". We have corrected this to a simple 200 code, which signifies an "ok" status message. This issue was actually identified by ChatGPT while we were dowsing for potential issues.

Test modified

<syntaxhighlight lang=ruby line>
# Tests whether a participant returns properly if provided with a valid Participant ID
response '200', 'Returns a participant' do
let(:id) { participant2.id }

run_test! do |response|
data = JSON.parse(response.body)
expect(data['user_id']).to eq(studenta.id)
expect(data['assignment_id']).to eq(assignment2.id)
end
end
</syntaxhighlight>

==Redundant <code>Participant.all</code> Queries Removed==

This issue was initially caught by the LLM, ChatGPT, that the team was using in order to find potential issues. We found that simply using <code>Participant.where()</code> removed the need for the <code>Participant.all</code> query entirely while changing nothing else about the function, reducing the amount of queries necessary to call the filtering methods, <code>filter_participants_by_user</code> and <code>filter_participants_by_assignment</code>.

Example:

<syntaxhighlight lang=ruby line>
# New function
def filter_participants_by_user(user)
participants = Participant.where(user_id: user.id) if user # This would simply get the participants given the proper user ID
participants.order(:id)
end

# Old function
def filter_participants_by_user(user)
participants = Participant.all() # This would obtain the entire list of participants rather than just the necessary ones
participants = participants.where(user_id: user.id) if user
participants.order(:id)
end
</syntaxhighlight>

==New Private Method: <code>assign_participant_permissions()</code>==

The reasoning behind the addition of this method is because of a repeated piece of code that existed in the previous implementation:

<syntaxhighlight lang=ruby line>
permissions = retrieve_participant_permissions(authorization)

participant.authorization = authorization
participant.can_submit = permissions[:can_submit]
participant.can_review = permissions[:can_review]
participant.can_take_quiz = permissions[:can_take_quiz]
participant.can_mentor = permissions[:can_mentor]
</syntaxhighlight>

This was repeated in two different contexts: when the Participant was updated or created. This is a violation of the DRY principle, as the same code is repeated multiple times where it could have been reduced to make it more easily readable. In order to resolve this issue, we simply turned this code snippet into a private method that can be called within <code>participants_controller.rb</code>:

<syntaxhighlight lang=ruby line>
# An authorization string containing the participant's role is taken and used to determine
# what permissions will be allocated to the participant. Each of these permissions will
# then be assigned to the Participant's database permission attributes.
#
# @param [String] authorization: An authorization string that represents the participant's role
# @param [Participant] participant: The participant whose authorization permissions are being updated
def assign_participant_permissions(authorization, participant)
# Call helper method from participants_helper to retrieve a dictionary containing the
# appropriate permission boolean values for the role specified by the authorization string
permissions = retrieve_participant_permissions(authorization)

# Assigns each of the boolean permission values to their respective database counterparts
participant.authorization = authorization
participant.can_submit = permissions[:can_submit]
participant.can_review = permissions[:can_review]
participant.can_take_quiz = permissions[:can_take_quiz]
participant.can_mentor = permissions[:can_mentor]
end
</syntaxhighlight>

===Description:===

An authorization string containing the participant's role is taken and used to determine what permissions will be allocated to the participant. Each of these permissions will then be assigned to the Participant's database permission attributes.

===Parameters:===

<ul>
<li><code>authorization</code>: An authorization string that represents the participant's role. This can be either reader, reviewer, submitter, or mentor.</li>
<li><code>participant</code>: The participant whose attributes are being updated. This is passed in to be modified by the function to be used to assign each of the participant's attribute values that are representative of its assigned role.</li>
</ul>

===Behavior===

<ul>
<li>Use <code>retrieve_participant_permissions</code> from <code>participants_helper</code> in order to get all necessary permission boolean values for a given participant role</li>
<li>Assign each of the permission boolean values (<code>can_submit</code>, <code>can_review</code>, <code>can_take_quiz</code>, <code>can_mentor</code>)</li> from the helper method to their respective database attribute counterparts in Participant
</ul>

==Post-Demo Changes==

There were three notable topics that were brought up during the final demo presentation:

<ul>
<li>The renaming of <code>get_participants_by_user</code> and <code>get_participants_by_assignment</code> to something more suitable to its purpose in rendering the JSON of a list of participants</li>
<li>Consider the application of <code>find_user</code> and <code>find_assignment</code></li> within <code>participants_controller</code>
<li>Update the wiki to provide descriptions for each of the methods included in <code>participants_controller</code> (See Methods subsection in the Implementation section)</li>
</ul>

===Renaming <code>get_participants_by_user</code> and <code>get_participants_by_assignment</code>===

These two functions were renamed (once again) to something that better fit the functionality and purpose of the function. Since these functions are meant to render the lists of participants gotten from their respective parameters and use the ID values for each, both of the functions were renamed to <code>render_participants_by_user_id</code> and <code>render_participants_by_assignment_id</code> respectively. The renaming of the filter methods was also brought up, but those functions actually do use the objects themselves as parameters, so have been left as is for the time being.

===<code>find_user</code> and <code>find_assignment</code></li> within <code>participants_controller</code>===

We reconsidered the use of these methods within the controller since it was somewhat odd that it would have these methods. However, we concluded that, since the find methods are helper methods that are private and not open to be used by other parts of the code, to be fine to leave as is. This is mostly because they are simple helper methods that get the current user and assignment and return them, rendering an error if they do not exist.

==Methods==

===<code>render_participants_by_user_id</code>===

Description

Fetches all participants associated with the specified user.

Parameters

<ul>
<li><code>user_id [Integer]</code>: ID of the user</li>
</ul>

Returns

<ul>
<li>200 OK: A JSON array of participant objects</li>
<li>401 Unauthorized: If the user is not authorized for the action</li>
<li>404 Not Found: If the user does not exist</li>
<li>422 Unprocessable Entity: If the query fails unexpectedly</li>
</ul>

Notable Changes

<ul>
<li>Renamed from <code>list_user_participants</code> to <code>render_participants_by_user_id</code></li>
</ul>
Code

<syntaxhighlight lang=ruby line>
def render_participants_by_user_id
user = find_user if params[:user_id].present?
return if params[:user_id].present? && user.nil?

participants = filter_participants_by_user(user)

if participants.nil?
render json: participants.errors, status: :unprocessable_entity
else
render json: participants, status: :ok
end
end
</syntaxhighlight>

===<code>render_participants_by_assignment_id</code>===

Description

Fetches all participants associated with a specific assignment.

Parameters

<ul> <li><code>assignment_id [Integer]</code>: ID of the assignment</li> </ul>

Returns

<ul> <li>200 OK: A JSON array of participant objects</li> <li>401 Unauthorized: If the user is not authorized for the action</li> <li>404 Not Found: If the assignment does not exist</li> <li>422 Unprocessable Entity: If the query fails unexpectedly</li> </ul>

Notable Changes

<ul> <li>Renamed from <code>list_assignment_participants</code> to <code>render_participants_by_assignment_id</code></li> </ul>

Code

<syntaxhighlight lang=ruby line>
def render_participants_by_assignment_id
assignment = find_assignment if params[:assignment_id].present?
return if params[:assignment_id].present? && assignment.nil?

participants = filter_participants_by_assignment(assignment)

if participants.nil?
render json: participants.errors, status: :unprocessable_entity
else
render json: participants, status: :ok
end
end
</syntaxhighlight>

===<code>show</code>===

Description

Fetches the details of a specific participant by their ID.

Parameters

<ul> <li><code>id [Integer]</code>: ID of the participant</li> </ul>

Returns

<ul> <li>200 OK: JSON representation of the participant</li> <li>401 Unauthorized: If the user is not authorized</li> <li>404 Not Found: If the participant does not exist</li> <li>422 Unprocessable Entity: If the lookup fails</li> </ul>

Notable Changes

<ul> <li>Standardized participant lookup to return proper HTTP codes</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def show
participant = Participant.find(params[:id])

if participant.nil?
render json: participant.errors, status: :unprocessable_entity
else
render json: participant, status: :ok
end
end
</syntaxhighlight>

===<code>add_participant_to_assignment</code>===

Description

Adds a user as a participant to an assignment with the specified authorization (role and permissions).

Parameters

<ul> <li><code>participant[user_id] [Integer]</code>: ID of the user</li> <li><code>participant[assignment_id] [Integer]</code>: ID of the assignment</li> <li><code>authorization [String]</code>: Role assigned to the participant (reader, reviewer, submitter, mentor)</li> </ul>

Returns

<ul> <li>201 Created: Participant successfully added</li> <li>404 Not Found: If user or assignment is not found</li> <li>422 Unprocessable Entity: If authorization is invalid or save fails</li> </ul>

Notable Changes

<ul> <li>Introduced role-based permission assignment during participant creation</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def add_participant_to_assignment
user = find_user
return unless user

assignment = find_assignment
return unless assignment

authorization = validate_authorization
return unless authorization

participant = assignment.add_participant(user)
assign_participant_permissions(authorization, participant)

if participant.save
render json: participant, status: :created
else
render json: participant.errors, status: :unprocessable_entity
end
end
</syntaxhighlight>

===<code>update_authorization</code>===

Description

Updates the authorization (role) of an existing participant.

Parameters

<ul> <li><code>id [Integer]</code>: ID of the participant</li> <li><code>authorization [String]</code>: New role to assign (reader, reviewer, submitter, mentor)</li> </ul>

Returns

<ul> <li>201 Created: Authorization updated successfully</li> <li>401 Unauthorized: If the user is not authorized</li> <li>404 Not Found: If participant is not found</li> <li>422 Unprocessable Entity: If authorization is invalid</li> </ul>

Notable Changes

<ul> <li>Added validation for authorization role values</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def update_authorization
participant = find_participant
return unless participant

authorization = validate_authorization
return unless authorization

assign_participant_permissions(authorization, participant)

if participant.save
render json: participant, status: :created
else
render json: participant.errors, status: :unprocessable_entity
end
end
</syntaxhighlight>

===<code>destroy</code>===

Description

Deletes a participant from the system. Optionally includes assignment and team context in the success message.

Parameters

<ul> <li><code>id [Integer]</code>: ID of the participant</li> <li><code>assignment_id [Integer] (optional)</code></li> <li><code>team_id [Integer] (optional)</code></li> </ul>

Returns

<ul> <li>200 OK: Success message indicating deletion</li> <li>401 Unauthorized: If the user is not authorized</li> <li>404 Not Found: If participant is not found</li> <li>422 Unprocessable Entity: If deletion fails</li> </ul>

Notable Changes

<ul> <li>Enhanced success message based on team/assignment presence</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def destroy
participant = Participant.find_by(id: params[:id])

if participant.nil?
render json: { error: 'Not Found' }, status: :not_found
elsif participant.destroy
successful_deletion_message = if params[:team_id].nil?
"Participant #{params[:id]} in Assignment #{params[:assignment_id]} has been deleted successfully!"
else
"Participant #{params[:id]} in Team #{params[:team_id]} of Assignment #{params[:assignment_id]} has been deleted successfully!"
end
render json: { message: successful_deletion_message }, status: :ok
else
render json: participant.errors, status: :unprocessable_entity
end
end
</syntaxhighlight>

===<code>participants_params</code>===

Description

Defines the strong parameters allowed when creating or updating a participant.

Parameters

<ul> <li><code>participant</code>: Hash containing fields like user_id, assignment_id, authorization, etc.</li> </ul>

Returns

<ul> <li>Permitted parameter hash for participant creation/update</li> </ul>

Notable Changes

<ul> <li>Updated to include all permission and assignment-related fields</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def participant_params
params.require(:participant).permit(:user_id, :assignment_id, :authorization, :can_submit,
:can_review, :can_take_quiz, :can_mentor, :handle,
:team_id, :join_team_request_id, :permission_granted,
:topic, :current_stage, :stage_deadline)
end
</syntaxhighlight>

===<code>filter_participants_by_user</code>===

Description

Fetches participants associated with a given user, ordered by ID.

Parameters

<ul> <li><code>user [User]</code>: User object</li> </ul>

Returns

<ul> <li>Ordered list of participants for the user</li> </ul>

Notable Changes

<ul> <li>None</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def filter_participants_by_user(user)
participants = Participant.where(user_id: user.id) if user
participants.order(:id)
end
</syntaxhighlight>

===<code>filter_participants_by_assignment</code>===

Description

Fetches participants associated with a given assignment, ordered by ID.

Parameters

<ul> <li><code>assignment [Assignment]</code>: Assignment object</li> </ul>

Returns

<ul> <li>Ordered list of participants for the assignment</li> </ul>

Notable Changes

<ul> <li>None</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def filter_participants_by_assignment(assignment)
participants = Participant.where(assignment_id: assignment.id) if assignment
participants.order(:id)
end
</syntaxhighlight>

===<code>find_user</code>===

Description

Finds a user based on the provided user_id.

Parameters

<ul> <li><code>user_id [Integer]</code>: ID of the user</li> </ul>

Returns

<ul> <li>User object if found</li> <li>404 error if not found</li> </ul>

Notable Changes

<ul> <li>Centralized user lookup and error handling</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def find_user
user_id = params[:user_id]
user = User.find_by(id: user_id)
render json: { error: 'User not found' }, status: :not_found unless user
user
end
</syntaxhighlight>

===<code>find_assignment</code>===

Description

Finds an assignment based on the provided assignment_id.

Parameters

<ul> <li><code>assignment_id [Integer]</code>: ID of the assignment</li> </ul>

Returns

<ul> <li>Assignment object if found</li> <li>404 error if not found</li> </ul>

Notable Changes

<ul> <li>Centralized assignment lookup and error handling</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def find_assignment
assignment_id = params[:assignment_id]
assignment = Assignment.find_by(id: assignment_id)
render json: { error: 'Assignment not found' }, status: :not_found unless assignment
assignment
end
</syntaxhighlight>

===<code>find_participant</code>===

Description

Finds a participant based on the provided ID.

Parameters

<ul> <li><code>id [Integer]</code>: ID of the participant</li> </ul>

Returns

<ul> <li>Participant object if found</li> <li>404 error if not found</li> </ul>

Notable Changes

<ul> <li>Centralized participant lookup and error handling</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def find_participant
participant_id = params[:id]
participant = Participant.find_by(id: participant_id)
render json: { error: 'Participant not found' }, status: :not_found unless participant
participant
end
</syntaxhighlight>

===<code>assign_participant_permissions</code>===

Description

Assigns permission flags to a participant based on the authorization role provided.

Parameters

<ul> <li><code>authorization [String]</code>: Role to assign</li> <li><code>participant [Participant]</code>: Participant object</li> </ul>

Returns

<ul> <li>Participant object with updated permissions</li> </ul>

Notable Changes

<ul> <li>Added dynamic permission setting based on role</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def assign_participant_permissions(authorization, participant)
# Call helper method from participants_helper to retrieve a dictionary containing the
# appropriate permission boolean values for the role specified by the authorization string
permissions = retrieve_participant_permissions(authorization)

# Assigns each of the boolean permission values to their respective database counterparts
participant.authorization = authorization
participant.can_submit = permissions[:can_submit]
participant.can_review = permissions[:can_review]
participant.can_take_quiz = permissions[:can_take_quiz]
participant.can_mentor = permissions[:can_mentor]
end
</syntaxhighlight>

===<code>validate_authorization</code>===

Description

Validates that the authorization string is present and one of the accepted roles.

Parameters

<ul> <li><code>authorization [String]</code>: Authorization role</li> </ul>

Returns

<ul> <li>Validated authorization string</li> <li>422 error if invalid</li> </ul>

Notable Changes

<ul> <li>Standardized authorization validation across endpoints</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def validate_authorization
valid_authorizations = %w[reader reviewer submitter mentor]
authorization = params[:authorization]
authorization = authorization.downcase if authorization.present?

unless authorization
render json: { error: 'authorization is required' }, status: :unprocessable_entity
return
end

unless valid_authorizations.include?(authorization)
render json: { error: 'authorization not valid. Valid authorizations are: Reader, Reviewer, Submitter, Mentor' },
status: :unprocessable_entity
return
end

authorization
end
</syntaxhighlight>

=Testing Plan=

Of this implementation, also existing 25 tests are passing. We have also given each test their respective IDs within <code>participants_controller_spec.rb</code> as well so that they may be more easily identifiable. For more information about the previous testing plan, please refer to the previous implementation's page here: [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2484._Reimplement_participants_controller.rb]

Below are any modifications to the existing test file (<code>participants_controller_spec.rb</code>) that we have made during the course of this project, alongside the descriptions and rationales behind them:

==Tests==

Below are the tests that are included in this implementation. We have updated the test descriptions to include more accurate and detailed information about each of the tests as well. Any tests that have been modified or new will be specified as such:

{| class="wikitable" style="margin-left:40px"
|-
! Test ID !! Test Description
|-
| 1 || Retrieve participants by valid user ID (should return participant data)
|-
| 2 || Retrieve participants by user ID with no participants (should return empty array)
|-
| 3 || Retrieve participants with non-existent user ID (should return 'User not found')
|-
| 4 || Retrieve participants by user ID with invalid token (should return 'Not Authorized')
|-
| 5 || Retrieve participants by valid assignment ID (should return participant data)
|-
| 6 || Retrieve participants by non-existent assignment ID (should return 'Assignment not found')
|-
| 7 || Retrieve participants by assignment ID with invalid token (should return 'Not Authorized')
|-
| 8 || Retrieve a participant by valid ID (should return participant details)
|-
| 9 || Retrieve a participant by non-existent ID (should return 'Not Found')
|-
| 10 || Retrieve a participant by ID with invalid token (should return 'Not Authorized')
|-
| 11 || Delete a participant by valid ID (should return deletion success message)
|-
| 12 || Delete a participant by non-existent ID (should return 'Not Found')
|-
| 13 || Delete a participant by ID with invalid token (should return 'Not Authorized')
|-
| 14 || Update participant authorization with valid data (should return updated authorization)
|-
| 15 || Update participant authorization with non-existent participant ID (should return 'Participant not found')
|-
| 16 || Update participant authorization with invalid role (should return 'authorization not valid')
|-
| 17 || Update participant authorization with invalid token (should return 'Not Authorized')
|-
| 18 || Add a participant successfully (should return participant data with authorization)
|-
| 19 || Add a participant that already exists (should return duplicate participant error)
|-
| 20 || Add a participant with non-existent user ID (should return 'User not found')
|-
| 21 || Add a participant with non-existent assignment ID (should return 'Assignment not found')
|-
| 22 || Add a participant with invalid authorization (should return 'authorization not valid')
|-
| 23 || Add a participant with unsupported authorization format (should return 'authorization not valid')
|-
| 24 (NEW) || Add a participant missing user_id in request body (should return 'User not found')
|-
| 25 (NEW) || Add a participant missing assignment_id in request body (should return 'Assignment not found')
|}

==Removed Tests==

These are any tests that we have modified or removed from the previous testing plan. If the test ID is denoted by (Previously), that means that the ID shown was part of the previous implementation's testing plan.

{| class="wikitable" style="margin-left:40px"
|-
! Test ID !! Modification Description
|-
| (Previously) 22 || This test was removed as it was redundant. While it is important to check the authorization of the participant that would be invalid, the invalid ID used for this test is a duplicate of the previous test, meaning the result is guaranteed to match that of the previous test regardless of what is meant to be tested.
|}

=Next Steps=

Being able to implement this could potentially simplify rendering to the view somewhat in that it could handle simple HTML status code handling. Below are some examples of implementations to serve as a point of reference:

===Example 1===

<syntaxhighlight lang=ruby line>
# Checks if a target object (participant or participants) is not nil and then renders the object.
# If the object is nil, renders the object errors and sends a not_found_status and if the object
# exists, renders the object and sends a success status
# not_found_status default: :unprocessable_entity (422)
# success_status default: :ok (200)
def render_object_or_error(object, not_found_status: :unprocessable_entity, success_status: :ok)
if object.nil?
render json: { error: 'Resource not found' }, status: not_found_status
elsif object.respond_to?(:errors) && object.errors.any?
render json: object.errors, status: :unprocessable_entity
else
render json: object, status: success_status
end
</syntaxhighlight>

This example is modeled to be specific to the most common use case for this function in the <code>participants_controller.rb</code> by returning the default 422 and 200 error and success codes that are used by three instances of JSON rendering where it checks for whether a list of participants or a single participant is nil. These default values for the status codes are mainly to cover those instances, but could be changed to something else if necessary. The <code>object</code> parameter is representative of the object that was meant to be rendered given the success or failure of the operation.

===Example 2===

<syntaxhighlight lang=ruby line>
def render_object_if(conditional, object, error_status, success_status)
if conditional
render json: { error: 'Resource not found' }, status: error_status
else
render json: object, status: success_status
end
</syntaxhighlight>

This example is a more generic implementation of the function, mandating the error and success status codes rather than providing default values. The point of this was to emphasize readability when glancing over the use of this function. For example, being able to tell that seeing the function being used would immediately tell the reader what the success and failure states were immediately without having to find and inspect the function itself. The <code>conditional</code> parameter would also allow the function to act similarly to a more readable ternary statement made for rendering.

Implementing this successfully would reduce the amount of repetitive code being used within the controller, as the if-else view rendering is very common in <code>participants_controller.rb</code>. We were unable to implement it within our given timeframe, so we opted to divert our focus on other, important tasks that we needed to do.

=Team=
'''Mentor'''

*Aniruddha Rajnekar <aarajnek@ncsu.edu>

'''Students'''

*Akhil Adusumilli <aadusum@ncsu.edu>

*Vansh Dodiya <vkdodiya@ncsu.edu>

*Brian Huynh <bhhuynh@ncsu.edu>

= Relevant Links =

Pull Request [https://github.com/expertiza/reimplementation-back-end/pull/192] 
GitHub Repository [https://github.com/Vansh17/refactoring-participants-controller.git] 
GitHub Project Board [https://github.com/users/Vansh17/projects/2] 
<code>participants_controller.rb</code> in Old Expertiza [https://github.com/expertiza/expertiza/blob/main/app/controllers/participants_controller.rb] 
<code>participants_helper.rb</code> in Old Expertiza [https://github.com/expertiza/expertiza/blob/main/app/helpers/participants_helper.rb]

CSC/ECE 517 Spring 2025 - E2531 Refactor participants controller.rb

2025-04-27T19:24:20Z

Vkdodiya: /* Methods (TEMP) */

=Introduction=
From the project description: "This project aims to refactor the <code>participants_controller.rb</code> and its helper class, <code>participants_helper.rb</code>, in the Expertiza system. The focus will be on improving code structure by implementing DRY and SOLID principles, enhancing readability with meaningful comments and clear naming conventions, and ensuring robustness through comprehensive RSpec testing." Since this is a refactoring project, we will also be utilizing Large Language Models (LLMs) to aid in development. More information on how we used them can be found in the section below.

==Video Overview==

https://youtu.be/4kfz0hrmSg4

Note: In the video it shows the test file at the end, but does not mention a last-minute change that numbers all of the tests to make it much easier to keep track of each of the tests and which ones are passing.

=Use of Large Language Models (LLMs)=

For this project, we are using ChatGPT as an LLM helper in determining what issues there are within the code. The use of LLMs in this project will likely be limited to probing for potential issues that exist within the system.

Below we have organized the following prompts and a summary of the output in a table:

{| class="wikitable" style="margin-left:40px"
|-
! style="width: 25%" | Prompts !! LLM Output Summary
|-
| [Code from <code>participants_controller.rb</code>] Are there any ways where we can refactor the code to improve readability, DRYness, and clarity of error handling?
|| It recognized some of the issues we, as a team, had already identified and suggested fixes that were similar to what we outlined: Redundant JSON Rendering Code[https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2025_-_E2531_Refactor_participants_controller.rb#Simplifying_Redundant_JSON_Rendering_Code] and Simplifying the Assignment of Participant Fields[https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2025_-_E2531_Refactor_participants_controller.rb#Simplifying_the_Assignment_of_Participant_Fields]. Additionally, it suggested minor changes that we could implement, such as using <code>Participant.where(...)</code> instead of <code>Participant.all</code> to filter out the code more efficiently instead of getting all database instances every time, as well as the use of strong parameters in <code>add()</code> and <code>update_authorization()</code> to avoid having to implement custom parsing techniques. It also recommends renaming the <code>add()</code> function to something more specific in relation to its purpose (adding a <code>Participant</code> to an <code>Assignment</code>.
|-
| Potential Redundant Tests in <code>participants_controller_spec.rb</code>
|| The tests on line 222 and 231 are redundant as only the authorization differs. (Note: This should be investigated to see whether or not this is necessary)
|-
| Checking for issues with the current testing files
|| The "Get Participant by ID call" test was returning a 201 status code instead of the more suitable 200 code
|}

For more detailed information on what prompts we used and the output we got, please visit the page here: [https://docs.google.com/document/d/105_U_Coky-edx7n-tFhD2B5RqmVXxEsKPW_qUaf7bQU/edit?usp=sharing].

=Requirements=
Objectives:
<ul>
<li>Apply DRY principles to eliminate redundant code.</li>
<li>Ensure adherence to SOLID principles for better maintainability.</li>
<li>Use appropriate design patterns to optimize code architecture.</li>
<li>Write clear, informative comments and use meaningful naming conventions.</li>
<li>Test the refactored code extensively with RSpec to verify functionality.</li>
</ul>
Deliverables:
<ul>
<li>Refactored code for participants_controller.rb and helper class.</li>
<li>Comprehensive test suite and coverage report.</li>
<li>Updated and detailed documentation.</li>
<li>Video demonstration of the API functionality.</li>
</ul>

==Existing Issues==
<ul>
<li>There are some API functions that are currently not functioning properly, making it somewhat difficult to test</li>
<li>Some API functions are not returning the correct HTML status messages (e.g. test on line 136 returns 201 instead of 200)</li>
<li>Documentation and comments can be somewhat vague</li>
<ul>
<li>In-line comments should be more descriptive, explaining what the code does in more details</li>
<li>Tests are not described via comments, but in name alone; some more descriptive comments that explain the tests in more detail would be ideal</li>
</ul>
<li>Eliminate instances of redundant code</li>
<li>The method naming should be more descriptive</li>

</ul>

=Design / Proposed Solution=

Based on the previous implementation's controller diagram, we have created a new version that contains our proposed changes and modifications to <code>participants_controller.rb</code>.

[[File:Participants_controller_refactor_v1.2.png]]

==Simplifying Redundant JSON Rendering Code==

Many of the functions in the current implementation contain a conditional if-else statement that determines what HTML status code is returned alongside any necessary values that are requested. Due to its simple nature, it might be possible to reduce the amount of space this takes up by implementing a private helper method that would shorten the process.

Example:

<syntaxhighlight lang=ruby line> if participants.nil?
render json: participants.errors, status: :unprocessable_entity
else
render json: participants, status: :ok
end</syntaxhighlight>

==Simplifying the Assignment of Participant Fields==

The <code>add()</code> and <code>update()</code> both take up a significant amount of space to assign values to database fields and are essentially the same in functionality (in terms of this specific section. We can remove redundancy by creating a method that can remove this redundancy.

Example

<syntaxhighlight lang=ruby line> permissions = retrieve_participant_permissions(authorization)

participant.authorization = authorization
participant.can_submit = permissions[:can_submit]
participant.can_review = permissions[:can_review]
participant.can_take_quiz = permissions[:can_take_quiz]
participant.can_mentor = permissions[:can_mentor]</syntaxhighlight>

==Provide More Clarity in Function Names==

There are some functions that are somewhat unclear/vague in <code>participants_controller.rb</code>. For example, the <code>list_user_participants()</code> and <code>list_assignment_participants()</code>.

=== - Suggested Method Name Improvements ===

{| class="wikitable"
! Old Method Name
! New Method Name
! Notes
|-
| <code>list_user_participants</code>
| <code>render_participants_by_user_id</code>
| Clearer and more descriptive
|-
| <code>list_assignment_participants</code>
| <code>render_participants_by_assignment_id</code>
| Clearer and more descriptive and is consistent with the other get method
|-
| <code>add</code>
| <code>add_participant_to_assignment</code>
| Describes both creation and authorization setup of participant to assignment
|-
| <code>filter_user_participants</code>
| <code>filter_participants_by_user</code>
| Highlights the purpose of the method
|-
| <code>filter_assignment_participants</code>
| <code>filter_participants_by_assignment</code>
| Highlights the purpose of the method

|}

==Improve Documentation and Comments==

Some of the documentation and in-line comments can be somewhat vague. This can lead to misconceptions about how some functions work or how some of the code can function. Below are potential improvements we plan to make for function descriptions, though these may change with the final implementation.

=== Improved Method Comments ===

{| class="wikitable"
! Method
! Original Comment
! Refactored Comment
|-
| render_participants_by_user_id
| Return a list of participants for a given user
| Retrieves all participants associated with the specified user ID
|-
| render_participants_by_assignment_id
| Return a list of participants for a given assignment
| Retrieves all participants linked to the specified assignment ID
|-
| show
| Return a specified participant
| Fetch and return the participant with the given ID
|-
| add_participant_to_assignment
| Assign the specified authorization to the participant and add them to an assignment
| Creates a new participant for a given assignment and assigns appropriate authorization and permissions
|-
| update_authorization
| Update the specified participant to the specified authorization
| Updates the participant’s authorization role and related permissions
|-
| destroy
| Delete a participant
| Deletes the participant identified by the given ID and returns a confirmation message
|-
| participant_params
| Permitted parameters for creating a Participant object
| Strong parameters: list of attributes allowed for participant creation or update
|-
| filter_participants_by_user
| Filters participants based on the provided user. Returns participants ordered by their IDs
| Returns a sorted list of participants filtered by user, if provided
|-
| filter_participants_by_assignment
| Filters participants based on the provided assignment. Returns participants ordered by their IDs
| Returns a sorted list of participants filtered by assignment, if provided
|-
| validate_authorization
| Validates that the authorization parameter is present and is one of the following valid authorizations: reader, reviewer, submitter, mentor
| Ensures authorization param is valid and returns it in lowercase; otherwise returns error response
|-
| find_user / find_assignment / find_participant
| Finds a user/assignment/participant by ID and returns it
| Fetches the corresponding record by ID; renders a not-found error if record does not exist
|}

==Proposed Testing Changes==

<ul>
<li>Add more descriptive comments for tests</li>
<li>Add test that checks that authorizations are updated correctly</li>
<li>Add test that checks that inputted path parameters are not missing and valid inputs</li>
<li>Tests at Line 222 and Line 231 are redundant, as the only difference in the test is the authorization, which would not affect what happens if a participant is not found</li>
</ul>

=Implementation=

As this is a refactoring project, most of our work on the codebase involved cleaning up the current codebase to better align with foundational code style principles rather than introducing any of kind of new functionality. Our primary focus is to make the code more readable and easier to work with than before. We also took the liberty of fixing some minor errors that we found along the way.

==Changelog==

<ul>
<li>Naming changes to multiple functions for better clarity and consistency</li>
<li>Changed HTML status message for <code>show()</code> from 201 (Created) to 200 (OK) as it is a better fit</li>
<li>Created the <code>assign_participant_permissions()</code> method</li>
<li>Introduced two additional tests and removed a redundant one (see Testing Plan for more details)</li>
<li>Removed redundant queries to <code>Participant.all()</code> in both filtering methods</li>
<li>Updated method comments to be more descriptive (see comments table in Design)</li>
</ul>

==Function Name Changes==

The previous implementation had several functions that were strangely named or had names that could be easily misconstrued. The name changes remain the same from the proposal and design section, but for the purpose of clarity, the rationale for each of the functions will be provided below.

===<code>list_user_participants</code> and <code>list_assignment_participants</code>===

These two functions are meant to render a list of participants given a <code>User</code> or <code>Assignment</code> respectively. Based on the name alone, it is difficult to tell that the function would render a User/Assignment or Participants. In order to remedy this, we chose the names <code>render_participants_by_user_id</code> and <code>render_participants_by_assignment_id</code>. The word "list" was replaced by "render" in order to better denote that it is rendering something (json in this case) and the "by" is added to emphasize that the User and Assignment are being used as parameters to search for the Participants. This provides a much clearer picture of what these functions should do compared to before.

===<code>add</code>===

The <code>add</code> function's name was too vague to be particularly useful in identifying its purpose. To be more accurate, the function was meant to add the user to a given assignment, which would return a participant from the assignment's <code>add_participant</code> function. The new name of the function provides much more context to what it does (<code>add_participant_to_assignment</code>).

===<code>filter_user_participants</code> and <code>filter_assignment_participants</code>===

Similar to the list methods that were previously mentioned, it is difficult to tell what exactly these two functions do. While it can be easily seen that it filters something, what is being filtered can be easily mistaken (e.g. does it filter users by participants or participants by users?). The new names, <code>filter_participants_by_user</code> and <code>filter_participants_by_assignment</code> are much clearer in defining that the User and Assignment are being used as the filter parameters for the function.

==HTML Status Code Change for <code>GET</code> Call==

The status code being used for this was previously 201, denoting "successful creation". We have corrected this to a simple 200 code, which signifies an "ok" status message. This issue was actually identified by ChatGPT while we were dowsing for potential issues.

Test modified

<syntaxhighlight lang=ruby line>
# Tests whether a participant returns properly if provided with a valid Participant ID
response '200', 'Returns a participant' do
let(:id) { participant2.id }

run_test! do |response|
data = JSON.parse(response.body)
expect(data['user_id']).to eq(studenta.id)
expect(data['assignment_id']).to eq(assignment2.id)
end
end
</syntaxhighlight>

==Redundant <code>Participant.all</code> Queries Removed==

This issue was initially caught by the LLM, ChatGPT, that the team was using in order to find potential issues. We found that simply using <code>Participant.where()</code> removed the need for the <code>Participant.all</code> query entirely while changing nothing else about the function, reducing the amount of queries necessary to call the filtering methods, <code>filter_participants_by_user</code> and <code>filter_participants_by_assignment</code>.

Example:

<syntaxhighlight lang=ruby line>
# New function
def filter_participants_by_user(user)
participants = Participant.where(user_id: user.id) if user # This would simply get the participants given the proper user ID
participants.order(:id)
end

# Old function
def filter_participants_by_user(user)
participants = Participant.all() # This would obtain the entire list of participants rather than just the necessary ones
participants = participants.where(user_id: user.id) if user
participants.order(:id)
end
</syntaxhighlight>

==New Private Method: <code>assign_participant_permissions()</code>==

The reasoning behind the addition of this method is because of a repeated piece of code that existed in the previous implementation:

<syntaxhighlight lang=ruby line>
permissions = retrieve_participant_permissions(authorization)

participant.authorization = authorization
participant.can_submit = permissions[:can_submit]
participant.can_review = permissions[:can_review]
participant.can_take_quiz = permissions[:can_take_quiz]
participant.can_mentor = permissions[:can_mentor]
</syntaxhighlight>

This was repeated in two different contexts: when the Participant was updated or created. This is a violation of the DRY principle, as the same code is repeated multiple times where it could have been reduced to make it more easily readable. In order to resolve this issue, we simply turned this code snippet into a private method that can be called within <code>participants_controller.rb</code>:

<syntaxhighlight lang=ruby line>
# An authorization string containing the participant's role is taken and used to determine
# what permissions will be allocated to the participant. Each of these permissions will
# then be assigned to the Participant's database permission attributes.
#
# @param [String] authorization: An authorization string that represents the participant's role
# @param [Participant] participant: The participant whose authorization permissions are being updated
def assign_participant_permissions(authorization, participant)
# Call helper method from participants_helper to retrieve a dictionary containing the
# appropriate permission boolean values for the role specified by the authorization string
permissions = retrieve_participant_permissions(authorization)

# Assigns each of the boolean permission values to their respective database counterparts
participant.authorization = authorization
participant.can_submit = permissions[:can_submit]
participant.can_review = permissions[:can_review]
participant.can_take_quiz = permissions[:can_take_quiz]
participant.can_mentor = permissions[:can_mentor]
end
</syntaxhighlight>

===Description:===

An authorization string containing the participant's role is taken and used to determine what permissions will be allocated to the participant. Each of these permissions will then be assigned to the Participant's database permission attributes.

===Parameters:===

<ul>
<li><code>authorization</code>: An authorization string that represents the participant's role. This can be either reader, reviewer, submitter, or mentor.</li>
<li><code>participant</code>: The participant whose attributes are being updated. This is passed in to be modified by the function to be used to assign each of the participant's attribute values that are representative of its assigned role.</li>
</ul>

===Behavior===

<ul>
<li>Use <code>retrieve_participant_permissions</code> from <code>participants_helper</code> in order to get all necessary permission boolean values for a given participant role</li>
<li>Assign each of the permission boolean values (<code>can_submit</code>, <code>can_review</code>, <code>can_take_quiz</code>, <code>can_mentor</code>)</li> from the helper method to their respective database attribute counterparts in Participant
</ul>

==Post-Demo Changes==

There were three notable topics that were brought up during the final demo presentation:

<ul>
<li>The renaming of <code>get_participants_by_user</code> and <code>get_participants_by_assignment</code> to something more suitable to its purpose in rendering the JSON of a list of participants</li>
<li>Consider the application of <code>find_user</code> and <code>find_assignment</code></li> within <code>participants_controller</code>
<li>Update the wiki to provide descriptions for each of the methods included in <code>participants_controller</code> (See Methods subsection in the Implementation section)</li>
</ul>

===Renaming <code>get_participants_by_user</code> and <code>get_participants_by_assignment</code>===

These two functions were renamed (once again) to something that better fit the functionality and purpose of the function. Since these functions are meant to render the lists of participants gotten from their respective parameters and use the ID values for each, both of the functions were renamed to <code>render_participants_by_user_id</code> and <code>render_participants_by_assignment_id</code> respectively. The renaming of the filter methods was also brought up, but those functions actually do use the objects themselves as parameters, so have been left as is for the time being.

===<code>find_user</code> and <code>find_assignment</code></li> within <code>participants_controller</code>===

We reconsidered the use of these methods within the controller since it was somewhat odd that it would have these methods. However, we concluded that, since the find methods are helper methods that are private and not open to be used by other parts of the code, to be fine to leave as is. This is mostly because they are simple helper methods that get the current user and assignment and return them, rendering an error if they do not exist.

==Methods (TEMP)==

===<code>render_participants_by_user_id</code>===

Description

Fetches all participants associated with the specified user.

Parameters

<ul>
<li><code>user_id [Integer]</code>: ID of the user</li>
</ul>

Returns

<ul>
<li>200 OK: A JSON array of participant objects</li>
<li>401 Unauthorized: If the user is not authorized for the action</li>
<li>404 Not Found: If the user does not exist</li>
<li>422 Unprocessable Entity: If the query fails unexpectedly</li>
</ul>

Notable Changes

<ul>
<li>Renamed from <code>list_user_participants</code> to <code>render_participants_by_user_id</code></li>
</ul>
Code

<syntaxhighlight lang=ruby line>
def render_participants_by_user_id
user = find_user if params[:user_id].present?
return if params[:user_id].present? && user.nil?

participants = filter_participants_by_user(user)

if participants.nil?
render json: participants.errors, status: :unprocessable_entity
else
render json: participants, status: :ok
end
end
</syntaxhighlight>

===<code>render_participants_by_assignment_id</code>===

Description

Fetches all participants associated with a specific assignment.

Parameters

<ul> <li><code>assignment_id [Integer]</code>: ID of the assignment</li> </ul>

Returns

<ul> <li>200 OK: A JSON array of participant objects</li> <li>401 Unauthorized: If the user is not authorized for the action</li> <li>404 Not Found: If the assignment does not exist</li> <li>422 Unprocessable Entity: If the query fails unexpectedly</li> </ul>

Notable Changes

<ul> <li>Renamed from <code>list_assignment_participants</code> to <code>render_participants_by_assignment_id</code></li> </ul>

Code

<syntaxhighlight lang=ruby line>
def render_participants_by_assignment_id
assignment = find_assignment if params[:assignment_id].present?
return if params[:assignment_id].present? && assignment.nil?

participants = filter_participants_by_assignment(assignment)

if participants.nil?
render json: participants.errors, status: :unprocessable_entity
else
render json: participants, status: :ok
end
end
</syntaxhighlight>

===<code>show</code>===

Description

Fetches the details of a specific participant by their ID.

Parameters

<ul> <li><code>id [Integer]</code>: ID of the participant</li> </ul>

Returns

<ul> <li>200 OK: JSON representation of the participant</li> <li>401 Unauthorized: If the user is not authorized</li> <li>404 Not Found: If the participant does not exist</li> <li>422 Unprocessable Entity: If the lookup fails</li> </ul>

Notable Changes

<ul> <li>Standardized participant lookup to return proper HTTP codes</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def show
participant = Participant.find(params[:id])

if participant.nil?
render json: participant.errors, status: :unprocessable_entity
else
render json: participant, status: :ok
end
end
</syntaxhighlight>

===<code>add_participant_to_assignment</code>===

Description

Adds a user as a participant to an assignment with the specified authorization (role and permissions).

Parameters

<ul> <li><code>participant[user_id] [Integer]</code>: ID of the user</li> <li><code>participant[assignment_id] [Integer]</code>: ID of the assignment</li> <li><code>authorization [String]</code>: Role assigned to the participant (reader, reviewer, submitter, mentor)</li> </ul>

Returns

<ul> <li>201 Created: Participant successfully added</li> <li>404 Not Found: If user or assignment is not found</li> <li>422 Unprocessable Entity: If authorization is invalid or save fails</li> </ul>

Notable Changes

<ul> <li>Introduced role-based permission assignment during participant creation</li> </ul>

Code

<syntaxhighlight lang=ruby line>
def add_participant_to_assignment
user = find_user
return unless user

assignment = find_assignment
return unless assignment

authorization = validate_authorization
return unless authorization

participant = assignment.add_participant(user)
assign_participant_permissions(authorization, participant)

if participant.save
render json: participant, status: :created
else
render json: participant.errors, status: :unprocessable_entity
end
end
</syntaxhighlight>

===<code>update_authorization</code>===

Description

Parameters

Returns

Notable Changes

Code

<syntaxhighlight lang=ruby line>
def update_authorization
participant = find_participant
return unless participant

authorization = validate_authorization
return unless authorization

assign_participant_permissions(authorization, participant)

if participant.save
render json: participant, status: :created
else
render json: participant.errors, status: :unprocessable_entity
end
end
</syntaxhighlight>

===<code>destroy</code>===

Description

Parameters

Returns

Notable Changes

Code

<syntaxhighlight lang=ruby line>
def destroy
participant = Participant.find_by(id: params[:id])

if participant.nil?
render json: { error: 'Not Found' }, status: :not_found
elsif participant.destroy
successful_deletion_message = if params[:team_id].nil?
"Participant #{params[:id]} in Assignment #{params[:assignment_id]} has been deleted successfully!"
else
"Participant #{params[:id]} in Team #{params[:team_id]} of Assignment #{params[:assignment_id]} has been deleted successfully!"
end
render json: { message: successful_deletion_message }, status: :ok
else
render json: participant.errors, status: :unprocessable_entity
end
end
</syntaxhighlight>

===<code>participants_params</code>===

Description

Parameters

Returns

Notable Changes

Code

<syntaxhighlight lang=ruby line>
def participant_params
params.require(:participant).permit(:user_id, :assignment_id, :authorization, :can_submit,
:can_review, :can_take_quiz, :can_mentor, :handle,
:team_id, :join_team_request_id, :permission_granted,
:topic, :current_stage, :stage_deadline)
end
</syntaxhighlight>

===<code>filter_participants_by_user</code>===

Description

Parameters

Returns

Notable Changes

Code

<syntaxhighlight lang=ruby line>
def filter_participants_by_user(user)
participants = Participant.where(user_id: user.id) if user
participants.order(:id)
end
</syntaxhighlight>

===<code>filter_participants_by_assignment</code>===

Description

Parameters

Returns

Notable Changes

Code

<syntaxhighlight lang=ruby line>
def filter_participants_by_assignment(assignment)
participants = Participant.where(assignment_id: assignment.id) if assignment
participants.order(:id)
end
</syntaxhighlight>

===<code>find_user</code>===

Description

Parameters

Returns

Notable Changes

Code

<syntaxhighlight lang=ruby line>
def find_user
user_id = params[:user_id]
user = User.find_by(id: user_id)
render json: { error: 'User not found' }, status: :not_found unless user
user
end
</syntaxhighlight>

===<code>find_assignment</code>===

Description

Parameters

Returns

Notable Changes

Code

<syntaxhighlight lang=ruby line>
def find_assignment
assignment_id = params[:assignment_id]
assignment = Assignment.find_by(id: assignment_id)
render json: { error: 'Assignment not found' }, status: :not_found unless assignment
assignment
end
</syntaxhighlight>

===<code>find_participant</code>===

Description

Parameters

Returns

Notable Changes

Code

<syntaxhighlight lang=ruby line>
def find_participant
participant_id = params[:id]
participant = Participant.find_by(id: participant_id)
render json: { error: 'Participant not found' }, status: :not_found unless participant
participant
end
</syntaxhighlight>

===<code>assign_participant_permissions</code>===

Description

Parameters

Returns

Code

<syntaxhighlight lang=ruby line>
def assign_participant_permissions(authorization, participant)
# Call helper method from participants_helper to retrieve a dictionary containing the
# appropriate permission boolean values for the role specified by the authorization string
permissions = retrieve_participant_permissions(authorization)

# Assigns each of the boolean permission values to their respective database counterparts
participant.authorization = authorization
participant.can_submit = permissions[:can_submit]
participant.can_review = permissions[:can_review]
participant.can_take_quiz = permissions[:can_take_quiz]
participant.can_mentor = permissions[:can_mentor]
end
</syntaxhighlight>

===<code>validate_authorization</code>===

Description

Parameters

Returns

Notable Changes

Code

<syntaxhighlight lang=ruby line>
def validate_authorization
valid_authorizations = %w[reader reviewer submitter mentor]
authorization = params[:authorization]
authorization = authorization.downcase if authorization.present?

unless authorization
render json: { error: 'authorization is required' }, status: :unprocessable_entity
return
end

unless valid_authorizations.include?(authorization)
render json: { error: 'authorization not valid. Valid authorizations are: Reader, Reviewer, Submitter, Mentor' },
status: :unprocessable_entity
return
end

authorization
end
</syntaxhighlight>

=Testing Plan=

Of this implementation, also existing 25 tests are passing. We have also given each test their respective IDs within <code>participants_controller_spec.rb</code> as well so that they may be more easily identifiable. For more information about the previous testing plan, please refer to the previous implementation's page here: [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2484._Reimplement_participants_controller.rb]

Below are any modifications to the existing test file (<code>participants_controller_spec.rb</code>) that we have made during the course of this project, alongside the descriptions and rationales behind them:

==Tests==

Below are the tests that are included in this implementation. We have updated the test descriptions to include more accurate and detailed information about each of the tests as well. Any tests that have been modified or new will be specified as such:

{| class="wikitable" style="margin-left:40px"
|-
! Test ID !! Test Description
|-
| 1 || Retrieve participants by valid user ID (should return participant data)
|-
| 2 || Retrieve participants by user ID with no participants (should return empty array)
|-
| 3 || Retrieve participants with non-existent user ID (should return 'User not found')
|-
| 4 || Retrieve participants by user ID with invalid token (should return 'Not Authorized')
|-
| 5 || Retrieve participants by valid assignment ID (should return participant data)
|-
| 6 || Retrieve participants by non-existent assignment ID (should return 'Assignment not found')
|-
| 7 || Retrieve participants by assignment ID with invalid token (should return 'Not Authorized')
|-
| 8 || Retrieve a participant by valid ID (should return participant details)
|-
| 9 || Retrieve a participant by non-existent ID (should return 'Not Found')
|-
| 10 || Retrieve a participant by ID with invalid token (should return 'Not Authorized')
|-
| 11 || Delete a participant by valid ID (should return deletion success message)
|-
| 12 || Delete a participant by non-existent ID (should return 'Not Found')
|-
| 13 || Delete a participant by ID with invalid token (should return 'Not Authorized')
|-
| 14 || Update participant authorization with valid data (should return updated authorization)
|-
| 15 || Update participant authorization with non-existent participant ID (should return 'Participant not found')
|-
| 16 || Update participant authorization with invalid role (should return 'authorization not valid')
|-
| 17 || Update participant authorization with invalid token (should return 'Not Authorized')
|-
| 18 || Add a participant successfully (should return participant data with authorization)
|-
| 19 || Add a participant that already exists (should return duplicate participant error)
|-
| 20 || Add a participant with non-existent user ID (should return 'User not found')
|-
| 21 || Add a participant with non-existent assignment ID (should return 'Assignment not found')
|-
| 22 || Add a participant with invalid authorization (should return 'authorization not valid')
|-
| 23 || Add a participant with unsupported authorization format (should return 'authorization not valid')
|-
| 24 (NEW) || Add a participant missing user_id in request body (should return 'User not found')
|-
| 25 (NEW) || Add a participant missing assignment_id in request body (should return 'Assignment not found')
|}

==Removed Tests==

These are any tests that we have modified or removed from the previous testing plan. If the test ID is denoted by (Previously), that means that the ID shown was part of the previous implementation's testing plan.

{| class="wikitable" style="margin-left:40px"
|-
! Test ID !! Modification Description
|-
| (Previously) 22 || This test was removed as it was redundant. While it is important to check the authorization of the participant that would be invalid, the invalid ID used for this test is a duplicate of the previous test, meaning the result is guaranteed to match that of the previous test regardless of what is meant to be tested.
|}

=Next Steps=

Being able to implement this could potentially simplify rendering to the view somewhat in that it could handle simple HTML status code handling. Below are some examples of implementations to serve as a point of reference:

===Example 1===

<syntaxhighlight lang=ruby line>
# Checks if a target object (participant or participants) is not nil and then renders the object.
# If the object is nil, renders the object errors and sends a not_found_status and if the object
# exists, renders the object and sends a success status
# not_found_status default: :unprocessable_entity (422)
# success_status default: :ok (200)
def render_object_or_error(object, not_found_status: :unprocessable_entity, success_status: :ok)
if object.nil?
render json: { error: 'Resource not found' }, status: not_found_status
elsif object.respond_to?(:errors) && object.errors.any?
render json: object.errors, status: :unprocessable_entity
else
render json: object, status: success_status
end
</syntaxhighlight>

This example is modeled to be specific to the most common use case for this function in the <code>participants_controller.rb</code> by returning the default 422 and 200 error and success codes that are used by three instances of JSON rendering where it checks for whether a list of participants or a single participant is nil. These default values for the status codes are mainly to cover those instances, but could be changed to something else if necessary. The <code>object</code> parameter is representative of the object that was meant to be rendered given the success or failure of the operation.

===Example 2===

<syntaxhighlight lang=ruby line>
def render_object_if(conditional, object, error_status, success_status)
if conditional
render json: { error: 'Resource not found' }, status: error_status
else
render json: object, status: success_status
end
</syntaxhighlight>

This example is a more generic implementation of the function, mandating the error and success status codes rather than providing default values. The point of this was to emphasize readability when glancing over the use of this function. For example, being able to tell that seeing the function being used would immediately tell the reader what the success and failure states were immediately without having to find and inspect the function itself. The <code>conditional</code> parameter would also allow the function to act similarly to a more readable ternary statement made for rendering.

Implementing this successfully would reduce the amount of repetitive code being used within the controller, as the if-else view rendering is very common in <code>participants_controller.rb</code>. We were unable to implement it within our given timeframe, so we opted to divert our focus on other, important tasks that we needed to do.

=Team=
'''Mentor'''

*Aniruddha Rajnekar <aarajnek@ncsu.edu>

'''Students'''

*Akhil Adusumilli <aadusum@ncsu.edu>

*Vansh Dodiya <vkdodiya@ncsu.edu>

*Brian Huynh <bhhuynh@ncsu.edu>

= Relevant Links =

Pull Request [https://github.com/expertiza/reimplementation-back-end/pull/192] 
GitHub Repository [https://github.com/Vansh17/refactoring-participants-controller.git] 
GitHub Project Board [https://github.com/users/Vansh17/projects/2] 
<code>participants_controller.rb</code> in Old Expertiza [https://github.com/expertiza/expertiza/blob/main/app/controllers/participants_controller.rb] 
<code>participants_helper.rb</code> in Old Expertiza [https://github.com/expertiza/expertiza/blob/main/app/helpers/participants_helper.rb]

CSC/ECE 517 Spring 2025 - E2531 Refactor participants controller.rb

2025-04-27T19:21:43Z

Vkdodiya: /* Methods (TEMP) */

=Introduction=
From the project description: "This project aims to refactor the <code>participants_controller.rb</code> and its helper class, <code>participants_helper.rb</code>, in the Expertiza system. The focus will be on improving code structure by implementing DRY and SOLID principles, enhancing readability with meaningful comments and clear naming conventions, and ensuring robustness through comprehensive RSpec testing." Since this is a refactoring project, we will also be utilizing Large Language Models (LLMs) to aid in development. More information on how we used them can be found in the section below.

==Video Overview==

https://youtu.be/4kfz0hrmSg4

Note: In the video it shows the test file at the end, but does not mention a last-minute change that numbers all of the tests to make it much easier to keep track of each of the tests and which ones are passing.

=Use of Large Language Models (LLMs)=

For this project, we are using ChatGPT as an LLM helper in determining what issues there are within the code. The use of LLMs in this project will likely be limited to probing for potential issues that exist within the system.

Below we have organized the following prompts and a summary of the output in a table:

{| class="wikitable" style="margin-left:40px"
|-
! style="width: 25%" | Prompts !! LLM Output Summary
|-
| [Code from <code>participants_controller.rb</code>] Are there any ways where we can refactor the code to improve readability, DRYness, and clarity of error handling?
|| It recognized some of the issues we, as a team, had already identified and suggested fixes that were similar to what we outlined: Redundant JSON Rendering Code[https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2025_-_E2531_Refactor_participants_controller.rb#Simplifying_Redundant_JSON_Rendering_Code] and Simplifying the Assignment of Participant Fields[https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2025_-_E2531_Refactor_participants_controller.rb#Simplifying_the_Assignment_of_Participant_Fields]. Additionally, it suggested minor changes that we could implement, such as using <code>Participant.where(...)</code> instead of <code>Participant.all</code> to filter out the code more efficiently instead of getting all database instances every time, as well as the use of strong parameters in <code>add()</code> and <code>update_authorization()</code> to avoid having to implement custom parsing techniques. It also recommends renaming the <code>add()</code> function to something more specific in relation to its purpose (adding a <code>Participant</code> to an <code>Assignment</code>.
|-
| Potential Redundant Tests in <code>participants_controller_spec.rb</code>
|| The tests on line 222 and 231 are redundant as only the authorization differs. (Note: This should be investigated to see whether or not this is necessary)
|-
| Checking for issues with the current testing files
|| The "Get Participant by ID call" test was returning a 201 status code instead of the more suitable 200 code
|}

For more detailed information on what prompts we used and the output we got, please visit the page here: [https://docs.google.com/document/d/105_U_Coky-edx7n-tFhD2B5RqmVXxEsKPW_qUaf7bQU/edit?usp=sharing].

=Requirements=
Objectives:
<ul>
<li>Apply DRY principles to eliminate redundant code.</li>
<li>Ensure adherence to SOLID principles for better maintainability.</li>
<li>Use appropriate design patterns to optimize code architecture.</li>
<li>Write clear, informative comments and use meaningful naming conventions.</li>
<li>Test the refactored code extensively with RSpec to verify functionality.</li>
</ul>
Deliverables:
<ul>
<li>Refactored code for participants_controller.rb and helper class.</li>
<li>Comprehensive test suite and coverage report.</li>
<li>Updated and detailed documentation.</li>
<li>Video demonstration of the API functionality.</li>
</ul>

==Existing Issues==
<ul>
<li>There are some API functions that are currently not functioning properly, making it somewhat difficult to test</li>
<li>Some API functions are not returning the correct HTML status messages (e.g. test on line 136 returns 201 instead of 200)</li>
<li>Documentation and comments can be somewhat vague</li>
<ul>
<li>In-line comments should be more descriptive, explaining what the code does in more details</li>
<li>Tests are not described via comments, but in name alone; some more descriptive comments that explain the tests in more detail would be ideal</li>
</ul>
<li>Eliminate instances of redundant code</li>
<li>The method naming should be more descriptive</li>

</ul>

=Design / Proposed Solution=

Based on the previous implementation's controller diagram, we have created a new version that contains our proposed changes and modifications to <code>participants_controller.rb</code>.

[[File:Participants_controller_refactor_v1.2.png]]

==Simplifying Redundant JSON Rendering Code==

Many of the functions in the current implementation contain a conditional if-else statement that determines what HTML status code is returned alongside any necessary values that are requested. Due to its simple nature, it might be possible to reduce the amount of space this takes up by implementing a private helper method that would shorten the process.

Example:

<syntaxhighlight lang=ruby line> if participants.nil?
render json: participants.errors, status: :unprocessable_entity
else
render json: participants, status: :ok
end</syntaxhighlight>

==Simplifying the Assignment of Participant Fields==

The <code>add()</code> and <code>update()</code> both take up a significant amount of space to assign values to database fields and are essentially the same in functionality (in terms of this specific section. We can remove redundancy by creating a method that can remove this redundancy.

Example

<syntaxhighlight lang=ruby line> permissions = retrieve_participant_permissions(authorization)

participant.authorization = authorization
participant.can_submit = permissions[:can_submit]
participant.can_review = permissions[:can_review]
participant.can_take_quiz = permissions[:can_take_quiz]
participant.can_mentor = permissions[:can_mentor]</syntaxhighlight>

==Provide More Clarity in Function Names==

There are some functions that are somewhat unclear/vague in <code>participants_controller.rb</code>. For example, the <code>list_user_participants()</code> and <code>list_assignment_participants()</code>.

=== - Suggested Method Name Improvements ===

{| class="wikitable"
! Old Method Name
! New Method Name
! Notes
|-
| <code>list_user_participants</code>
| <code>render_participants_by_user_id</code>
| Clearer and more descriptive
|-
| <code>list_assignment_participants</code>
| <code>render_participants_by_assignment_id</code>
| Clearer and more descriptive and is consistent with the other get method
|-
| <code>add</code>
| <code>add_participant_to_assignment</code>
| Describes both creation and authorization setup of participant to assignment
|-
| <code>filter_user_participants</code>
| <code>filter_participants_by_user</code>
| Highlights the purpose of the method
|-
| <code>filter_assignment_participants</code>
| <code>filter_participants_by_assignment</code>
| Highlights the purpose of the method

|}

==Improve Documentation and Comments==

Some of the documentation and in-line comments can be somewhat vague. This can lead to misconceptions about how some functions work or how some of the code can function. Below are potential improvements we plan to make for function descriptions, though these may change with the final implementation.

=== Improved Method Comments ===

{| class="wikitable"
! Method
! Original Comment
! Refactored Comment
|-
| render_participants_by_user_id
| Return a list of participants for a given user
| Retrieves all participants associated with the specified user ID
|-
| render_participants_by_assignment_id
| Return a list of participants for a given assignment
| Retrieves all participants linked to the specified assignment ID
|-
| show
| Return a specified participant
| Fetch and return the participant with the given ID
|-
| add_participant_to_assignment
| Assign the specified authorization to the participant and add them to an assignment
| Creates a new participant for a given assignment and assigns appropriate authorization and permissions
|-
| update_authorization
| Update the specified participant to the specified authorization
| Updates the participant’s authorization role and related permissions
|-
| destroy
| Delete a participant
| Deletes the participant identified by the given ID and returns a confirmation message
|-
| participant_params
| Permitted parameters for creating a Participant object
| Strong parameters: list of attributes allowed for participant creation or update
|-
| filter_participants_by_user
| Filters participants based on the provided user. Returns participants ordered by their IDs
| Returns a sorted list of participants filtered by user, if provided
|-
| filter_participants_by_assignment
| Filters participants based on the provided assignment. Returns participants ordered by their IDs
| Returns a sorted list of participants filtered by assignment, if provided
|-
| validate_authorization
| Validates that the authorization parameter is present and is one of the following valid authorizations: reader, reviewer, submitter, mentor
| Ensures authorization param is valid and returns it in lowercase; otherwise returns error response
|-
| find_user / find_assignment / find_participant
| Finds a user/assignment/participant by ID and returns it
| Fetches the corresponding record by ID; renders a not-found error if record does not exist
|}

==Proposed Testing Changes==

<ul>
<li>Add more descriptive comments for tests</li>
<li>Add test that checks that authorizations are updated correctly</li>
<li>Add test that checks that inputted path parameters are not missing and valid inputs</li>
<li>Tests at Line 222 and Line 231 are redundant, as the only difference in the test is the authorization, which would not affect what happens if a participant is not found</li>
</ul>

=Implementation=

As this is a refactoring project, most of our work on the codebase involved cleaning up the current codebase to better align with foundational code style principles rather than introducing any of kind of new functionality. Our primary focus is to make the code more readable and easier to work with than before. We also took the liberty of fixing some minor errors that we found along the way.

==Changelog==

<ul>
<li>Naming changes to multiple functions for better clarity and consistency</li>
<li>Changed HTML status message for <code>show()</code> from 201 (Created) to 200 (OK) as it is a better fit</li>
<li>Created the <code>assign_participant_permissions()</code> method</li>
<li>Introduced two additional tests and removed a redundant one (see Testing Plan for more details)</li>
<li>Removed redundant queries to <code>Participant.all()</code> in both filtering methods</li>
<li>Updated method comments to be more descriptive (see comments table in Design)</li>
</ul>

==Function Name Changes==

The previous implementation had several functions that were strangely named or had names that could be easily misconstrued. The name changes remain the same from the proposal and design section, but for the purpose of clarity, the rationale for each of the functions will be provided below.

===<code>list_user_participants</code> and <code>list_assignment_participants</code>===

These two functions are meant to render a list of participants given a <code>User</code> or <code>Assignment</code> respectively. Based on the name alone, it is difficult to tell that the function would render a User/Assignment or Participants. In order to remedy this, we chose the names <code>render_participants_by_user_id</code> and <code>render_participants_by_assignment_id</code>. The word "list" was replaced by "render" in order to better denote that it is rendering something (json in this case) and the "by" is added to emphasize that the User and Assignment are being used as parameters to search for the Participants. This provides a much clearer picture of what these functions should do compared to before.

===<code>add</code>===

The <code>add</code> function's name was too vague to be particularly useful in identifying its purpose. To be more accurate, the function was meant to add the user to a given assignment, which would return a participant from the assignment's <code>add_participant</code> function. The new name of the function provides much more context to what it does (<code>add_participant_to_assignment</code>).

===<code>filter_user_participants</code> and <code>filter_assignment_participants</code>===

Similar to the list methods that were previously mentioned, it is difficult to tell what exactly these two functions do. While it can be easily seen that it filters something, what is being filtered can be easily mistaken (e.g. does it filter users by participants or participants by users?). The new names, <code>filter_participants_by_user</code> and <code>filter_participants_by_assignment</code> are much clearer in defining that the User and Assignment are being used as the filter parameters for the function.

==HTML Status Code Change for <code>GET</code> Call==

The status code being used for this was previously 201, denoting "successful creation". We have corrected this to a simple 200 code, which signifies an "ok" status message. This issue was actually identified by ChatGPT while we were dowsing for potential issues.

Test modified

<syntaxhighlight lang=ruby line>
# Tests whether a participant returns properly if provided with a valid Participant ID
response '200', 'Returns a participant' do
let(:id) { participant2.id }

run_test! do |response|
data = JSON.parse(response.body)
expect(data['user_id']).to eq(studenta.id)
expect(data['assignment_id']).to eq(assignment2.id)
end
end
</syntaxhighlight>

==Redundant <code>Participant.all</code> Queries Removed==

This issue was initially caught by the LLM, ChatGPT, that the team was using in order to find potential issues. We found that simply using <code>Participant.where()</code> removed the need for the <code>Participant.all</code> query entirely while changing nothing else about the function, reducing the amount of queries necessary to call the filtering methods, <code>filter_participants_by_user</code> and <code>filter_participants_by_assignment</code>.

Example:

<syntaxhighlight lang=ruby line>
# New function
def filter_participants_by_user(user)
participants = Participant.where(user_id: user.id) if user # This would simply get the participants given the proper user ID
participants.order(:id)
end

# Old function
def filter_participants_by_user(user)
participants = Participant.all() # This would obtain the entire list of participants rather than just the necessary ones
participants = participants.where(user_id: user.id) if user
participants.order(:id)
end
</syntaxhighlight>

==New Private Method: <code>assign_participant_permissions()</code>==

The reasoning behind the addition of this method is because of a repeated piece of code that existed in the previous implementation:

<syntaxhighlight lang=ruby line>
permissions = retrieve_participant_permissions(authorization)

participant.authorization = authorization
participant.can_submit = permissions[:can_submit]
participant.can_review = permissions[:can_review]
participant.can_take_quiz = permissions[:can_take_quiz]
participant.can_mentor = permissions[:can_mentor]
</syntaxhighlight>

This was repeated in two different contexts: when the Participant was updated or created. This is a violation of the DRY principle, as the same code is repeated multiple times where it could have been reduced to make it more easily readable. In order to resolve this issue, we simply turned this code snippet into a private method that can be called within <code>participants_controller.rb</code>:

<syntaxhighlight lang=ruby line>
# An authorization string containing the participant's role is taken and used to determine
# what permissions will be allocated to the participant. Each of these permissions will
# then be assigned to the Participant's database permission attributes.
#
# @param [String] authorization: An authorization string that represents the participant's role
# @param [Participant] participant: The participant whose authorization permissions are being updated
def assign_participant_permissions(authorization, participant)
# Call helper method from participants_helper to retrieve a dictionary containing the
# appropriate permission boolean values for the role specified by the authorization string
permissions = retrieve_participant_permissions(authorization)

# Assigns each of the boolean permission values to their respective database counterparts
participant.authorization = authorization
participant.can_submit = permissions[:can_submit]
participant.can_review = permissions[:can_review]
participant.can_take_quiz = permissions[:can_take_quiz]
participant.can_mentor = permissions[:can_mentor]
end
</syntaxhighlight>

===Description:===

An authorization string containing the participant's role is taken and used to determine what permissions will be allocated to the participant. Each of these permissions will then be assigned to the Participant's database permission attributes.

===Parameters:===

<ul>
<li><code>authorization</code>: An authorization string that represents the participant's role. This can be either reader, reviewer, submitter, or mentor.</li>
<li><code>participant</code>: The participant whose attributes are being updated. This is passed in to be modified by the function to be used to assign each of the participant's attribute values that are representative of its assigned role.</li>
</ul>

===Behavior===

<ul>
<li>Use <code>retrieve_participant_permissions</code> from <code>participants_helper</code> in order to get all necessary permission boolean values for a given participant role</li>
<li>Assign each of the permission boolean values (<code>can_submit</code>, <code>can_review</code>, <code>can_take_quiz</code>, <code>can_mentor</code>)</li> from the helper method to their respective database attribute counterparts in Participant
</ul>

==Post-Demo Changes==

There were three notable topics that were brought up during the final demo presentation:

<ul>
<li>The renaming of <code>get_participants_by_user</code> and <code>get_participants_by_assignment</code> to something more suitable to its purpose in rendering the JSON of a list of participants</li>
<li>Consider the application of <code>find_user</code> and <code>find_assignment</code></li> within <code>participants_controller</code>
<li>Update the wiki to provide descriptions for each of the methods included in <code>participants_controller</code> (See Methods subsection in the Implementation section)</li>
</ul>

===Renaming <code>get_participants_by_user</code> and <code>get_participants_by_assignment</code>===

These two functions were renamed (once again) to something that better fit the functionality and purpose of the function. Since these functions are meant to render the lists of participants gotten from their respective parameters and use the ID values for each, both of the functions were renamed to <code>render_participants_by_user_id</code> and <code>render_participants_by_assignment_id</code> respectively. The renaming of the filter methods was also brought up, but those functions actually do use the objects themselves as parameters, so have been left as is for the time being.

===<code>find_user</code> and <code>find_assignment</code></li> within <code>participants_controller</code>===

We reconsidered the use of these methods within the controller since it was somewhat odd that it would have these methods. However, we concluded that, since the find methods are helper methods that are private and not open to be used by other parts of the code, to be fine to leave as is. This is mostly because they are simple helper methods that get the current user and assignment and return them, rendering an error if they do not exist.

==Methods (TEMP)==

===<code>render_participants_by_user_id</code>===

Description

Fetches all participants associated with the specified user.

Parameters

<ul>
<li><code>user_id [Integer]</code>: ID of the user</li>
</ul>

Returns

<ul>
<li>200 OK: A JSON array of participant objects</li>
<li>401 Unauthorized: If the user is not authorized for the action</li>
<li>404 Not Found: If the user does not exist</li>
<li>422 Unprocessable Entity: If the query fails unexpectedly</li>
</ul>

Notable Changes

<ul>
<li>Renamed from <code>list_user_participants</code> to <code>render_participants_by_user_id</code></li>
</ul>
Code

<syntaxhighlight lang=ruby line>
def render_participants_by_user_id
user = find_user if params[:user_id].present?
return if params[:user_id].present? && user.nil?

participants = filter_participants_by_user(user)

if participants.nil?
render json: participants.errors, status: :unprocessable_entity
else
render json: participants, status: :ok
end
end
</syntaxhighlight>

===<code>render_participants_by_assignment_id</code>===

Description

Fetches all participants associated with a specific assignment.

Parameters

<ul> <li><code>assignment_id [Integer]</code>: ID of the assignment</li> </ul>

Returns

<ul> <li>200 OK: A JSON array of participant objects</li> <li>401 Unauthorized: If the user is not authorized for the action</li> <li>404 Not Found: If the assignment does not exist</li> <li>422 Unprocessable Entity: If the query fails unexpectedly</li> </ul>

Notable Changes

<ul> <li>Renamed from <code>list_assignment_participants</code> to <code>render_participants_by_assignment_id</code></li> </ul>

Code

<syntaxhighlight lang=ruby line>
def render_participants_by_assignment_id
assignment = find_assignment if params[:assignment_id].present?
return if params[:assignment_id].present? && assignment.nil?

participants = filter_participants_by_assignment(assignment)

if participants.nil?
render json: participants.errors, status: :unprocessable_entity
else
render json: participants, status: :ok
end
end
</syntaxhighlight>

===<code>show</code>===

Description

Parameters

Returns

Notable Changes

Code

<syntaxhighlight lang=ruby line>
def show
participant = Participant.find(params[:id])

if participant.nil?
render json: participant.errors, status: :unprocessable_entity
else
render json: participant, status: :ok
end
end
</syntaxhighlight>

===<code>add_participant_to_assignment</code>===

Description

Parameters

Returns

Notable Changes

Code

<syntaxhighlight lang=ruby line>
def add_participant_to_assignment
user = find_user
return unless user

assignment = find_assignment
return unless assignment

authorization = validate_authorization
return unless authorization

participant = assignment.add_participant(user)
assign_participant_permissions(authorization, participant)

if participant.save
render json: participant, status: :created
else
render json: participant.errors, status: :unprocessable_entity
end
end
</syntaxhighlight>

===<code>update_authorization</code>===

Description

Parameters

Returns

Notable Changes

Code

<syntaxhighlight lang=ruby line>
def update_authorization
participant = find_participant
return unless participant

authorization = validate_authorization
return unless authorization

assign_participant_permissions(authorization, participant)

if participant.save
render json: participant, status: :created
else
render json: participant.errors, status: :unprocessable_entity
end
end
</syntaxhighlight>

===<code>destroy</code>===

Description

Parameters

Returns

Notable Changes

Code

<syntaxhighlight lang=ruby line>
def destroy
participant = Participant.find_by(id: params[:id])

if participant.nil?
render json: { error: 'Not Found' }, status: :not_found
elsif participant.destroy
successful_deletion_message = if params[:team_id].nil?
"Participant #{params[:id]} in Assignment #{params[:assignment_id]} has been deleted successfully!"
else
"Participant #{params[:id]} in Team #{params[:team_id]} of Assignment #{params[:assignment_id]} has been deleted successfully!"
end
render json: { message: successful_deletion_message }, status: :ok
else
render json: participant.errors, status: :unprocessable_entity
end
end
</syntaxhighlight>

===<code>participants_params</code>===

Description

Parameters

Returns

Notable Changes

Code

<syntaxhighlight lang=ruby line>
def participant_params
params.require(:participant).permit(:user_id, :assignment_id, :authorization, :can_submit,
:can_review, :can_take_quiz, :can_mentor, :handle,
:team_id, :join_team_request_id, :permission_granted,
:topic, :current_stage, :stage_deadline)
end
</syntaxhighlight>

===<code>filter_participants_by_user</code>===

Description

Parameters

Returns

Notable Changes

Code

<syntaxhighlight lang=ruby line>
def filter_participants_by_user(user)
participants = Participant.where(user_id: user.id) if user
participants.order(:id)
end
</syntaxhighlight>

===<code>filter_participants_by_assignment</code>===

Description

Parameters

Returns

Notable Changes

Code

<syntaxhighlight lang=ruby line>
def filter_participants_by_assignment(assignment)
participants = Participant.where(assignment_id: assignment.id) if assignment
participants.order(:id)
end
</syntaxhighlight>

===<code>find_user</code>===

Description

Parameters

Returns

Notable Changes

Code

<syntaxhighlight lang=ruby line>
def find_user
user_id = params[:user_id]
user = User.find_by(id: user_id)
render json: { error: 'User not found' }, status: :not_found unless user
user
end
</syntaxhighlight>

===<code>find_assignment</code>===

Description

Parameters

Returns

Notable Changes

Code

<syntaxhighlight lang=ruby line>
def find_assignment
assignment_id = params[:assignment_id]
assignment = Assignment.find_by(id: assignment_id)
render json: { error: 'Assignment not found' }, status: :not_found unless assignment
assignment
end
</syntaxhighlight>

===<code>find_participant</code>===

Description

Parameters

Returns

Notable Changes

Code

<syntaxhighlight lang=ruby line>
def find_participant
participant_id = params[:id]
participant = Participant.find_by(id: participant_id)
render json: { error: 'Participant not found' }, status: :not_found unless participant
participant
end
</syntaxhighlight>

===<code>assign_participant_permissions</code>===

Description

Parameters

Returns

Code

<syntaxhighlight lang=ruby line>
def assign_participant_permissions(authorization, participant)
# Call helper method from participants_helper to retrieve a dictionary containing the
# appropriate permission boolean values for the role specified by the authorization string
permissions = retrieve_participant_permissions(authorization)

# Assigns each of the boolean permission values to their respective database counterparts
participant.authorization = authorization
participant.can_submit = permissions[:can_submit]
participant.can_review = permissions[:can_review]
participant.can_take_quiz = permissions[:can_take_quiz]
participant.can_mentor = permissions[:can_mentor]
end
</syntaxhighlight>

===<code>validate_authorization</code>===

Description

Parameters

Returns

Notable Changes

Code

<syntaxhighlight lang=ruby line>
def validate_authorization
valid_authorizations = %w[reader reviewer submitter mentor]
authorization = params[:authorization]
authorization = authorization.downcase if authorization.present?

unless authorization
render json: { error: 'authorization is required' }, status: :unprocessable_entity
return
end

unless valid_authorizations.include?(authorization)
render json: { error: 'authorization not valid. Valid authorizations are: Reader, Reviewer, Submitter, Mentor' },
status: :unprocessable_entity
return
end

authorization
end
</syntaxhighlight>

=Testing Plan=

Of this implementation, also existing 25 tests are passing. We have also given each test their respective IDs within <code>participants_controller_spec.rb</code> as well so that they may be more easily identifiable. For more information about the previous testing plan, please refer to the previous implementation's page here: [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2484._Reimplement_participants_controller.rb]

Below are any modifications to the existing test file (<code>participants_controller_spec.rb</code>) that we have made during the course of this project, alongside the descriptions and rationales behind them:

==Tests==

Below are the tests that are included in this implementation. We have updated the test descriptions to include more accurate and detailed information about each of the tests as well. Any tests that have been modified or new will be specified as such:

{| class="wikitable" style="margin-left:40px"
|-
! Test ID !! Test Description
|-
| 1 || Retrieve participants by valid user ID (should return participant data)
|-
| 2 || Retrieve participants by user ID with no participants (should return empty array)
|-
| 3 || Retrieve participants with non-existent user ID (should return 'User not found')
|-
| 4 || Retrieve participants by user ID with invalid token (should return 'Not Authorized')
|-
| 5 || Retrieve participants by valid assignment ID (should return participant data)
|-
| 6 || Retrieve participants by non-existent assignment ID (should return 'Assignment not found')
|-
| 7 || Retrieve participants by assignment ID with invalid token (should return 'Not Authorized')
|-
| 8 || Retrieve a participant by valid ID (should return participant details)
|-
| 9 || Retrieve a participant by non-existent ID (should return 'Not Found')
|-
| 10 || Retrieve a participant by ID with invalid token (should return 'Not Authorized')
|-
| 11 || Delete a participant by valid ID (should return deletion success message)
|-
| 12 || Delete a participant by non-existent ID (should return 'Not Found')
|-
| 13 || Delete a participant by ID with invalid token (should return 'Not Authorized')
|-
| 14 || Update participant authorization with valid data (should return updated authorization)
|-
| 15 || Update participant authorization with non-existent participant ID (should return 'Participant not found')
|-
| 16 || Update participant authorization with invalid role (should return 'authorization not valid')
|-
| 17 || Update participant authorization with invalid token (should return 'Not Authorized')
|-
| 18 || Add a participant successfully (should return participant data with authorization)
|-
| 19 || Add a participant that already exists (should return duplicate participant error)
|-
| 20 || Add a participant with non-existent user ID (should return 'User not found')
|-
| 21 || Add a participant with non-existent assignment ID (should return 'Assignment not found')
|-
| 22 || Add a participant with invalid authorization (should return 'authorization not valid')
|-
| 23 || Add a participant with unsupported authorization format (should return 'authorization not valid')
|-
| 24 (NEW) || Add a participant missing user_id in request body (should return 'User not found')
|-
| 25 (NEW) || Add a participant missing assignment_id in request body (should return 'Assignment not found')
|}

==Removed Tests==

These are any tests that we have modified or removed from the previous testing plan. If the test ID is denoted by (Previously), that means that the ID shown was part of the previous implementation's testing plan.

{| class="wikitable" style="margin-left:40px"
|-
! Test ID !! Modification Description
|-
| (Previously) 22 || This test was removed as it was redundant. While it is important to check the authorization of the participant that would be invalid, the invalid ID used for this test is a duplicate of the previous test, meaning the result is guaranteed to match that of the previous test regardless of what is meant to be tested.
|}

=Next Steps=

Being able to implement this could potentially simplify rendering to the view somewhat in that it could handle simple HTML status code handling. Below are some examples of implementations to serve as a point of reference:

===Example 1===

<syntaxhighlight lang=ruby line>
# Checks if a target object (participant or participants) is not nil and then renders the object.
# If the object is nil, renders the object errors and sends a not_found_status and if the object
# exists, renders the object and sends a success status
# not_found_status default: :unprocessable_entity (422)
# success_status default: :ok (200)
def render_object_or_error(object, not_found_status: :unprocessable_entity, success_status: :ok)
if object.nil?
render json: { error: 'Resource not found' }, status: not_found_status
elsif object.respond_to?(:errors) && object.errors.any?
render json: object.errors, status: :unprocessable_entity
else
render json: object, status: success_status
end
</syntaxhighlight>

This example is modeled to be specific to the most common use case for this function in the <code>participants_controller.rb</code> by returning the default 422 and 200 error and success codes that are used by three instances of JSON rendering where it checks for whether a list of participants or a single participant is nil. These default values for the status codes are mainly to cover those instances, but could be changed to something else if necessary. The <code>object</code> parameter is representative of the object that was meant to be rendered given the success or failure of the operation.

===Example 2===

<syntaxhighlight lang=ruby line>
def render_object_if(conditional, object, error_status, success_status)
if conditional
render json: { error: 'Resource not found' }, status: error_status
else
render json: object, status: success_status
end
</syntaxhighlight>

This example is a more generic implementation of the function, mandating the error and success status codes rather than providing default values. The point of this was to emphasize readability when glancing over the use of this function. For example, being able to tell that seeing the function being used would immediately tell the reader what the success and failure states were immediately without having to find and inspect the function itself. The <code>conditional</code> parameter would also allow the function to act similarly to a more readable ternary statement made for rendering.

Implementing this successfully would reduce the amount of repetitive code being used within the controller, as the if-else view rendering is very common in <code>participants_controller.rb</code>. We were unable to implement it within our given timeframe, so we opted to divert our focus on other, important tasks that we needed to do.

=Team=
'''Mentor'''

*Aniruddha Rajnekar <aarajnek@ncsu.edu>

'''Students'''

*Akhil Adusumilli <aadusum@ncsu.edu>

*Vansh Dodiya <vkdodiya@ncsu.edu>

*Brian Huynh <bhhuynh@ncsu.edu>

= Relevant Links =

Pull Request [https://github.com/expertiza/reimplementation-back-end/pull/192] 
GitHub Repository [https://github.com/Vansh17/refactoring-participants-controller.git] 
GitHub Project Board [https://github.com/users/Vansh17/projects/2] 
<code>participants_controller.rb</code> in Old Expertiza [https://github.com/expertiza/expertiza/blob/main/app/controllers/participants_controller.rb] 
<code>participants_helper.rb</code> in Old Expertiza [https://github.com/expertiza/expertiza/blob/main/app/helpers/participants_helper.rb]

CSC/ECE 517 Spring 2025 - E2531 Refactor participants controller.rb

2025-04-22T16:18:48Z

Vkdodiya: /* Issues and Next Steps */

CSC/ECE 517 Spring 2025 - E2531 Refactor participants controller.rb

2025-04-08T21:49:07Z

Vkdodiya: /* Improved Method Comments */

==Introduction==
From the project description: "This project aims to refactor the <code>participants_controller.rb</code> and its helper class, <code>participants_helper.rb</code>, in the Expertiza system. The focus will be on improving code structure by implementing DRY and SOLID principles, enhancing readability with meaningful comments and clear naming conventions, and ensuring robustness through comprehensive RSpec testing." Since this is a refactoring project, we will also be utilizing Large Language Models (LLMs) to aid in development. More information on how we used them can be found in the section below.

==Use of Large Language Models (LLMs)==

For this project, we are using ChatGPT as an LLM helper in determining what issues there are within the code. The use of LLMs in this project will likely be limited to probing for potential issues that exist within the system.

Below we have organized the following prompts and a summary of the output in a table:

{| class="wikitable" style="margin-left:40px"
|-
! style="width: 25%" | Prompts !! LLM Output Summary
|-
| [Code from <code>participants_controller.rb</code>] Are there any ways where we can refactor the code to improve readability, DRYness, and clarity of error handling?
|| It recognized some of the issues we, as a team, had already identified and suggested fixes that were similar to what we outlined: Redundant JSON Rendering Code[https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2025_-_E2531_Refactor_participants_controller.rb#Simplifying_Redundant_JSON_Rendering_Code] and Simplifying the Assignment of Participant Fields[https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2025_-_E2531_Refactor_participants_controller.rb#Simplifying_the_Assignment_of_Participant_Fields]. Additionally, it suggested minor changes that we could implement, such as using <code>Participant.where(...)</code> instead of <code>Participant.all</code> to filter out the code more efficiently instead of getting all database instances every time, as well as the use of strong parameters in <code>add()</code> and <code>update_authorization()</code> to avoid having to implement custom parsing techniques. It also recommends renaming the <code>add()</code> function to something more specific in relation to its purpose (adding a <code>Participant</code> to an <code>Assignment</code>.
|-
| Potential Redundant Tests in <code>participants_controller_spec.rb</code>
|| The tests on line 222 and 231 are redundant as only the authorization differs. (Note: This should be investigated to see whether or not this is necessary)
|}

For more detailed information on what prompts we used and the output we got, please visit the page here: [https://docs.google.com/document/d/105_U_Coky-edx7n-tFhD2B5RqmVXxEsKPW_qUaf7bQU/edit?usp=sharing].

==Requirements==
Objectives:
<ul>
<li>Apply DRY principles to eliminate redundant code.</li>
<li>Ensure adherence to SOLID principles for better maintainability.</li>
<li>Use appropriate design patterns to optimize code architecture.</li>
<li>Write clear, informative comments and use meaningful naming conventions.</li>
<li>Test the refactored code extensively with RSpec to verify functionality.</li>
</ul>
Deliverables:
<ul>
<li>Refactored code for participants_controller.rb and helper class.</li>
<li>Comprehensive test suite and coverage report.</li>
<li>Updated and detailed documentation.</li>
<li>Video demonstration of the API functionality.</li>
</ul>

==Existing Issues==
<ul>
<li>There are some API functions that are currently not functioning properly, making it somewhat difficult to test</li>
<li>Some API functions are not returning the correct HTML status messages (e.g. test on line 136 returns 201 instead of 200)</li>
<li>Documentation and comments can be somewhat vague</li>
<ul>
<li>In-line comments should be more descriptive, explaining what the code does in more details</li>
<li>Tests are not described via comments, but in name alone; some more descriptive comments that explain the tests in more detail would be ideal</li>
</ul>
<li>Eliminate instances of redundant code</li>
<li>The method naming should be more descriptive</li>

</ul>

==Design / Proposed Solution (TEMP)==

===Simplifying Redundant JSON Rendering Code===

Many of the functions in the current implementation contain a conditional if-else statement that determines what HTML status code is returned alongside any necessary values that are requested. Due to its simple nature, it might be possible to reduce the amount of space this takes up by implementing a private helper method that would shorten the process.

Example:

<pre> if participants.nil?
render json: participants.errors, status: :unprocessable_entity
else
render json: participants, status: :ok
end</pre>

===Simplifying the Assignment of Participant Fields===

In the <code>add()</code> and <code>update</code> both take up a significant amount of space to assign values to database fields and are essentially the same in functionality (in terms of this specific section. We can remove redundancy by creating a method that can remove this redundancy.

Example

<pre> permissions = retrieve_participant_permissions(authorization)

participant.authorization = authorization
participant.can_submit = permissions[:can_submit]
participant.can_review = permissions[:can_review]
participant.can_take_quiz = permissions[:can_take_quiz]
participant.can_mentor = permissions[:can_mentor]</pre>

===Provide More Clarity in Function Names===

There are some functions that are somewhat unclear/vague in <code>participants_controller.rb</code>. For example, the <code>list_user_participants()</code> and <code>list_assignment_participants()</code>.

==== - Suggested Method Name Improvements ====

{| class="wikitable"
! Old Method Name
! New Method Name
! Notes
|-
| list_user_participants
| participants_by_user
| Clearer and more descriptive
|-
| list_assignment_participants
| participants_by_assignment
| Consistent with the above
|-
| show
| show_participant
| Explicit about what is shown
|-
| add
| create_participant_with_authorization
| Describes both creation and auth setup
|-
| update_authorization
| update_participant_authorization
| Makes the subject (participant) clear
|-
| destroy
| destroy_participant
| More descriptive for further use
|-
| filter_user_participants
| participants_for_user
| Highlights the purpose of the method
|-
| filter_assignment_participants
| participants_for_assignment
| Highlights the purpose of the method
|-
| validate_authorization
| validated_authorization
| Suggests return value is validated

|}

===Improve Documentation and Comments===

=== Improved Method Comments ===

{| class="wikitable"
! Method
! Original Comment
! Refactored Comment
|-
| list_user_participants
| Return a list of participants for a given user
| Retrieves all participants associated with the specified user ID
|-
| list_assignment_participants
| Return a list of participants for a given assignment
| Retrieves all participants linked to the specified assignment ID
|-
| show
| Return a specified participant
| Fetch and return the participant with the given ID
|-
| add
| Assign the specified authorization to the participant and add them to an assignment
| Creates a new participant for a given assignment and assigns appropriate authorization and permissions
|-
| update_authorization
| Update the specified participant to the specified authorization
| Updates the participant’s authorization role and related permissions
|-
| destroy
| Delete a participant
| Deletes the participant identified by the given ID and returns a confirmation message
|-
| participant_params
| Permitted parameters for creating a Participant object
| Strong parameters: list of attributes allowed for participant creation or update
|-
| filter_user_participants
| Filters participants based on the provided user. Returns participants ordered by their IDs
| Returns a sorted list of participants filtered by user, if provided
|-
| filter_assignment_participants
| Filters participants based on the provided assignment. Returns participants ordered by their IDs
| Returns a sorted list of participants filtered by assignment, if provided
|-
| validate_authorization
| Validates that the authorization parameter is present and is one of the following valid authorizations: reader, reviewer, submitter, mentor
| Ensures authorization param is valid and returns it in lowercase; otherwise returns error response
|-
| find_user / find_assignment / find_participant
| Finds a user/assignment/participant by ID and returns it
| Fetches the corresponding record by ID; renders a not-found error if record does not exist
|}

===Proposed Testing Changes===

<ul>
<li>Add more descriptive comments for tests</li>
<li>Add test that checks that authorizations are updated correctly</li>
<li>Add test that checks that inputted path parameters are not missing and valid inputs</li>
<li>Tests at Line 222 and Line 231 are redundant, as the only difference in the test is the authorization, which would not affect what happens if a participant is not found</li>
</ul>

==Team==
'''Mentor'''

*Aniruddha Rajnekar <aarajnek@ncsu.edu>

'''Students'''

*Akhil Adusumilli <aadusum@ncsu.edu>

*Vansh Dodiya <vkdodiya@ncsu.edu>

*Brian Huynh <bhhuynh@ncsu.edu>

== Relevant Links ==

Pull Request (Unimplemented) [] 
GitHub Repository [https://github.com/Vansh17/refactoring-participants-controller.git] 
GitHub Project Board [https://github.com/users/Vansh17/projects/2] 
<code>participants_controller.rb</code> in Old Expertiza [https://github.com/expertiza/expertiza/blob/main/app/controllers/participants_controller.rb] 
<code>participants_helper.rb</code> in Old Expertiza [https://github.com/expertiza/expertiza/blob/main/app/helpers/participants_helper.rb]

CSC/ECE 517 Spring 2025 - E2531 Refactor participants controller.rb

2025-04-08T21:48:25Z

Vkdodiya: /* Testing Plan (TEMP) */

==Introduction==
From the project description: "This project aims to refactor the <code>participants_controller.rb</code> and its helper class, <code>participants_helper.rb</code>, in the Expertiza system. The focus will be on improving code structure by implementing DRY and SOLID principles, enhancing readability with meaningful comments and clear naming conventions, and ensuring robustness through comprehensive RSpec testing." Since this is a refactoring project, we will also be utilizing Large Language Models (LLMs) to aid in development. More information on how we used them can be found in the section below.

==Use of Large Language Models (LLMs)==

For this project, we are using ChatGPT as an LLM helper in determining what issues there are within the code. The use of LLMs in this project will likely be limited to probing for potential issues that exist within the system.

Below we have organized the following prompts and a summary of the output in a table:

{| class="wikitable" style="margin-left:40px"
|-
! style="width: 25%" | Prompts !! LLM Output Summary
|-
| [Code from <code>participants_controller.rb</code>] Are there any ways where we can refactor the code to improve readability, DRYness, and clarity of error handling?
|| It recognized some of the issues we, as a team, had already identified and suggested fixes that were similar to what we outlined: Redundant JSON Rendering Code[https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2025_-_E2531_Refactor_participants_controller.rb#Simplifying_Redundant_JSON_Rendering_Code] and Simplifying the Assignment of Participant Fields[https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2025_-_E2531_Refactor_participants_controller.rb#Simplifying_the_Assignment_of_Participant_Fields]. Additionally, it suggested minor changes that we could implement, such as using <code>Participant.where(...)</code> instead of <code>Participant.all</code> to filter out the code more efficiently instead of getting all database instances every time, as well as the use of strong parameters in <code>add()</code> and <code>update_authorization()</code> to avoid having to implement custom parsing techniques. It also recommends renaming the <code>add()</code> function to something more specific in relation to its purpose (adding a <code>Participant</code> to an <code>Assignment</code>.
|-
| Potential Redundant Tests in <code>participants_controller_spec.rb</code>
|| The tests on line 222 and 231 are redundant as only the authorization differs. (Note: This should be investigated to see whether or not this is necessary)
|}

For more detailed information on what prompts we used and the output we got, please visit the page here: [https://docs.google.com/document/d/105_U_Coky-edx7n-tFhD2B5RqmVXxEsKPW_qUaf7bQU/edit?usp=sharing].

==Requirements==
Objectives:
<ul>
<li>Apply DRY principles to eliminate redundant code.</li>
<li>Ensure adherence to SOLID principles for better maintainability.</li>
<li>Use appropriate design patterns to optimize code architecture.</li>
<li>Write clear, informative comments and use meaningful naming conventions.</li>
<li>Test the refactored code extensively with RSpec to verify functionality.</li>
</ul>
Deliverables:
<ul>
<li>Refactored code for participants_controller.rb and helper class.</li>
<li>Comprehensive test suite and coverage report.</li>
<li>Updated and detailed documentation.</li>
<li>Video demonstration of the API functionality.</li>
</ul>

==Existing Issues==
<ul>
<li>There are some API functions that are currently not functioning properly, making it somewhat difficult to test</li>
<li>Some API functions are not returning the correct HTML status messages (e.g. test on line 136 returns 201 instead of 200)</li>
<li>Documentation and comments can be somewhat vague</li>
<ul>
<li>In-line comments should be more descriptive, explaining what the code does in more details</li>
<li>Tests are not described via comments, but in name alone; some more descriptive comments that explain the tests in more detail would be ideal</li>
</ul>
<li>Eliminate instances of redundant code</li>
<li>The method naming should be more descriptive</li>

</ul>

==Design / Proposed Solution (TEMP)==

===Simplifying Redundant JSON Rendering Code===

Many of the functions in the current implementation contain a conditional if-else statement that determines what HTML status code is returned alongside any necessary values that are requested. Due to its simple nature, it might be possible to reduce the amount of space this takes up by implementing a private helper method that would shorten the process.

Example:

<pre> if participants.nil?
render json: participants.errors, status: :unprocessable_entity
else
render json: participants, status: :ok
end</pre>

===Simplifying the Assignment of Participant Fields===

In the <code>add()</code> and <code>update</code> both take up a significant amount of space to assign values to database fields and are essentially the same in functionality (in terms of this specific section. We can remove redundancy by creating a method that can remove this redundancy.

Example

<pre> permissions = retrieve_participant_permissions(authorization)

participant.authorization = authorization
participant.can_submit = permissions[:can_submit]
participant.can_review = permissions[:can_review]
participant.can_take_quiz = permissions[:can_take_quiz]
participant.can_mentor = permissions[:can_mentor]</pre>

===Provide More Clarity in Function Names===

There are some functions that are somewhat unclear/vague in <code>participants_controller.rb</code>. For example, the <code>list_user_participants()</code> and <code>list_assignment_participants()</code>.

==== - Suggested Method Name Improvements ====

{| class="wikitable"
! Old Method Name
! New Method Name
! Notes
|-
| list_user_participants
| participants_by_user
| Clearer and more descriptive
|-
| list_assignment_participants
| participants_by_assignment
| Consistent with the above
|-
| show
| show_participant
| Explicit about what is shown
|-
| add
| create_participant_with_authorization
| Describes both creation and auth setup
|-
| update_authorization
| update_participant_authorization
| Makes the subject (participant) clear
|-
| destroy
| destroy_participant
| More descriptive for further use
|-
| filter_user_participants
| participants_for_user
| Highlights the purpose of the method
|-
| filter_assignment_participants
| participants_for_assignment
| Highlights the purpose of the method
|-
| validate_authorization
| validated_authorization
| Suggests return value is validated

|}

===Improve Documentation and Comments===

== Improved Method Comments ==

{| class="wikitable"
! Method
! Original Comment
! Refactored Comment
|-
| list_user_participants
| Return a list of participants for a given user
| Retrieves all participants associated with the specified user ID
|-
| list_assignment_participants
| Return a list of participants for a given assignment
| Retrieves all participants linked to the specified assignment ID
|-
| show
| Return a specified participant
| Fetch and return the participant with the given ID
|-
| add
| Assign the specified authorization to the participant and add them to an assignment
| Creates a new participant for a given assignment and assigns appropriate authorization and permissions
|-
| update_authorization
| Update the specified participant to the specified authorization
| Updates the participant’s authorization role and related permissions
|-
| destroy
| Delete a participant
| Deletes the participant identified by the given ID and returns a confirmation message
|-
| participant_params
| Permitted parameters for creating a Participant object
| Strong parameters: list of attributes allowed for participant creation or update
|-
| filter_user_participants
| Filters participants based on the provided user. Returns participants ordered by their IDs
| Returns a sorted list of participants filtered by user, if provided
|-
| filter_assignment_participants
| Filters participants based on the provided assignment. Returns participants ordered by their IDs
| Returns a sorted list of participants filtered by assignment, if provided
|-
| validate_authorization
| Validates that the authorization parameter is present and is one of the following valid authorizations: reader, reviewer, submitter, mentor
| Ensures authorization param is valid and returns it in lowercase; otherwise returns error response
|-
| find_user / find_assignment / find_participant
| Finds a user/assignment/participant by ID and returns it
| Fetches the corresponding record by ID; renders a not-found error if record does not exist
|}

===Proposed Testing Changes===

<ul>
<li>Add more descriptive comments for tests</li>
<li>Add test that checks that authorizations are updated correctly</li>
<li>Add test that checks that inputted path parameters are not missing and valid inputs</li>
<li>Tests at Line 222 and Line 231 are redundant, as the only difference in the test is the authorization, which would not affect what happens if a participant is not found</li>
</ul>

==Team==
'''Mentor'''

*Aniruddha Rajnekar <aarajnek@ncsu.edu>

'''Students'''

*Akhil Adusumilli <aadusum@ncsu.edu>

*Vansh Dodiya <vkdodiya@ncsu.edu>

*Brian Huynh <bhhuynh@ncsu.edu>

== Relevant Links ==

Pull Request (Unimplemented) [] 
GitHub Repository [https://github.com/Vansh17/refactoring-participants-controller.git] 
GitHub Project Board [https://github.com/users/Vansh17/projects/2] 
<code>participants_controller.rb</code> in Old Expertiza [https://github.com/expertiza/expertiza/blob/main/app/controllers/participants_controller.rb] 
<code>participants_helper.rb</code> in Old Expertiza [https://github.com/expertiza/expertiza/blob/main/app/helpers/participants_helper.rb]

CSC/ECE 517 Spring 2025 - E2531 Refactor participants controller.rb

2025-04-08T21:47:49Z

Vkdodiya: /* Next Steps (TEMP) */

==Introduction==
From the project description: "This project aims to refactor the <code>participants_controller.rb</code> and its helper class, <code>participants_helper.rb</code>, in the Expertiza system. The focus will be on improving code structure by implementing DRY and SOLID principles, enhancing readability with meaningful comments and clear naming conventions, and ensuring robustness through comprehensive RSpec testing." Since this is a refactoring project, we will also be utilizing Large Language Models (LLMs) to aid in development. More information on how we used them can be found in the section below.

==Use of Large Language Models (LLMs)==

For this project, we are using ChatGPT as an LLM helper in determining what issues there are within the code. The use of LLMs in this project will likely be limited to probing for potential issues that exist within the system.

Below we have organized the following prompts and a summary of the output in a table:

{| class="wikitable" style="margin-left:40px"
|-
! style="width: 25%" | Prompts !! LLM Output Summary
|-
| [Code from <code>participants_controller.rb</code>] Are there any ways where we can refactor the code to improve readability, DRYness, and clarity of error handling?
|| It recognized some of the issues we, as a team, had already identified and suggested fixes that were similar to what we outlined: Redundant JSON Rendering Code[https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2025_-_E2531_Refactor_participants_controller.rb#Simplifying_Redundant_JSON_Rendering_Code] and Simplifying the Assignment of Participant Fields[https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2025_-_E2531_Refactor_participants_controller.rb#Simplifying_the_Assignment_of_Participant_Fields]. Additionally, it suggested minor changes that we could implement, such as using <code>Participant.where(...)</code> instead of <code>Participant.all</code> to filter out the code more efficiently instead of getting all database instances every time, as well as the use of strong parameters in <code>add()</code> and <code>update_authorization()</code> to avoid having to implement custom parsing techniques. It also recommends renaming the <code>add()</code> function to something more specific in relation to its purpose (adding a <code>Participant</code> to an <code>Assignment</code>.
|-
| Potential Redundant Tests in <code>participants_controller_spec.rb</code>
|| The tests on line 222 and 231 are redundant as only the authorization differs. (Note: This should be investigated to see whether or not this is necessary)
|}

For more detailed information on what prompts we used and the output we got, please visit the page here: [https://docs.google.com/document/d/105_U_Coky-edx7n-tFhD2B5RqmVXxEsKPW_qUaf7bQU/edit?usp=sharing].

==Requirements==
Objectives:
<ul>
<li>Apply DRY principles to eliminate redundant code.</li>
<li>Ensure adherence to SOLID principles for better maintainability.</li>
<li>Use appropriate design patterns to optimize code architecture.</li>
<li>Write clear, informative comments and use meaningful naming conventions.</li>
<li>Test the refactored code extensively with RSpec to verify functionality.</li>
</ul>
Deliverables:
<ul>
<li>Refactored code for participants_controller.rb and helper class.</li>
<li>Comprehensive test suite and coverage report.</li>
<li>Updated and detailed documentation.</li>
<li>Video demonstration of the API functionality.</li>
</ul>

==Existing Issues==
<ul>
<li>There are some API functions that are currently not functioning properly, making it somewhat difficult to test</li>
<li>Some API functions are not returning the correct HTML status messages (e.g. test on line 136 returns 201 instead of 200)</li>
<li>Documentation and comments can be somewhat vague</li>
<ul>
<li>In-line comments should be more descriptive, explaining what the code does in more details</li>
<li>Tests are not described via comments, but in name alone; some more descriptive comments that explain the tests in more detail would be ideal</li>
</ul>
<li>Eliminate instances of redundant code</li>
<li>The method naming should be more descriptive</li>

</ul>

==Design / Proposed Solution (TEMP)==

===Simplifying Redundant JSON Rendering Code===

Many of the functions in the current implementation contain a conditional if-else statement that determines what HTML status code is returned alongside any necessary values that are requested. Due to its simple nature, it might be possible to reduce the amount of space this takes up by implementing a private helper method that would shorten the process.

Example:

<pre> if participants.nil?
render json: participants.errors, status: :unprocessable_entity
else
render json: participants, status: :ok
end</pre>

===Simplifying the Assignment of Participant Fields===

In the <code>add()</code> and <code>update</code> both take up a significant amount of space to assign values to database fields and are essentially the same in functionality (in terms of this specific section. We can remove redundancy by creating a method that can remove this redundancy.

Example

<pre> permissions = retrieve_participant_permissions(authorization)

participant.authorization = authorization
participant.can_submit = permissions[:can_submit]
participant.can_review = permissions[:can_review]
participant.can_take_quiz = permissions[:can_take_quiz]
participant.can_mentor = permissions[:can_mentor]</pre>

===Provide More Clarity in Function Names===

There are some functions that are somewhat unclear/vague in <code>participants_controller.rb</code>. For example, the <code>list_user_participants()</code> and <code>list_assignment_participants()</code>.

==== - Suggested Method Name Improvements ====

{| class="wikitable"
! Old Method Name
! New Method Name
! Notes
|-
| list_user_participants
| participants_by_user
| Clearer and more descriptive
|-
| list_assignment_participants
| participants_by_assignment
| Consistent with the above
|-
| show
| show_participant
| Explicit about what is shown
|-
| add
| create_participant_with_authorization
| Describes both creation and auth setup
|-
| update_authorization
| update_participant_authorization
| Makes the subject (participant) clear
|-
| destroy
| destroy_participant
| More descriptive for further use
|-
| filter_user_participants
| participants_for_user
| Highlights the purpose of the method
|-
| filter_assignment_participants
| participants_for_assignment
| Highlights the purpose of the method
|-
| validate_authorization
| validated_authorization
| Suggests return value is validated

|}

===Improve Documentation and Comments===

== Improved Method Comments ==

{| class="wikitable"
! Method
! Original Comment
! Refactored Comment
|-
| list_user_participants
| Return a list of participants for a given user
| Retrieves all participants associated with the specified user ID
|-
| list_assignment_participants
| Return a list of participants for a given assignment
| Retrieves all participants linked to the specified assignment ID
|-
| show
| Return a specified participant
| Fetch and return the participant with the given ID
|-
| add
| Assign the specified authorization to the participant and add them to an assignment
| Creates a new participant for a given assignment and assigns appropriate authorization and permissions
|-
| update_authorization
| Update the specified participant to the specified authorization
| Updates the participant’s authorization role and related permissions
|-
| destroy
| Delete a participant
| Deletes the participant identified by the given ID and returns a confirmation message
|-
| participant_params
| Permitted parameters for creating a Participant object
| Strong parameters: list of attributes allowed for participant creation or update
|-
| filter_user_participants
| Filters participants based on the provided user. Returns participants ordered by their IDs
| Returns a sorted list of participants filtered by user, if provided
|-
| filter_assignment_participants
| Filters participants based on the provided assignment. Returns participants ordered by their IDs
| Returns a sorted list of participants filtered by assignment, if provided
|-
| validate_authorization
| Validates that the authorization parameter is present and is one of the following valid authorizations: reader, reviewer, submitter, mentor
| Ensures authorization param is valid and returns it in lowercase; otherwise returns error response
|-
| find_user / find_assignment / find_participant
| Finds a user/assignment/participant by ID and returns it
| Fetches the corresponding record by ID; renders a not-found error if record does not exist
|}

===Proposed Testing Changes===

<ul>
<li>Add more descriptive comments for tests</li>
<li>Add test that checks that authorizations are updated correctly</li>
<li>Add test that checks that inputted path parameters are not missing and valid inputs</li>
<li>Tests at Line 222 and Line 231 are redundant, as the only difference in the test is the authorization, which would not affect what happens if a participant is not found</li>
</ul>

==Testing Plan (TEMP)==

From the previous implementation, there are 24 tests that are all passing. For more information about the previous testing plan, please refer to the previous implementation's page here: [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2484._Reimplement_participants_controller.rb]

===New/Modified Tests===
{| class="wikitable" style="margin-left:40px"
|-
! Test ID !! Test Description
|-
| 25 || Check whether <code>Participant</code> properly assigns the appropriate permissions when updating authorizations to each new role
|-
| 26 || Check the validity of incoming path parameters (Invalid: Non-Existent)
|}

==Team==
'''Mentor'''

*Aniruddha Rajnekar <aarajnek@ncsu.edu>

'''Students'''

*Akhil Adusumilli <aadusum@ncsu.edu>

*Vansh Dodiya <vkdodiya@ncsu.edu>

*Brian Huynh <bhhuynh@ncsu.edu>

== Relevant Links ==

Pull Request (Unimplemented) [] 
GitHub Repository [https://github.com/Vansh17/refactoring-participants-controller.git] 
GitHub Project Board [https://github.com/users/Vansh17/projects/2] 
<code>participants_controller.rb</code> in Old Expertiza [https://github.com/expertiza/expertiza/blob/main/app/controllers/participants_controller.rb] 
<code>participants_helper.rb</code> in Old Expertiza [https://github.com/expertiza/expertiza/blob/main/app/helpers/participants_helper.rb]

CSC/ECE 517 Spring 2025 - E2531 Refactor participants controller.rb

2025-04-08T21:47:26Z

Vkdodiya: /* Implementation (TEMP) */

==Introduction==
From the project description: "This project aims to refactor the <code>participants_controller.rb</code> and its helper class, <code>participants_helper.rb</code>, in the Expertiza system. The focus will be on improving code structure by implementing DRY and SOLID principles, enhancing readability with meaningful comments and clear naming conventions, and ensuring robustness through comprehensive RSpec testing." Since this is a refactoring project, we will also be utilizing Large Language Models (LLMs) to aid in development. More information on how we used them can be found in the section below.

==Use of Large Language Models (LLMs)==

For this project, we are using ChatGPT as an LLM helper in determining what issues there are within the code. The use of LLMs in this project will likely be limited to probing for potential issues that exist within the system.

Below we have organized the following prompts and a summary of the output in a table:

{| class="wikitable" style="margin-left:40px"
|-
! style="width: 25%" | Prompts !! LLM Output Summary
|-
| [Code from <code>participants_controller.rb</code>] Are there any ways where we can refactor the code to improve readability, DRYness, and clarity of error handling?
|| It recognized some of the issues we, as a team, had already identified and suggested fixes that were similar to what we outlined: Redundant JSON Rendering Code[https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2025_-_E2531_Refactor_participants_controller.rb#Simplifying_Redundant_JSON_Rendering_Code] and Simplifying the Assignment of Participant Fields[https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2025_-_E2531_Refactor_participants_controller.rb#Simplifying_the_Assignment_of_Participant_Fields]. Additionally, it suggested minor changes that we could implement, such as using <code>Participant.where(...)</code> instead of <code>Participant.all</code> to filter out the code more efficiently instead of getting all database instances every time, as well as the use of strong parameters in <code>add()</code> and <code>update_authorization()</code> to avoid having to implement custom parsing techniques. It also recommends renaming the <code>add()</code> function to something more specific in relation to its purpose (adding a <code>Participant</code> to an <code>Assignment</code>.
|-
| Potential Redundant Tests in <code>participants_controller_spec.rb</code>
|| The tests on line 222 and 231 are redundant as only the authorization differs. (Note: This should be investigated to see whether or not this is necessary)
|}

For more detailed information on what prompts we used and the output we got, please visit the page here: [https://docs.google.com/document/d/105_U_Coky-edx7n-tFhD2B5RqmVXxEsKPW_qUaf7bQU/edit?usp=sharing].

==Requirements==
Objectives:
<ul>
<li>Apply DRY principles to eliminate redundant code.</li>
<li>Ensure adherence to SOLID principles for better maintainability.</li>
<li>Use appropriate design patterns to optimize code architecture.</li>
<li>Write clear, informative comments and use meaningful naming conventions.</li>
<li>Test the refactored code extensively with RSpec to verify functionality.</li>
</ul>
Deliverables:
<ul>
<li>Refactored code for participants_controller.rb and helper class.</li>
<li>Comprehensive test suite and coverage report.</li>
<li>Updated and detailed documentation.</li>
<li>Video demonstration of the API functionality.</li>
</ul>

==Existing Issues==
<ul>
<li>There are some API functions that are currently not functioning properly, making it somewhat difficult to test</li>
<li>Some API functions are not returning the correct HTML status messages (e.g. test on line 136 returns 201 instead of 200)</li>
<li>Documentation and comments can be somewhat vague</li>
<ul>
<li>In-line comments should be more descriptive, explaining what the code does in more details</li>
<li>Tests are not described via comments, but in name alone; some more descriptive comments that explain the tests in more detail would be ideal</li>
</ul>
<li>Eliminate instances of redundant code</li>
<li>The method naming should be more descriptive</li>

</ul>

==Design / Proposed Solution (TEMP)==

===Simplifying Redundant JSON Rendering Code===

Many of the functions in the current implementation contain a conditional if-else statement that determines what HTML status code is returned alongside any necessary values that are requested. Due to its simple nature, it might be possible to reduce the amount of space this takes up by implementing a private helper method that would shorten the process.

Example:

<pre> if participants.nil?
render json: participants.errors, status: :unprocessable_entity
else
render json: participants, status: :ok
end</pre>

===Simplifying the Assignment of Participant Fields===

In the <code>add()</code> and <code>update</code> both take up a significant amount of space to assign values to database fields and are essentially the same in functionality (in terms of this specific section. We can remove redundancy by creating a method that can remove this redundancy.

Example

<pre> permissions = retrieve_participant_permissions(authorization)

participant.authorization = authorization
participant.can_submit = permissions[:can_submit]
participant.can_review = permissions[:can_review]
participant.can_take_quiz = permissions[:can_take_quiz]
participant.can_mentor = permissions[:can_mentor]</pre>

===Provide More Clarity in Function Names===

There are some functions that are somewhat unclear/vague in <code>participants_controller.rb</code>. For example, the <code>list_user_participants()</code> and <code>list_assignment_participants()</code>.

==== - Suggested Method Name Improvements ====

{| class="wikitable"
! Old Method Name
! New Method Name
! Notes
|-
| list_user_participants
| participants_by_user
| Clearer and more descriptive
|-
| list_assignment_participants
| participants_by_assignment
| Consistent with the above
|-
| show
| show_participant
| Explicit about what is shown
|-
| add
| create_participant_with_authorization
| Describes both creation and auth setup
|-
| update_authorization
| update_participant_authorization
| Makes the subject (participant) clear
|-
| destroy
| destroy_participant
| More descriptive for further use
|-
| filter_user_participants
| participants_for_user
| Highlights the purpose of the method
|-
| filter_assignment_participants
| participants_for_assignment
| Highlights the purpose of the method
|-
| validate_authorization
| validated_authorization
| Suggests return value is validated

|}

===Improve Documentation and Comments===

== Improved Method Comments ==

{| class="wikitable"
! Method
! Original Comment
! Refactored Comment
|-
| list_user_participants
| Return a list of participants for a given user
| Retrieves all participants associated with the specified user ID
|-
| list_assignment_participants
| Return a list of participants for a given assignment
| Retrieves all participants linked to the specified assignment ID
|-
| show
| Return a specified participant
| Fetch and return the participant with the given ID
|-
| add
| Assign the specified authorization to the participant and add them to an assignment
| Creates a new participant for a given assignment and assigns appropriate authorization and permissions
|-
| update_authorization
| Update the specified participant to the specified authorization
| Updates the participant’s authorization role and related permissions
|-
| destroy
| Delete a participant
| Deletes the participant identified by the given ID and returns a confirmation message
|-
| participant_params
| Permitted parameters for creating a Participant object
| Strong parameters: list of attributes allowed for participant creation or update
|-
| filter_user_participants
| Filters participants based on the provided user. Returns participants ordered by their IDs
| Returns a sorted list of participants filtered by user, if provided
|-
| filter_assignment_participants
| Filters participants based on the provided assignment. Returns participants ordered by their IDs
| Returns a sorted list of participants filtered by assignment, if provided
|-
| validate_authorization
| Validates that the authorization parameter is present and is one of the following valid authorizations: reader, reviewer, submitter, mentor
| Ensures authorization param is valid and returns it in lowercase; otherwise returns error response
|-
| find_user / find_assignment / find_participant
| Finds a user/assignment/participant by ID and returns it
| Fetches the corresponding record by ID; renders a not-found error if record does not exist
|}

===Proposed Testing Changes===

<ul>
<li>Add more descriptive comments for tests</li>
<li>Add test that checks that authorizations are updated correctly</li>
<li>Add test that checks that inputted path parameters are not missing and valid inputs</li>
<li>Tests at Line 222 and Line 231 are redundant, as the only difference in the test is the authorization, which would not affect what happens if a participant is not found</li>
</ul>

==Testing Plan (TEMP)==

From the previous implementation, there are 24 tests that are all passing. For more information about the previous testing plan, please refer to the previous implementation's page here: [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2484._Reimplement_participants_controller.rb]

===New/Modified Tests===
{| class="wikitable" style="margin-left:40px"
|-
! Test ID !! Test Description
|-
| 25 || Check whether <code>Participant</code> properly assigns the appropriate permissions when updating authorizations to each new role
|-
| 26 || Check the validity of incoming path parameters (Invalid: Non-Existent)
|}

==Next Steps (TEMP)==

==Team==
'''Mentor'''

*Aniruddha Rajnekar <aarajnek@ncsu.edu>

'''Students'''

*Akhil Adusumilli <aadusum@ncsu.edu>

*Vansh Dodiya <vkdodiya@ncsu.edu>

*Brian Huynh <bhhuynh@ncsu.edu>

== Relevant Links ==

Pull Request (Unimplemented) [] 
GitHub Repository [https://github.com/Vansh17/refactoring-participants-controller.git] 
GitHub Project Board [https://github.com/users/Vansh17/projects/2] 
<code>participants_controller.rb</code> in Old Expertiza [https://github.com/expertiza/expertiza/blob/main/app/controllers/participants_controller.rb] 
<code>participants_helper.rb</code> in Old Expertiza [https://github.com/expertiza/expertiza/blob/main/app/helpers/participants_helper.rb]

CSC/ECE 517 Spring 2025 - E2531 Refactor participants controller.rb

2025-04-08T05:51:52Z

Vkdodiya: /* Improve Documentation and Comments */

==Introduction==
From the project description: "This project aims to refactor the <code>participants_controller.rb</code> and its helper class, <code>participants_helper.rb</code>, in the Expertiza system. The focus will be on improving code structure by implementing DRY and SOLID principles, enhancing readability with meaningful comments and clear naming conventions, and ensuring robustness through comprehensive RSpec testing." Since this is a refactoring project, we will also be utilizing Large Language Models (LLMs) to aid in development. More information on how we used them can be found in the section below.

==Use of Large Language Models (LLMs)==

For this project, we are using ChatGPT as an LLM helper in determining what issues there are within the code.

Below we have organized the following prompts and a summary of the output in a table:

{| class="wikitable" style="margin-left:40px"
|-
! style="width: 25%" | Prompts !! LLM Output
|-
| [Code from <code>participants_controller.rb</code>] Are there any ways where we can refactor the code to improve readability, DRYness, and clarity of error handling? || It recognized some of the issues we, as a team, had already identified and suggested fixes that were similar to what we outlined: Redundant JSON Rendering Code[https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2025_-_E2531_Refactor_participants_controller.rb#Simplifying_Redundant_JSON_Rendering_Code] and Simplifying the Assignment of Participant Fields[https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2025_-_E2531_Refactor_participants_controller.rb#Simplifying_the_Assignment_of_Participant_Fields]. Additionally, it suggested minor changes that we could implement, such as using <code>Participant.where(...)</code> instead of <code>Participant.all</code> to filter out the code more efficiently instead of getting all database instances every time, as well as the use of strong parameters in <code>add()</code> and <code>update_authorization()</code> to avoid having to implement custom parsing techniques. It also recommends renaming the <code>add()</code> function to something more specific in relation to its purpose (adding a <code>Participant</code> to an <code>Assignment</code>.
|}

For more detailed information on what prompts we used and the output we got, please visit the page here: [https://docs.google.com/document/d/105_U_Coky-edx7n-tFhD2B5RqmVXxEsKPW_qUaf7bQU/edit?usp=sharing].

==Requirements==
Objectives:
<ul>
<li>Apply DRY principles to eliminate redundant code.</li>
<li>Ensure adherence to SOLID principles for better maintainability.</li>
<li>Use appropriate design patterns to optimize code architecture.</li>
<li>Write clear, informative comments and use meaningful naming conventions.</li>
<li>Test the refactored code extensively with RSpec to verify functionality.</li>
</ul>
Deliverables:
<ul>
<li>Refactored code for participants_controller.rb and helper class.</li>
<li>Comprehensive test suite and coverage report.</li>
<li>Updated and detailed documentation.</li>
<li>Video demonstration of the API functionality.</li>
</ul>

==Existing Issues==
<ul>
<li>There are some API functions that are currently not functioning properly, making it somewhat difficult to test</li>
<li>Some API functions are not returning the correct HTML status messages (e.g. test on line 136 returns 201 instead of 200)</li>
<li>Documentation and comments can be somewhat vague</li>
<ul>
<li>In-line comments should be more descriptive, explaining what the code does in more details</li>
<li>Tests are not described via comments, but in name alone; some more descriptive comments that explain the tests in more detail would be ideal</li>
</ul>
<li>Eliminate instances of redundant code</li>
<li>The method naming should be more descriptive</li>

</ul>

==Design / Proposed Solution (TEMP)==

===Simplifying Redundant JSON Rendering Code===

Many of the functions in the current implementation contain a conditional if-else statement that determines what HTML status code is returned alongside any necessary values that are requested. Due to its simple nature, it might be possible to reduce the amount of space this takes up by implementing a private helper method that would shorten the process.

Example:

<pre> if participants.nil?
render json: participants.errors, status: :unprocessable_entity
else
render json: participants, status: :ok
end</pre>

===Simplifying the Assignment of Participant Fields===

In the <code>add()</code> and <code>update</code> both take up a significant amount of space to assign values to database fields and are essentially the same in functionality (in terms of this specific section. We can remove redundancy by creating a method that can remove this redundancy.

Example

<pre> permissions = retrieve_participant_permissions(authorization)

participant.authorization = authorization
participant.can_submit = permissions[:can_submit]
participant.can_review = permissions[:can_review]
participant.can_take_quiz = permissions[:can_take_quiz]
participant.can_mentor = permissions[:can_mentor]</pre>

===Provide More Clarity in Function Names===

There are some functions that are somewhat unclear/vague in <code>participants_controller.rb</code>. For example, the <code>list_user_participants()</code> and <code>list_assignment_participants()</code>.

==== - Suggested Method Name Improvements ====

{| class="wikitable"
! Old Method Name
! New Method Name
! Notes
|-
| list_user_participants
| participants_by_user
| Clearer and more descriptive
|-
| list_assignment_participants
| participants_by_assignment
| Consistent with the above
|-
| show
| show_participant
| Explicit about what is shown
|-
| add
| create_participant_with_authorization
| Describes both creation and auth setup
|-
| update_authorization
| update_participant_authorization
| Makes the subject (participant) clear
|-
| destroy
| destroy_participant
| More descriptive for further use
|-
| filter_user_participants
| participants_for_user
| Highlights the purpose of the method
|-
| filter_assignment_participants
| participants_for_assignment
| Highlights the purpose of the method
|-
| validate_authorization
| validated_authorization
| Suggests return value is validated

|}

===Improve Documentation and Comments===

== Improved Method Comments ==

{| class="wikitable"
! Method
! Original Comment
! Refactored Comment
|-
| list_user_participants
| Return a list of participants for a given user
| Retrieves all participants associated with the specified user ID
|-
| list_assignment_participants
| Return a list of participants for a given assignment
| Retrieves all participants linked to the specified assignment ID
|-
| show
| Return a specified participant
| Fetch and return the participant with the given ID
|-
| add
| Assign the specified authorization to the participant and add them to an assignment
| Creates a new participant for a given assignment and assigns appropriate authorization and permissions
|-
| update_authorization
| Update the specified participant to the specified authorization
| Updates the participant’s authorization role and related permissions
|-
| destroy
| Delete a participant
| Deletes the participant identified by the given ID and returns a confirmation message
|-
| participant_params
| Permitted parameters for creating a Participant object
| Strong parameters: list of attributes allowed for participant creation or update
|-
| filter_user_participants
| Filters participants based on the provided user. Returns participants ordered by their IDs
| Returns a sorted list of participants filtered by user, if provided
|-
| filter_assignment_participants
| Filters participants based on the provided assignment. Returns participants ordered by their IDs
| Returns a sorted list of participants filtered by assignment, if provided
|-
| validate_authorization
| Validates that the authorization parameter is present and is one of the following valid authorizations: reader, reviewer, submitter, mentor
| Ensures authorization param is valid and returns it in lowercase; otherwise returns error response
|-
| find_user / find_assignment / find_participant
| Finds a user/assignment/participant by ID and returns it
| Fetches the corresponding record by ID; renders a not-found error if record does not exist
|}

===Proposed Testing Changes===

<ul>
<li>Add more descriptive comments for tests</li>
<li>Add test that checks that authorizations are updated correctly</li>
<li>Add test that checks that inputted path parameters are not missing and valid inputs</li>
<li>Tests at Line 222 and Line 231 are redundant, as the only difference in the test is the authorization, which would not affect what happens if a participant is not found</li>
</ul>

==Implementation (TEMP)==

==Testing Plan (TEMP)==

From the previous implementation, there are 24 tests that are all passing. For more information about the previous testing plan, please refer to the previous implementation's page here: [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2484._Reimplement_participants_controller.rb]

===New/Modified Tests===
{| class="wikitable" style="margin-left:40px"
|-
! Test ID !! Test Description
|-
| 1 || (TEMP)
|}

==Next Steps (TEMP)==

Key concerns identified include the overlap and redundancy within the current system:

==Team==
'''Mentor'''

*Aniruddha Rajnekar <aarajnek@ncsu.edu>

'''Students'''

*Akhil Adusumilli <aadusum@ncsu.edu>

*Vansh Dodiya <vkdodiya@ncsu.edu>

*Brian Huynh <bhhuynh@ncsu.edu>

== Relevant Links ==

Pull Request (Unimplemented) [] 
GitHub Repository [https://github.com/Vansh17/refactoring-participants-controller.git] 
GitHub Project Board [https://github.com/users/Vansh17/projects/2] 
<code>participants_controller.rb</code> in Old Expertiza [https://github.com/expertiza/expertiza/blob/main/app/controllers/participants_controller.rb] 
<code>participants_helper.rb</code> in Old Expertiza [https://github.com/expertiza/expertiza/blob/main/app/helpers/participants_helper.rb]

CSC/ECE 517 Spring 2025 - E2531 Refactor participants controller.rb

2025-04-08T05:28:20Z

Vkdodiya: /* Suggested Method Name Improvements */

CSC/ECE 517 Spring 2025 - E2531 Refactor participants controller.rb

2025-04-08T05:28:10Z

Vkdodiya: /* Suggested Method Name Improvements */

CSC/ECE 517 Spring 2025 - E2531 Refactor participants controller.rb

2025-04-08T05:28:02Z

Vkdodiya: /* Provide More Clarity in Function Names */

CSC/ECE 517 Spring 2025 - E2531 Refactor participants controller.rb

2025-04-08T05:27:46Z

Vkdodiya: /* Provide More Clarity in Function Names */

CSC/ECE 517 Spring 2025 - E2531 Refactor participants controller.rb

2025-04-08T05:27:22Z

Vkdodiya: /* Provide More Clarity in Function Names */

CSC/ECE 517 Spring 2025 - E2531 Refactor participants controller.rb

2025-04-08T00:24:15Z

Vkdodiya: /* Existing Issues */

CSC/ECE 517 Spring 2025 - E2531 Refactor participants controller.rb

2025-04-08T00:15:05Z

Vkdodiya: /* Existing Issues */

CSC/ECE 517 Spring 2025 - E2531 Refactor participants controller.rb

2025-04-08T00:11:32Z

Vkdodiya: /* Existing Issues */

CSC/ECE 517 Spring 2025 - E2531 Refactor participants controller.rb

2025-04-07T00:12:16Z

Vkdodiya: /* Introduction */

==Introduction==
This project aims to refactor the <code>participants_controller.rb</code> and its helper class, <code>participants_helper.rb</code>, in the Expertiza system. The focus will be on improving code structure by implementing DRY and SOLID principles, enhancing readability with meaningful comments and clear naming conventions, and ensuring robustness through comprehensive RSpec testing.

==Use of Large Language Models (LLMs)==

==Requirements==
Objectives:
<ul>
<li>Apply DRY principles to eliminate redundant code.</li>
<li>Ensure adherence to SOLID principles for better maintainability.</li>
<li>Use appropriate design patterns to optimize code architecture.</li>
<li>Write clear, informative comments and use meaningful naming conventions.</li>
<li>Test the refactored code extensively with RSpec to verify functionality.</li>
</ul>
Deliverables:
<ul>
<li>Refactored code for participants_controller.rb and helper class.</li>
<li>Comprehensive test suite and coverage report.</li>
<li>Updated and detailed documentation.</li>
<li>Video demonstration of the API functionality.</li>
</ul>

==Existing Issues==
<ul>
<li>There are some API functions that are currently not functioning properly:</li>

<ul>
<li>[API functions here]</li>
</ul>

<li>In-code comments should be more descriptive</li>
<li>Eliminate instances of redundant code</li>
</ul>

==Design / Proposed Solution (OLD/TEMP) ==

==Implementation (TEMP)==

==Testing Plan (TEMP)==

====Tests====
{| class="wikitable" style="margin-left:40px"
|-
! Test ID !! Test Description
|-
| 1 || Test 'assignment_index' with valid assignment ID - Should list participants
|}

==Next Steps (TEMP)==

Key concerns identified include the overlap and redundancy within the current system:

==Team==
'''Mentor'''

*Aniruddha Rajnekar <aarajnek@ncsu.edu>

'''Students'''

*Akhil Adusumilli <aadusum@ncsu.edu>

*Vansh Dodiya <vkdodiya@ncsu.edu>

*Brian Huynh <bhhuynh@ncsu.edu>

== Relevant Links ==

Pull Request (Unimplemented) [] 
GitHub Repository [https://github.com/Vansh17/refactoring-participants-controller.git] 
GitHub Project Board [https://github.com/users/Vansh17/projects/2] 
<code> participants_controller.rb </code> in Old Expertiza [https://github.com/expertiza/expertiza/blob/main/app/controllers/participants_controller.rb] 
<code> participants_helper.rb </code> in Old Expertiza [https://github.com/expertiza/expertiza/blob/main/app/helpers/participants_helper.rb]

CSC/ECE 517 Spring 2025 - E2531 Refactor participants controller.rb

2025-04-06T23:05:50Z

Vkdodiya: /* Relevant Links */

==About Expertiza==
Expertiza is an open-source project used to manage and submit assignments for CSC 517: Object-Oriented Design & Development as well as serving as a way for CSC 517 students to be able to apply their skills with the Ruby on Rails framework when contributing to the project. Using the site, students are able to access assignments that are assigned to them by the teaching staff or request topics that are opened to students at the instructor's discretion. Students are also able to submit multiple file types as deliverables (.pdf, links, etc.) in the event that an assignment requires multiple deliverables.

Expertiza's use in the classroom is also a way to familiarize students with the system as they use it throughout the semester before having to contribute to it themselves. This way, students can more accurately understand and infer why and how the codebase operates when they eventually begin work on it.

==Introduction==
From the project description: "This project aims to refactor the <code>participants_controller.rb</code> and its helper class, <code>participants_helper.rb</code>, in the Expertiza system. The focus will be on improving code structure by implementing DRY and SOLID principles, enhancing readability with meaningful comments and clear naming conventions, and ensuring robustness through comprehensive RSpec testing."

==Requirements==

==Existing Issues==

==Design / Proposed Solution (OLD/TEMP) ==

===<code> participants_controller.rb </code> Methods / API Calls===
{| class="wikitable" style="width: 100%;
!  #  !! Method !! Endpoint !! Description
|-
|1
|user_index
|GET <code> /participants/user/:user_id </code>
|Return a list of participants for a given user
|-
|2
|assignment_index
|GET <code> /participants/assignment/:assignment_id </code>
|Return a list of participants for a given assignment
|-
|3
|show
|GET <code> /participants/:id </code>
|Return a specified participant
|-
|4
|add
|POST <code> /participants/:authorization </code>
|Assign the specified authorization to the participant and add them to an assignment
|-
|5
|update_authorization
|PATCH <code> /participants/:id/:authorization </code>
|Update the specified participant to the specified authorization
|-
|6
|destroy
|DELETE <code> /participants/:id </code>
|Delete a participant
|-
|7
|participant_params
| -
|Permitted parameters for creating a Participant object
|}

The following methods were removed from <code> participants_controller.rb </code>:

===<code> participants_helper.rb </code> Methods===

===Pattern(s)===

===SOLID Principle(s)===

==Implementation (TEMP)==
===Implement <code> participants_controller.rb </code> Methods===
Refer to the [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2484._Reimplement_participants_controller.rb#participants_controller.rb_Methods_/_API_Calls <code> participants_controller.rb </code> Methods / API Calls] section for a brief overview of its use 

{| class="wikitable"
|+
! Old Method Name !! Action !! New Method Name
|-
| action_allowed? || Removed || -
|-
| controller_locale || Removed || -
|-
| list || Renamed and Separated || user_index
|-
| - || - || assignment_index
|-
| add || No Change || add
|-
| update_authorizations || Renamed || update_authorization
|-
| destroy || No Change || destroy
|-
| inherit || Removed || -
|-
| bequeath_all || Removed || -
|-
| change_handle || Removed || -
|-
| delete || Removed || -
|-
| view_copyright_grants || Removed || -
|-
| participant_params || No Change || participant_params
|-
| get_user_info || Removed || -
|-
| get_signup_topics_for_assignment || Removed || -
|-
| - || Added || show
|-
|}

====<code>user_index</code> Method====
Description:

This method retrieves a list of participants associated with a specific user. If a valid <code>user_id</code> is provided in the request, the system searches for the corresponding user and returns the list of participants linked to that user. If no participants are found, or if the user is invalid, an appropriate error response is returned. 

Parameters:

<code>user_id</code>: The ID of the user whose participants you want to retrieve. If the user does not exist, the method returns without further action. 

Behavior:

*The method validates the presence and existence of the <code>user_id</code>.
**If the <code>user_id</code> is invalid, the method then stops execution and does not proceed with participant retrieval.
**If a valid user is provided, then it will retrieve all participants and filter in the ones of the provided user.
***The final filtered list of participants is returned as a JSON response containing a confirmation message and a 200 OK status.
***If the final list would be empty, then it will return a JSON response containing validation errors and a 422 Unprocessable Entity status.

Code:
<pre> # Return a list of participants for a given user
# params - user_id
# GET /participants/user/:user_id
def user_index
user = find_user if params[:user_id].present?
return if params[:user_id].present? && user.nil?

participants = filter_user_participants(user)

if participants.nil?
render json: participants.errors, status: :unprocessable_entity
else
render json: participants, status: :ok
end
end
</pre>

====<code>assignment_index</code> Method====
Description:

This method retrieves a list of participants associated with a specific assignment. If a valid <code>assignment_id</code> is provided in the request, the system searches for the corresponding assignment and returns the list of participants linked to that assignment. If no participants are found, or if the assignment is invalid, an appropriate error response is returned. 

Parameters:

<code>assignment_id</code>: The ID of the assignment whose participants you want to retrieve. If the assignment does not exist, the method returns without further action. 

Behavior:

*The method validates the presence and existence of the <code>assignment_id</code>.
**If the assignment_id is invalid, the method then stops execution and does not proceed with participant retrieval.
**If a valid assignment is provided, then it will retrieve all participants and filter in the ones of the provided assignment.
***The final filtered list of participants is returned as a JSON response containing a confirmation message and a 200 OK status.
***If the final list would be empty, then it will return a JSON response containing validation errors and a 422 Unprocessable Entity status.

Code:
<pre>
# Return a list of participants for a given assignment
# params - assignment_id
# GET /participants/assignment/:assignment_id
def assignment_index
assignment = find_assignment if params[:assignment_id].present?
return if params[:assignment_id].present? && assignment.nil?

participants = filter_assignment_participants(assignment)

if participants.nil?
render json: participants.errors, status: :unprocessable_entity
else
render json: participants, status: :ok
end
end</pre>

====<code>add</code> Method====

Description:

Assigns the specified authorization to a participant and adds them to a given assignment. It performs the necessary validations to ensure that the user, assignment, and authorization are valid before proceeding. If all validations pass, it associates the participant with the assignment and applies the relevant permissions based on the authorization.

Parameters:

<code>user_id</code> (required): The ID of the user to be added as a participant. 
<code>assignment_id</code> (required): The ID of the assignment the user will be added to. 
<code>authorization</code> (required): The authorization ID to define the user's permissions within the assignment.

Behavior:

*Validates and retrieves the user based on the provided <code>user_id</code>. If the user is not found, the method terminates.
*Validates and retrieves the assignment based on the provided <code>assignment_id</code>. If the assignment is not found, the method terminates.
*Validates and retrieves the authorization based on the provided <code>assignment_id</code>. If the authorization is not found, the method terminates.
*Builds a new participant instance linked to the validated user and assignment, with the appropriate permissions obtained from authorization.
*Attempts to save the participant:
**If successful: Returns a JSON response containing the created participant and a 201 Created status.
**If unsuccessful: Returns a JSON response containing validation errors and a 422 Unprocessable Entity status.

Code:
<pre> # Assign the specified authorization to the participant and add them to an assignment
# POST /participants/:authorization
def add
user = find_user
return unless user

assignment = find_assignment
return unless assignment

authorization = validate_authorization
return unless authorization

permissions = retrieve_participant_permissions(authorization)

participant = assignment.add_participant(user)
participant.authorization = authorization
participant.can_submit = permissions[:can_submit]
participant.can_review = permissions[:can_review]
participant.can_take_quiz = permissions[:can_take_quiz]
participant.can_mentor = permissions[:can_mentor]

if participant.save
render json: participant, status: :created
else
render json: participant.errors, status: :unprocessable_entity
end
end</pre>

====<code>update_authorization</code> Method ====
Description:

Updates the authorization and associated permissions for an existing participant.

Parameters:

<code>participant_id</code> (required): The ID of the participant whose authorization is being updated. 
<code>authorization</code> (required): The new authorization ID to assign to the participant.

Behavior:
*Validates the provided authorization using <code>validate_authorization</code> after finding the participant. If the authorization is missing, the method halts and returns a 422 Unprocessable Entity status.
*Upon successful validation of the authorization, the method retrieves the permissions associated with the authorization by calling <code>retrieve_participant_permissions</code>.
*Updates the participant's authorization field with the new authorization. Relevant permissions (can_submit, can_review, can_take_quiz, and can_mentor) are also updated based on the authorization’s values.
*Attempts to save the updated participant
**If the participant is successfully updated and saved to the database, a JSON response with the updated participant details and a 201 Created status is returned.
**If there are validation errors or the update fails, a JSON response with error details and a 422 Unprocessable Entity status is returned.

Code:
<pre> # Update the specified participant to the specified authorization
# PATCH /participants/:id/:authorization
def update_authorization
participant = find_participant
return unless participant

authorization = validate_authorization
return unless authorization

permissions = retrieve_participant_permissions(authorization)

participant.authorization = authorization
participant.can_submit = permissions[:can_submit]
participant.can_review = permissions[:can_review]
participant.can_take_quiz = permissions[:can_take_quiz]
participant.can_mentor = permissions[:can_mentor]

if participant.save
render json: participant, status: :created
else
render json: participant.errors, status: :unprocessable_entity
end
end</pre>

====<code>destroy</code> Method====

Description:

Deletes a specified participant based on the provided ID.

Parameters:

*<code>id</code> (required): The ID of the participant to be deleted.

Behavior:

*Retrieves the participant using the provided <code>id</code>.
*Attempts to delete the participant:
**If successful: Returns a JSON response containing a confirmation message and a 200 OK status.
**If unsuccessful: Returns a JSON response containing validation errors and a 422 Unprocessable Entity status.

Code:
<pre> # Delete a participant
# params - id
# DELETE /participants/:id
def destroy
participant = Participant.find_by(id: params[:id])

if participant.nil?
render json: { error: 'Not Found' }, status: :not_found
elsif participant.destroy
successful_deletion_message = if params[:team_id].nil?
"Participant #{params[:id]} in Assignment #{params[:assignment_id]} has been deleted successfully!"
else
"Participant #{params[:id]} in Team #{params[:team_id]} of Assignment #{params[:assignment_id]} has been deleted successfully!"
end
render json: { message: successful_deletion_message }, status: :ok
else
render json: participant.errors, status: :unprocessable_entity
end
end</pre>

====<code>show</code> Method (TEMP)====

Description:

Retrieves and returns a specific participant based on the provided ID.

Parameters:

*<code>id</code> (required): The ID of the participant to be retrieved.

Behavior:

*Fetches the participant from the database using the provided <code>id</code>.
*Attempts to fetch the participant:
**If successful: Returns a JSON response containing a confirmation message and a 200 OK status.
**If unsuccessful: Returns a JSON response containing validation errors and a 422 Unprocessable Entity status.

Code:
<pre> # Return a specified participant
# params - id
# GET /participants/:id
def show
participant = Participant.find(params[:id])

if participant.nil?
render json: participant.errors, status: :unprocessable_entity
else
render json: participant, status: :created
end
end</pre>

====<code>participant_params</code> Method====

Description:

Defines the permitted parameters for creating or updating a participant object.

Parameters:

The method expects a participant object within the request parameters. It permits the following attributes:

*<code>user_id</code> (required): The ID of the user associated with the participant.
*<code>assignment_id</code> (required): The ID of the assignment linked to the participant.
*<code>authorization</code> (optional): A string indicating the "Role" of the user, that being one of the following: reader, reviewer, submitter, or mentor.
*<code>can_submit</code> (optional): A boolean indicating whether the participant has submit permissions granted.
*<code>can_review</code> (optional): A boolean indicating whether the participant has review permissions granted.
*<code>can_take_quiz</code> (optional): A boolean indicating whether the participant has take_quiz permissions granted.
*<code>can_mentor</code> (optional): A boolean indicating whether the participant has mentor permissions granted.
*<code>handle</code> (optional): A string containing the participant's display name.
*<code>team_id</code> (optional): The ID of the team the participant belongs to.
*<code>join_team_request_id</code> (optional): The ID of any pending team join request related to the participant.
*<code>permission_granted</code> (optional): A boolean indicating whether the participant has specific permissions granted.
*<code>topic</code> (optional): The topic assigned to the participant (could be a string or other data type depending on the application context).
*<code>current_stage</code> (optional): The current progress stage of the participant.
*<code>stage_deadline</code> (optional): The deadline for the current stage.

Behavior:

*Ensures that only allowed parameters are passed when creating a participant object.

====<code>filter_user_participants</code> Method ====
Description:

Retrieves and filters participants based on the provided user.

Parameters:

*<code>user</code> (required): An instance of the user model. If provided, the method filters participants associated with this user.

Behavior:

*Fetches all participants from the database.
*The method filters participants where the <code>user_id</code> matches the given user's ID.
*The final list of participants is then ordered by their id in ascending order.

Code:
<pre> # Filters participants based on the provided user
# Returns participants ordered by their IDs
def filter_user_participants(user)
participants = Participant.all
participants = participants.where(user_id: user.id) if user
participants.order(:id)
end</pre>

====<code>filter_assignment_participants</code> Method ====
Description:

Retrieves and filters participants based on the provided assignment.

Parameters:

*<code>assignment</code> (required): An instance of the assignment model. If provided, the method filters participants associated with this assignment.

Behavior:

*Fetches all participants from the database.
*The method filters participants where the assignment_id matches the given assignment's ID.
*The final list of participants is then ordered by their id in ascending order.

Code:
<pre> def filter_assignment_participants(assignment)
participants = Participant.all
participants = participants.where(assignment_id: assignment.id) if assignment
participants.order(:id)
end</pre>

====<code>find_user</code> Method ====

Description:
Retrieves a User object based on the user_id provided. If the user is not found, it returns an error response and halts further execution.

Parameters:

<code>user_id</code> (optional): The ID of the user to be retrieved. Extracted from the permitted parameters.

Behavior:

*Attempts to find the user in the database using the provided <code>user_id</code>.
**If the user is not found (nil), it renders a JSON response with an error message and 404 Not Found status.
**If the user exists, it returns the user object with 200 OK status.

Code:
<pre> def find_user
user_id = params[:user_id]
user = User.find_by(id: user_id)
render json: { error: 'User not found' }, status: :not_found unless user
user
end</pre>

====<code>find_assignment</code> Method ====

Description:

Retrieves an assignment object based on the <code>assignment_id</code> provided. If the assignment is not found, it returns an error response and halts further execution.

Parameters:

<code>assignment_id</code> (optional): The ID of the assignment to be retrieved. Extracted from the permitted parameters.

Behavior:

*Attempts to find the assignment in the database using the provided <code>assignment_id</code>.
**If the assignment is not found (nil), it renders a JSON response with an error message and 404 Not Found status.
**If the assignment exists, it returns the assignment object with 200 OK status.

Code:
<pre> def find_assignment
assignment_id = params[:assignment_id]
assignment = Assignment.find_by(id: assignment_id)
render json: { error: 'Assignment not found' }, status: :not_found unless assignment
assignment
end</pre>

====<code>find_participant</code> Method ====

Description:

Retrieves a participant object based on the <code>participant_id</code> provided. If the participant is not found, it returns an error response and halts further execution.

Parameters:

<code>participant_id</code> (optional): The ID of the participant to be retrieved. Extracted from the permitted parameters.

Behavior:

*Attempts to find the participant in the database using the provided <code>participant_id</code>.
**If the participant is not found (nil), it renders a JSON response with an error message and 404 Not Found status.
**If the participant exists, it returns the participant object with 200 OK status.

Code:
<pre> def find_participant
participant_id = params[:id]
participant = Participant.find_by(id: participant_id)
render json: { error: 'Participant not found' }, status: :not_found unless participant
participant
end</pre>

====<code>validate_authorization</code> Method ====
Description:
*Validates the authorization parameter provided in the request. Ensures that the authorization value is one of the accepted roles: reader, reviewer, submitter, or mentor.

Parameters:
*<code>authorization</code> (required): A string representing the participant’s authorization role. This value must be one of the following: reader, reviewer, submitter, or mentor.

Behavior:
*If the authorization parameter is present, it is converted to lowercase to ensure case-insensitive comparison.
*If the authorization parameter is not provided, the method renders a 422 Unprocessable Entity response with an error message indicating that a participant must have an authorization.
*If the authorization value is provided but does not match one of the valid roles (reader, reviewer, submitter, or mentor), the method renders a 422 Unprocessable Entity response with an error message listing the valid options.
*If the authorization value is valid, the method returns the authorization string.

Code:
<pre> def validate_authorization
valid_authorizations = %w[reader reviewer submitter mentor]
authorization = params[:authorization]
authorization = authorization.downcase if authorization.present?

unless authorization
render json: { error: 'authorization is required' }, status: :unprocessable_entity
return
end

unless valid_authorizations.include?(authorization)
render json: { error: 'authorization not valid. Valid authorizations are: Reader, Reviewer, Submitter, Mentor' },
status: :unprocessable_entity
return
end

authorization
end
end</pre>

===Import from <code> participants_helper.rb </code>===
Refer to the [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2484._Reimplement_participants_controller.rb#participants_helper.rb_Methods <code> participants_helper.rb </code> Methods] section for all design-related inquiries 

{| class="wikitable"
|+
! Old Method Name !! Action !! New Method Name
|-
| upload_users || Removed || -
|-
| define_attributes || Removed || -
|-
| define_user || Removed || -
|-
| create_new_user || Removed || -
|-
| add_user_to_assignment || Removed || -
|-
| add_user_to_course || Removed || -
|-
| get_config || Removed || -
|-
| store_item || Removed || -
|-
| participant_permissions || Renamed || retrieve_participant_permissions
|}

====<code>retrieve_participant_permissions</code> Method====

Description:
*Retrieves the permissions associated with a given authorization role. The permissions determine the actions a participant can perform (e.g., submitting, reviewing, taking quizzes, or mentoring). The method merges default permissions with role-specific overrides and returns the final set of permissions for the specified authorization.

Parameters:

*<code>authorization</code> (required): A string representing the participant's authorization role. This value should be one of the following: reader, reviewer, submitter, or mentor.
Behavior:
*The method defines a set of default permissions that are assigned to all participants unless overridden by their specific authorization role. The default permissions allow submitting, reviewing, and taking quizzes, while disallowing mentoring.
*A permissions_map is used to define role-specific overrides for the default permissions:
**reader: Cannot submit, but can review and take quizzes.
**reviewer: Cannot submit or take quizzes, but can review.
**submitter: Cannot review or take quizzes, but can submit.
**mentor: Can mentor, and has the same permissions as a reader for other actions.
*The method merges the default permissions with the overrides for the specified authorization. The final set of permissions is returned.

Code:
<pre> def retrieve_participant_permissions(authorization)
default_permissions = {
can_submit: true,
can_review: true,
can_take_quiz: true,
can_mentor: false
}

permissions_map = {
'reader' => { can_submit: false },
'reviewer' => { can_submit: false, can_take_quiz: false },
'submitter' => { can_review: false, can_take_quiz: false },
'mentor' => { can_mentor: true }
}

default_permissions.merge(permissions_map[authorization])
end
end</pre>

===API Creation===

===Testing with rswag===

===Swagger UI Video Documentation===

==Testing Plan==
'''rswag''' 
We will use rswag to test and document our project’s API endpoints. Rswag integrates RSpec testing with Swagger, allowing us to define test cases in RSpec to validate functionality while automatically generating interactive Swagger documentation. This documentation, accessible through Swagger UI, provides developers and stakeholders with a user-friendly way to explore and interact with our API endpoints.

====Tests====
{| class="wikitable" style="margin-left:40px"
|-
! Test ID !! Test Description
|-
| 1 || (TEMP)
|}

==Next Steps==

Key concerns identified include the overlap and redundancy within the current system:

==Team==
'''Mentor'''

*Aniruddha Rajnekar <aarajnek@ncsu.edu>

'''Students'''

*Akhil Adusumilli <aadusum@ncsu.edu>

*Vansh Dodiya <vkdodiya@ncsu.edu>

*Brian Huynh <bhhuynh@ncsu.edu>

== Relevant Links ==

Pull Request (Unimplemented) [] 
GitHub Repository [https://github.com/Vansh17/refactoring-participants-controller.git] 
GitHub Project Board [https://github.com/users/Vansh17/projects/2] 
<code> participants_controller.rb </code> in Old Expertiza [https://github.com/expertiza/expertiza/blob/main/app/controllers/participants_controller.rb] 
<code> participants_helper.rb </code> in Old Expertiza [https://github.com/expertiza/expertiza/blob/main/app/helpers/participants_helper.rb]

CSC/ECE 517 Spring 2025 - E2511. Reimplement participants controller.rb

2025-03-26T02:59:44Z

Vkdodiya: /* Resources */

CSC/ECE 517 Spring 2025 - E2511. Reimplement participants controller.rb

2025-03-25T03:56:26Z

Vkdodiya: /* Resources */

CSC/ECE 517 Spring 2025 - E2511. Reimplement participants controller.rb

2025-03-25T03:31:05Z

Vkdodiya: /* Resources */

CSC/ECE 517 Spring 2025 - E2511. Reimplement participants controller.rb

2025-03-25T02:01:57Z

Vkdodiya: /* Resources */

CSC/ECE 517 Spring 2025 - E2511. Reimplement participants controller.rb

2025-03-25T01:58:25Z

Vkdodiya: /* Resources */

CSC/ECE 517 Spring 2025 - E2511. Reimplement participants controller.rb

2025-03-25T01:57:32Z

Vkdodiya: /* How it Works */

CSC/ECE 517 Spring 2025 - E2511. Reimplement participants controller.rb

2025-03-25T01:47:17Z

Vkdodiya: /* Method: add */

CSC/ECE 517 Spring 2025 - E2511. Reimplement participants controller.rb

2025-03-25T01:46:53Z

Vkdodiya: /* Example Test: Get Participants by User ID */

CSC/ECE 517 Spring 2025 - E2511. Reimplement participants controller.rb

2025-03-25T01:42:11Z

Vkdodiya: /* Endpoint: GET /api/v1/participants/user/:user_id */

CSC/ECE 517 Spring 2025 - E2511. Reimplement participants controller.rb

2025-03-25T01:40:06Z

Vkdodiya: /* Structure */

CSC/ECE 517 Spring 2025 - E2511. Reimplement participants controller.rb

2025-03-25T01:35:45Z

Vkdodiya: /* Authentication */

CSC/ECE 517 Spring 2025 - E2511. Reimplement participants controller.rb

2025-03-25T01:35:12Z

Vkdodiya: /* Benefits */

CSC/ECE 517 Spring 2025 - E2511. Reimplement participants controller.rb

2025-03-25T01:34:57Z

Vkdodiya: /* Error Handling Covered */

CSC/ECE 517 Spring 2025 - E2511. Reimplement participants controller.rb

2025-03-25T01:34:33Z

Vkdodiya: /* API Testing with RSpec and Swagger */

CSC/ECE 517 Spring 2025 - E2511. Reimplement participants controller.rb

2025-03-25T01:33:06Z

Vkdodiya: /* API Testing with RSpec and Swagger */

CSC/ECE 517 Spring 2025 - E2511. Reimplement participants controller.rb

2025-03-25T01:32:00Z

Vkdodiya: /* Role-Based Strategy Pattern */

CSC/ECE 517 Spring 2025 - E2511. Reimplement participants controller.rb

2025-03-25T01:27:00Z

Vkdodiya: /* Team Members */

CSC/ECE 517 Spring 2025 - E2511. Reimplement participants controller.rb

2025-03-25T00:06:42Z

Vkdodiya: /* SOLID Principles in participants_controller.rb */

CSC/ECE 517 Spring 2025 - E2511. Reimplement participants controller.rb

2025-03-25T00:06:20Z

Vkdodiya: /* SOLID Principles in participants_controller.rb */

CSC/ECE 517 Spring 2025 - E2511. Reimplement participants controller.rb

2025-03-25T00:06:05Z

Vkdodiya: /* participants_helper.rb Methods */

CSC/ECE 517 Spring 2025 - E2511. Reimplement participants controller.rb

2025-03-25T00:05:20Z

Vkdodiya: /* participants_helper.rb Methods */

CSC/ECE 517 Spring 2025 - E2511. Reimplement participants controller.rb

2025-03-25T00:04:48Z

Vkdodiya: /* participants_helper.rb Methods */

== About Expertiza ==
[https://expertiza.github.io Expertiza] is an open source project based on [https://rubyonrails.org Ruby on Rails] framework. Expertiza allows the instructor to create new assignments and customize new or existing assignments. It also allows the instructor to create a list of topics the students can sign up for. Students can form teams in Expertiza to work on various projects and assignments. Students can also peer review other students' submissions. Expertiza supports submission across various document types, including the URLs and wiki pages.

== Introduction ==
This project aims to reimplement the <code>participants_controller.rb</code> and <code>participants_helper.rb</code> in the new Expertiza system. The <code>participants_controller.rb</code> manages participants within assignments, and this reimplementation focuses on streamlining its methods, eliminating redundancy, and enhancing code readability and maintainability.

== Requirements ==
* Implement <code>participants_controller.rb</code> Methods: Fully implement each controller method with the same functionality as the current controller.
* Import from <code>participants_helper.rb</code>: Integrate relevant helper methods to streamline functionality and remove redundancy.
* API Creation: Expose API endpoints for all necessary methods to enable seamless access and integration from the frontend. Ensure that each endpoint follows best practices for RESTful API design, including proper error handling and secure data access.
* Testing with rswag: Create test cases for all methods, focusing on edge cases, and generate rswag documentation.
* Swagger UI Video Documentation: Record a video walkthrough of API endpoints in Swagger UI, showcasing each method’s functionality.

== Tasks to be Completed ==
* Implement participants_controller.rb Methods: Develop each method with the same functionality as the existing controller.
* Refactor and Integrate Helper Methods: Import relevant methods from participants_helper.rb to improve efficiency and eliminate code duplication.
* API Development: Expose RESTful API endpoints for necessary operations, ensuring proper error handling and secure data access.
* Testing with Rswag: Implement comprehensive test cases, including edge cases, and generate Rswag documentation.
* Swagger UI Documentation: Create a video walkthrough demonstrating API endpoints and their functionalities in Swagger UI.
* Make sure to write intuitive test cases for this controller using RSpec

= Reimplement participants_controller.rb =

== Previous participants_controller.rb Methods / API Calls ==

{| class="wikitable"
! #
! Method
! Endpoint
! Description
|-
| 1
| user_index
| <code>GET /participants/user/:user_id</code>
| Return a list of participants for a given user
|-
| 2
| assignment_index
| <code>GET /participants/assignment/:assignment_id</code>
| Return a list of participants for a given assignment
|-
| 3
| show
| <code>GET /participants/:id</code>
| Return a specified participant
|-
| 4
| add
| <code>POST /participants/:authorization</code>
| Assign the specified authorization to the participant and add them to an assignment
|-
| 5
| update_authorization
| <code>PATCH /participants/:id/:authorization</code>
| Update the specified participant to the specified authorization
|-
| 6
| destroy
| <code>DELETE /participants/:id</code>
| Delete a participant
|-
| 7
| participant_params
| -
| Permitted parameters for creating a Participant object
|}

== participants_controller.rb Methods / API Calls ==

{| class="wikitable"
! #
! HTTP Method
! Endpoint
! Method Name
! Description
|-
| 1
| GET
| /api/v1/participants
| index
| List all participants
|-
| 2
| POST
| /api/v1/participants
| create
| Create a new participant
|-
| 3
| GET
| /api/v1/participants/:id
| show
| Retrieve a participant by ID
|-
| 4
| PUT
| /api/v1/participants/:id
| update
| Update a participant
|-
| 5
| DELETE
| /api/v1/participants/:id
| destroy
| Delete a participant
|-
| 6
| GET
| /api/v1/participants/user/:user_id
| user_index
| Get participants by user ID
|-
| 7
| GET
| /api/v1/participants/assignment/:assignment_id
| assignment_index
| Get participants by assignment ID
|-
| 8
| POST
| /api/v1/participants/:id/:authorization
| add
| Add a participant with authorization
|-
| 9
| PATCH
| /api/v1/participants/:id/:authorization
| update_authorization
| Update participant authorization
|}

== Removed Methods from participants_controller.rb ==

The following methods were removed as part of the reimplementation:

* <code>action_allowed?</code> – No impact on functionality.
* <code>controller_locale</code> – No impact on functionality.
* <code>inherit</code> – Redundant due to lack of direct relation between Course and Participant.
* <code>bequeath_all</code> – Same reason as above.
* <code>change_handle</code> – `User` model already has `handle`, so it's redundant.
* <code>delete</code> – Replaced by `remove_participant` in <code>assignments_controller.rb</code>.
* <code>view_copyright_grants</code> – Old implementation was incorrect.
* <code>get_user_info</code> – Covered by `belongs_to` relation in the `Participant` model.
* <code>get_signup_topics_for_assignment</code> – Now handled by `sign_up_topics_controller.rb`.

== Implementation Summary ==

<code>Api::V1::ParticipantsController</code> was restructured to:
* Follow RESTful conventions (`index`, `show`, `create`, `update`, `destroy`)
* Add custom endpoints for `user_index`, `assignment_index`, and `update_authorization`
* Leverage strong parameters and `before_action` filters
* Integrate logic from `participants_helper.rb` (like `participant_permissions`)
* Improve error handling using status codes and JSON messages

== participants_controller.rb Methods ==
The following custom methods were added to handle participant creation with role-based authorization and to update existing participant permissions based on a new authorization.

=== Method: add ===

```ruby
#adding a participant with authorization
def add
assignment = Assignment.find(params[:id])
user = User.find_or_create_by(user_params)

# Now you can safely use `user` below
handle = "#{user.name.parameterize}-#{SecureRandom.hex(2)}"

permissions = participant_permissions(params[:authorization])

participant = assignment.participants.create!(
user: user,
handle: handle,
can_submit: permissions[:can_submit],
can_review: permissions[:can_review],
can_take_quiz: permissions[:can_take_quiz],
can_mentor: permissions[:can_mentor]
)

render json: participant, status: :created
end

=== Method: update_authorization ===
def update_authorization
participant = Participant.find(params[:id])

permissions = participant_permissions(params[:authorization])

participant.update!(
can_submit: permissions[:can_submit],
can_review: permissions[:can_review],
can_take_quiz: permissions[:can_take_quiz],
can_mentor: permissions[:can_mentor]
)

render json: participant, status: :ok
end

== participants_helper.rb Methods ==

The <code>ParticipantsHelper</code> module contains utility methods used to assign roles and permissions to a Participant. Compared to the original implementation, this version has been heavily simplified and cleaned up.

Only the following method is included in the reimplementation:

* <code>retrieve_participant_permissions</code> – Returns a hash of permission flags based on the participant’s assigned role.
This method sets default permissions (submit, review, quiz, mentor) and overrides them based on the role passed in. The supported roles are:
* <code>reader</code>
* <code>reviewer</code>
* <code>submitter</code>
* <code>mentor</code>

```ruby
def retrieve_participant_permissions(authorization)
default_permissions = {
can_submit: true,
can_review: true,
can_take_quiz: true,
can_mentor: false
}

permissions_map = {
'reader' => { can_submit: false },
'reviewer' => { can_submit: false, can_take_quiz: false },
'submitter' => { can_review: false, can_take_quiz: false },
'mentor' => { can_mentor: true }
}

default_permissions.merge(permissions_map[authorization])
end

class Api::V1::ParticipantsController < ApplicationController
include ParticipantsHelper
# autocomplete :user, :name
def index
participants = Participant.all
render json: participants
end
# ************************************************************
#keeping this commented as to test
# def action_allowed?
# if %w[change_handle update_duties].include? params[:action]
# current_user_has_student_privileges?
# else
# current_user_has_ta_privileges?
# end
# end
# ************************************************************
#redundant by may be required later
# def action_allowed?
# has_required_role?('Teaching Assistant')
# end
# ************************************************************

def create
@participant = Participant.new(participant_params)
if @participant.save
render json: @participant, status: :created
else
render json: { errors: @participant.errors.full_messages }, status: :unprocessable_entity
end
end

before_action :set_participant, only: [:show, :update, :destroy]

# GET /api/v1/participants/:id
def show
render json: @participant
end

#getting the user by user_index and retrive and how on swagger ui
def user_index
participants = Participant.where(user_id: params[:user_id])
render json: participants, status: :ok
end

#updating the participant by request body of example { "can_submit": true, "can_review": true}
def update
if @participant.update(participant_params)
render json: @participant, status: :ok
else
render json: { errors: @participant.errors.full_messages }, status: :unprocessable_entity
end
end

#destroying the user by the id of the specific user
def destroy
participant = Participant.find(params[:id])
participant.destroy
render json: { message: "Participant deleted successfully" }, status: :ok
rescue ActiveRecord::RecordNotFound
render json: { error: "Participant not found" }, status: :not_found
end

#finding partcipant by assignment id
def assignment_index
participants = Participant.where(assignment_id: params[:assignment_id])
render json: participants, status: :ok
end

# def add
# handle = "#{user.name.parameterize}-#{SecureRandom.hex(2)}"

# assignment_id = params[:id]
# authorization = params[:authorization]
# user_name = params[:user][:name]

# user = User.find_by(name: user_name)
# return render json: { error: "User not found" }, status: :not_found if user.nil?

# assignment = Assignment.find(assignment_id)
# permissions = participant_permissions(authorization)

# participant = assignment.participants.create(
# user: user,
# handle: handle,
# can_submit: permissions[:can_submit],
# can_review: permissions[:can_review],
# can_take_quiz: permissions[:can_take_quiz],
# can_mentor: permissions[:can_mentor]
# )

# if participant.persisted?
# render json: participant, status: :created
# else
# render json: { errors: participant.errors.full_messages }, status: :unprocessable_entity
# end
# end

#adding a participant with authorization
def add
assignment = Assignment.find(params[:id])
user = User.find_or_create_by(user_params) # 👈 You were probably missing this line

# Now you can safely use `user` below
handle = "#{user.name.parameterize}-#{SecureRandom.hex(2)}"

permissions = participant_permissions(params[:authorization])

participant = assignment.participants.create!(
user: user,
handle: handle,
can_submit: permissions[:can_submit],
can_review: permissions[:can_review],
can_take_quiz: permissions[:can_take_quiz],
can_mentor: permissions[:can_mentor]
)

render json: participant, status: :created
end

#updating authorization of the participants
def update_authorization
participant = Participant.find(params[:id])

permissions = participant_permissions(params[:authorization])

participant.update!(
can_submit: permissions[:can_submit],
can_review: permissions[:can_review],
can_take_quiz: permissions[:can_take_quiz],
can_mentor: permissions[:can_mentor]
)

render json: participant, status: :ok
end

private

def user_params
params.require(:user).permit(:name)
end

def participant_permissions(role)
case role
when 'Student'
{ can_submit: true, can_review: false, can_take_quiz: false, can_mentor: false }
when 'Reviewer'
{ can_submit: false, can_review: true, can_take_quiz: false, can_mentor: false }
when 'Teaching Assistant'
{ can_submit: false, can_review: true, can_take_quiz: false, can_mentor: true }
when 'Mentor'
{ can_submit: false, can_review: false, can_take_quiz: false, can_mentor: true }
else
{ can_submit: false, can_review: false, can_take_quiz: false, can_mentor: false }
end
end

def set_participant
@participant = Participant.find(params[:id])
rescue ActiveRecord::RecordNotFound
render json: { error: "Participant not found" }, status: 404
end

def participant_params
params.require(:participant).permit(:user_id, :assignment_id)
end

# *****************************************************

def controller_locale
locale_for_student
end

# def list
# if Participant::PARTICIPANT_TYPES.include? params[:model]
# @root_node = Object.const_get(params[:model] + 'Node').find_by(node_object_id: params[:id])
# @parent = Object.const_get(params[:model]).find(params[:id])
# end
# begin
# @participants = @parent.participants
# @model = params[:model]
# @authorization = params[:authorization]
# rescue StandardError
# flash[:error] = $ERROR_INFO
# end
# end

# def add
# curr_object = Object.const_get(params[:model]).find(params[:id]) if Participant::PARTICIPANT_TYPES.include? params[:model]
# begin
# permissions = participant_permissions(params[:authorization])
# can_submit = permissions[:can_submit]
# can_review = permissions[:can_review]
# can_take_quiz = permissions[:can_take_quiz]
# #E2351 - add corresponding duty fill from permissions
# can_mentor = permissions[:can_mentor]
# if curr_object.is_a?(Assignment)
# curr_object.add_participant(params[:user][:name], can_submit, can_review, can_take_quiz, can_mentor)
# elsif curr_object.is_a?(Course)
# curr_object.add_participant(params[:user][:name])
# end
# user = User.find_by(name: params[:user][:name])
# @model = params[:model]
# @participant = curr_object.participants.find_by(user_id: user.id)
# flash.now[:note] = "The user #{params[:user][:name]} has successfully been added."
# rescue StandardError
# url_for controller: 'users', action: 'new'
# flash.now[:error] = "The user #{params[:user][:name]} does not exist or has already been added."
# end
# render action: 'add.js.erb', layout: false
# end

# when you change the duties, changes the permissions based on the new duty you go to
def update_authorizations
participant = Participant.find(params[:id])
permissions = participant_permissions(params[:authorization])
can_submit = permissions[:can_submit]
can_review = permissions[:can_review]
can_take_quiz = permissions[:can_take_quiz]
can_mentor = permissions[:can_mentor]
parent_id = participant.parent_id
# Upon successfully updating the attributes based on user role, a flash message is displayed to the user after the
# change in the database. This also gives the user the error message if the update fails.
begin
participant.update_attributes(can_submit: can_submit, can_review: can_review, can_take_quiz: can_take_quiz, can_mentor: can_mentor)
flash[:success] = 'The role of the selected participants has been successfully updated.'
rescue StandardError
flash[:error] = 'The update action failed.'
end
redirect_to action: 'list', id: parent_id, model: participant.class.to_s.gsub('Participant', '')
end

# def destroy
# participant = Participant.find(params[:id])
# parent_id = participant.parent_id
# begin
# participant.destroy
# flash[:note] = undo_link("The user \"#{participant.user.name}\" has been successfully removed as a participant.")
# rescue StandardError
# flash[:error] = 'This participant is on a team, or is assigned as a reviewer for someone’s work.'
# end
# redirect_to action: 'list', id: parent_id, model: participant.class.to_s.gsub('Participant', '')
# end

# Copies existing participants from a course down to an assignment
def inherit
assignment = Assignment.find(params[:id])
course = assignment.course
@copied_participants = []
if course
participants = course.participants
if !participants.empty?
participants.each do |participant|
new_participant = participant.copy(params[:id])
@copied_participants.push new_participant if new_participant
end
# Only display undo link if copies of participants are created
if !@copied_participants.empty?
undo_link("The participants from \"#{course.name}\" have been successfully copied to this assignment. ")
else
flash[:note] = 'All course participants are already in this assignment'
end
else
flash[:note] = 'No participants were found to inherit this assignment.'
end
else
flash[:error] = 'No course was found for this assignment.'
end
redirect_to controller: 'participants', action: 'list', id: assignment.id, model: 'Assignment'
end

# Take all participants from an assignment and "bequeath" them to course as course_participants.
def bequeath_all
@copied_participants = []
assignment = Assignment.find(params[:id])
if assignment.course
course = assignment.course
assignment.participants.each do |participant|
new_participant = participant.copy_to_course(course.id)
@copied_participants.push new_participant if new_participant
end
# only display undo link if copies of participants are created
if !@copied_participants.empty?
undo_link("All participants were successfully copied to \"#{course.name}\". ")
else
flash[:note] = 'All assignment participants are already part of the course'
end
else
flash[:error] = 'This assignment is not associated with a course.'
end
redirect_to controller: 'participants', action: 'list', id: assignment.id, model: 'Assignment'
end

# Allow participant to change handle for this assignment
# If the participant parameters are available, update the participant
# and redirect to the view_actions page
def change_handle
@participant = AssignmentParticipant.find(params[:id])
return unless current_user_id?(@participant.user_id)

unless params[:participant].nil?
if !AssignmentParticipant.where(parent_id: @participant.parent_id, handle: params[:participant][:handle]).empty?
ExpertizaLogger.error LoggerMessage.new(controller_name, @participant.name, "Handle #{params[:participant][:handle]} already in use", request)
flash[:error] = "The handle #{params[:participant][:handle]} is already in use for this assignment. Please select a different one."
redirect_to controller: 'participants', action: 'change_handle', id: @participant
else
@participant.update_attributes(participant_params)
ExpertizaLogger.info LoggerMessage.new(controller_name, @participant.name, 'The change handle is saved successfully', request)
redirect_to controller: 'student_task', action: 'view', id: @participant
end
end
end

# Deletes participants from an assignment
def delete
contributor = AssignmentParticipant.find(params[:id])
name = contributor.name
assignment_id = contributor.assignment
begin
contributor.destroy
flash[:note] = "\"#{name}\" is no longer a participant in this assignment."
rescue StandardError
flash[:error] = "\"#{name}\" was not removed from this assignment. Please ensure that \"#{name}\" is not a reviewer or metareviewer and try again."
end
redirect_to controller: 'review_mapping', action: 'list_mappings', id: assignment_id
end

# A ‘copyright grant’ means the author has given permission to the instructor to use the work outside the course.
# This is incompletely implemented, but the values in the last column in http://expertiza.ncsu.edu/student_task/list are sourced from here.
def view_copyright_grants
assignment_id = params[:id]
assignment = Assignment.find(assignment_id)
@assignment_name = assignment.name
@has_topics = false
@teams_info = []
teams = Team.where(parent_id: assignment_id)
teams.each do |team|
team_info = {}
team_info[:name] = team.name(session[:ip])
users = []
team.users { |team_user| users.append(get_user_info(team_user, assignment)) }
team_info[:users] = users
@has_topics = get_signup_topics_for_assignment(assignment_id, team_info, team.id)
team_without_topic = SignedUpTeam.where('team_id = ?', team.id).none?
next if @has_topics && team_without_topic

@teams_info.append(team_info)
end
@teams_info = @teams_info.sort_by { |hashmap| [hashmap[:topic_id] ? 0 : 1, hashmap[:topic_id] || 0] }
end

private

def participant_params
params.require(:participant).permit(:can_submit, :can_review, :user_id, :parent_id, :submitted_at,
:permission_granted, :penalty_accumulated, :grade, :type, :handle,
:time_stamp, :digital_signature, :can_mentor, :can_take_quiz)
end

# Get the user info from the team user
def get_user_info(team_user, assignment)
user = {}
user[:name] = team_user.name
user[:fullname] = team_user.fullname
# set by default
permission_granted = false
assignment.participants.each do |participant|
permission_granted = participant.permission_granted? if team_user.id == participant.user.id
end
# If permission is granted, set the publisting rights string
user[:pub_rights] = permission_granted ? 'Granted' : 'Denied'
user[:verified] = false
user
end

# Get the signup topics for the assignment
def get_signup_topics_for_assignment(assignment_id, team_info, team_id)
signup_topics = SignUpTopic.where('assignment_id = ?', assignment_id)
if signup_topics.any?
has_topics = true
signup_topics.each do |signup_topic|
signup_topic.signed_up_teams.each do |signed_up_team|
if signed_up_team.team_id == team_id
team_info[:topic_name] = signup_topic.topic_name
team_info[:topic_id] = signup_topic.topic_identifier.to_i
end
end
end
end
has_topics
end
end
# ***************************************************************************************************
# class Api::V1::ParticipantsController < ApplicationController
# before_action :set_participant, only: [:show, :update, :destroy, :update_authorization]

# def index
# participants = Participant.all
# render json: participants, status: :ok
# end

# def show
# render json: @participant, status: :ok
# end

# def create
# participant = Participant.new(participant_params)
# if participant.save
# render json: participant, status: :created
# else
# render json: { errors: participant.errors.full_messages }, status: :unprocessable_entity
# end
# end

# def update
# if @participant.update(participant_params)
# render json: @participant, status: :ok
# else
# render json: { errors: @participant.errors.full_messages }, status: :unprocessable_entity
# end
# end

# def destroy
# @participant.destroy
# render json: { message: "Participant deleted successfully" }, status: :no_content
# end

# def user_index
# participants = Participant.where(user_id: params[:user_id])
# render json: participants, status: :ok
# end

# def assignment_index
# participants = Participant.where(assignment_id: params[:assignment_id])
# render json: participants, status: :ok
# end

# def add
# user = User.find_by(name: params[:user][:name])
# if user.nil?
# render json: { error: "User not found" }, status: :not_found
# return
# end

# assignment = Assignment.find(params[:id])
# participant = assignment.participants.create(user: user)

# if participant.persisted?
# render json: participant, status: :created
# else
# render json: { errors: participant.errors.full_messages }, status: :unprocessable_entity
# end
# end

# def update_authorization
# permissions = participant_permissions(params[:authorization])
# if @participant.update(permissions)
# render json: @participant, status: :ok
# else
# render json: { errors: @participant.errors.full_messages }, status: :unprocessable_entity
# end
# end

# private

# def set_participant
# @participant = Participant.find_by(id: params[:id])
# render json: { error: "Participant not found" }, status: :not_found if @participant.nil?
# end

# def participant_params
# params.require(:participant).permit(:user_id, :assignment_id, :can_submit, :can_review, :can_take_quiz)
# end
# end

== Role-Based Strategy Pattern ==

As part of this reimplementation, a Strategy Design Pattern was introduced to streamline role-based permission handling, replacing the large conditional structure previously present in <code>participants_helper.rb</code>.

This pattern allows each role to encapsulate its own permission logic, enabling easier testing, extension, and adherence to SOLID principles.

=== Structure ===

The strategy pattern consists of the following components located under the <code>Strategies/roles</code> directory:

* <code>mentor_strategy.rb</code>
* <code>reviewer_strategy.rb</code>
* <code>student_strategy.rb</code>
* <code>teacher_assistant_strategy.rb</code>
* <code>role_strategy.rb</code> – Base module defining required methods
* <code>role_context.rb</code> – Context class that uses strategies dynamically

=== How it Works ===

Each role strategy implements the <code>get_permissions</code> method to return a role-specific permission hash, for example:

```ruby
# Example from MentorStrategy
<code>def get_permissions</code>
{
can_submit: false,
can_review: false,
can_take_quiz: false,
can_mentor: true
}
<code>end</code>

== Sample of the Swagger UI API working ==

APIs of all the participants_controller.rb
[[File:participants_API.png |center|600px]]

Updating a user by specific id
[[File:Updating_participant_ss1.png |center|600px]]

Request successful with User updated
[[File:Updating_participant_ss2.png |center|600px]]

== Resources ==
* [https://github.com/expertiza/expertiza Expertiza GitHub Repository]
* [https://guides.rubyonrails.org/routing.html Rails Routing Guide]
* [https://rswag.org rswag API Documentation Tool]

== Team Members ==
* Vansh Dodiya (vkdodiya)
* Brian Huynh (bhhuynh)
* Akhil Adusumilli (aadusum)

== Mentor ==
* Aniruddha Rajnekar

CSC/ECE 517 Spring 2025 - E2511. Reimplement participants controller.rb

2025-03-24T23:57:49Z

Vkdodiya: /* Method: add */

CSC/ECE 517 Spring 2025 - E2511. Reimplement participants controller.rb

2025-03-24T23:57:25Z

Vkdodiya: /* participants_controller.rb Methods */

CSC/ECE 517 Spring 2025 - E2511. Reimplement participants controller.rb

2025-03-24T23:56:06Z

Vkdodiya:

CSC/ECE 517 Spring 2025 - E2511. Reimplement participants controller.rb

2025-03-24T23:52:24Z

Vkdodiya: /* Sample of the Swagger UI API working */

CSC/ECE 517 Spring 2025 - E2511. Reimplement participants controller.rb

2025-03-24T23:51:26Z

Vkdodiya: /* Sample of the Swagger UI API working */