New/feedback enhancement

app/api/api_root.rb

@@ -56,6 +56,9 @@ class ApiRoot < Grape::API
   mount DiscussionCommentApi
   mount ExtensionCommentsApi
   mount FeedbackApi::StageApi
+  mount FeedbackApi::FeedbackCommentTemplateApi
+  mount FeedbackApi::CriterionApi
+  mount FeedbackApi::CriterionOptionApi
   mount GroupSetsApi
   mount LearningOutcomesApi
   mount LearningAlignmentApi
@@ -103,6 +106,9 @@ class ApiRoot < Grape::API
   AuthenticationHelpers.add_auth_to ProjectsApi
   AuthenticationHelpers.add_auth_to StudentsApi
   AuthenticationHelpers.add_auth_to FeedbackApi::StageApi
+  AuthenticationHelpers.add_auth_to FeedbackApi::FeedbackCommentTemplateApi
+  AuthenticationHelpers.add_auth_to FeedbackApi::CriterionApi
+  AuthenticationHelpers.add_auth_to FeedbackApi::CriterionOptionApi
   AuthenticationHelpers.add_auth_to Submission::PortfolioApi
   AuthenticationHelpers.add_auth_to Submission::PortfolioEvidenceApi
   AuthenticationHelpers.add_auth_to Submission::BatchTaskApi

app/api/entities/feedback_entities/criterion_entity.rb

@@ -1,9 +1,10 @@
 module Entities
-  # entities present the data in a specific format to the user
-  class CriterionEntity < Grape::Entity
-    expose :id
-    expose :help_text
-    expose :description
-    expose :order
+  module FeedbackEntities
+    class CriterionEntity < Grape::Entity
+      expose :id
+      expose :order
+      expose :description
+      expose :help_text
+    end
   end
 end

app/api/entities/feedback_entities/criterion_option_entity.rb

@@ -1,8 +1,11 @@
 module Entities
-  class CriterionOptionEntity < Grape::Entity
-    expose :id
-    expose :task_status_id # TODO: ... check this?
-    expose :resolved_message_text
-    expose :unresolved_message_text
+  module FeedbackEntities
+    class CriterionOptionEntity < Grape::Entity
+      expose :id
+      expose :task_status_id
+      expose :outcome_status
+      expose :resolved_message_text
+      expose :unresolved_message_text
+    end
   end
 end

app/api/entities/feedback_entities/feedback_comment_entity.rb

@@ -1,6 +1,8 @@
 module Entities
-  class FeedbackCommentEntity < Grape::Entity
-    expose :id
-    expose :comment
+  module FeedbackEntities
+    class FeedbackCommentEntity < Grape::Entity
+      expose :id
+      expose :comment
+    end
   end
 end

app/api/entities/feedback_entities/feedback_comment_template_entity.rb

@@ -1,7 +1,9 @@
 module Entities
-  class FeedbackCommentTemplateEntity < Grape::Entity
-    expose :id
-    expose :comment_text_situation
-    expose :comment_text_next_action
+  module FeedbackEntities
+    class FeedbackCommentTemplateEntity < Grape::Entity
+      expose :id
+      expose :comment_text_situation
+      expose :comment_text_next_action
+    end
   end
 end

app/api/entities/feedback_entities/stage_entity.rb

@@ -1,10 +1,12 @@
 module Entities
-  class StageEntity < Grape::Entity
-    expose :id
-    expose :title # expose method: returns title of stage from stage.rb
-    expose :order
-    expose :entry_message
-    expose :exit_message_good
-    expose :exit_message_resubmit
+  module FeedbackEntities
+    class StageEntity < Grape::Entity
+      expose :id
+      expose :title
+      expose :order
+      expose :entry_message
+      expose :exit_message_good
+      expose :exit_message_resubmit
+    end
   end
 end

app/api/feedback_api/criterion_api.rb

@@ -0,0 +1,75 @@
+require 'grape'
+
+module FeedbackApi
+  class CriterionApi < Grape::API
+    desc 'Stages are completed through criteria. This endpoint allows you to create a new criterion for a given stage.'
+    params do
+      requires :stage_id, type: Integer, desc: 'The stage to which the criterion belongs'
+      requires :description, type: String,  desc: 'The description of the new criterion'
+      requires :order, type: Integer, desc: 'The order in which to display the criteria'
+      optional :help_text, type: String, desc: 'The context that a tutor may need to make sense of the criterion'
+    end
+    post '/criteria' do # POST to /api/feedback/criteria endpoint
+      stage = Stage.find(params[:stage_id])
+
+      unless authorise? current_user, stage.unit, :update
+        error!({ error: 'Not authorised to create a criterion for this unit' }, 403)
+      end
+
+      criterion_parameters = ActionController::Parameters.new(params)
+                                                         .permit(:description, :order) # "permit" method: only allow these parameters to be passed
+
+      criterion_parameters[:stage] = stage # "criterion_parameters" hash: add the stage to the hash
+
+      result = Criterion.create!(criterion_parameters) # "result" variable: create a new criterion with the parameters
+
+      present result, with: Entities::FeedbackEntities::CriterionEntity # "present" method: present the result with the "CriterionEntity" entity (defined in "doubtfire-api/app/api/entities/feedback_entities/criterion_entity.rb")
+    end
+
+    desc 'This endpoint allows you to get all the criteria for a given stage.'
+    params do
+      requires :stage_id, type: Integer, desc: 'The stage to which the criterion belongs'
+    end
+    get '/criteria' do
+      stage = Stage.find(params[:stage_id])
+
+      unless authorise? current_user, stage.unit, :provide_feedback
+        error!({ error: 'Not authorised to get feedback criteria for this unit' }, 403)
+      end
+
+      present stage.criteria, with: Entities::FeedbackEntities::CriterionEntity
+    end
+
+    desc 'This endpoint allows you to update the description and order of a criterion.'
+    params do
+      optional :description, type: String, desc: 'The new description for the criterion'
+      optional :order, type: Integer, desc: 'The new order value for the criterion'
+    end
+    put '/criteria/:id' do
+      # Get the criterion from the stage
+      criterion = Criterion.find(params[:id])
+
+      unless authorise? current_user, criterion.unit, :update
+        error!({ error: 'Not authorised to update feedback criteria for this unit' }, 403)
+      end
+
+      criterion_params = ActionController::Parameters.new(params)
+                                                     .permit(:description, :order)
+
+      criterion.update!(criterion_params)
+
+      present criterion, with: Entities::FeedbackEntities::CriterionEntity
+    end
+
+    desc 'This endpoint allows you to delete a criterion.'
+    delete '/criteria/:id' do
+      criterion = Criterion.find(params[:id])
+
+      unless authorise? current_user, criterion.unit, :update
+        error!({ error: 'Not authorised to delete feedback criteria for this unit' }, 403)
+      end
+
+      criterion.destroy!
+    end
+  end
+end

app/api/feedback_api/criterion_option_api.rb

@@ -0,0 +1,77 @@
+require 'grape'
+
+module FeedbackApi
+  class CriterionOptionApi < Grape::API
+    desc 'Criteria have criterion options. This endpoint allows you to create a new criterion option for a given criterion.'
+    params do
+      requires :criterion_id, type: Integer, desc: 'The criterion to which the criterion option belongs'
+      optional :outcome_status, type: String, desc: 'The outcome status for the student when this criterion option is true; e.g., "Fix and Rebsubmit", "Complete", etc'
+      optional :unresolved_message_text, type: String, desc: 'text that the tutor returns to the student who has not resolved the issue on resubmit'
+      optional :resolved_message_text, type: String, desc: 'text that the tutor returns to the student who has resolved the issue on resubmit'
+    end
+    post '/criterion_options' do
+      criterion = Criterion.find(params[:criterion_id])
+
+      unless authorise? current_user, criterion.stage.task_definition.unit, :update
+        error!({ error: 'Not authorised to create a criterion option for this unit' }, 403)
+      end
+
+      criterion_option_parameters = ActionController::Parameters.new(params)
+                                                                .permit(:outcome_status, :unresolved_message_text, :resolved_message_text)
+
+      criterion_option_parameters[:criterion] = criterion
+
+      result = CriterionOption.create!(criterion_option_parameters)
+
+      present result, with: Entities::FeedbackEntities::CriterionOptionEntity
+    end
+
+    desc 'This endpoint allows you to get all the criterion options for a given criterion.'
+    params do
+      requires :criterion_id, type: Integer, desc: 'The criterion to which the criterion option belongs'
+    end
+    get '/criterion_options' do
+      criterion = Criterion.find(params[:criterion_id])
+
+      unless authorise? current_user, criterion.unit, :provide_feedback
+        error!({ error: 'Not authorised to get feedback criterion options for this unit' }, 403)
+      end
+
+      present criterion.criterion_options, with: Entities::FeedbackEntities::CriterionOptionEntity
+    end
+
+    desc 'This endpoint allows you to update the outcome status, unresolved message text and resolved message text of a criterion option.'
+    params do
+      optional :outcome_status, type: String, desc: 'The new outcome status for the criterion option'
+      optional :unresolved_message_text, type: String, desc: 'The new unresolved message text for the criterion option'
+      optional :resolved_message_text, type: String, desc: 'The new resolved message text for the criterion option'
+    end
+    put '/criterion_options/:id' do
+      criterion_option = CriterionOption.find(params[:id])
+
+      unless authorise? current_user, criterion_option.unit, :update
+        error!({ error: 'Not authorised to update feedback criterion options for this unit' }, 403)
+      end
+
+      criterion_option_params = ActionController::Parameters.new(params)
+                                                            .permit(:outcome_status, :unresolved_message_text, :resolved_message_text)
+
+      criterion_option.update!(criterion_option_params)
+
+      present criterion_option, with: Entities::FeedbackEntities::CriterionOptionEntity
+    end
+
+    desc 'This endpoint allows you to delete a criterion option.'
+    delete '/criterion_options/:id' do
+      criterion_option = CriterionOption.find(params[:id])
+
+      unless authorise? current_user, criterion_option.unit, :update
+        error!({ error: 'Not authorised to delete feedback criterion options for this unit' }, 403)
+      end
+
+      criterion_option.destroy!
+
+      present criterion_option, with: Entities::FeedbackEntities::CriterionOptionEntity
+    end
+  end
+end

app/api/feedback_api/feedback_comment_api.rb

@@ -0,0 +1 @@
+

app/api/feedback_api/feedback_comment_template_api.rb

@@ -0,0 +1,74 @@
+require 'grape'
+
+module FeedbackApi
+  class FeedbackCommentTemplateApi < Grape::API
+    desc 'Feedback comment templates are used to provide a list of comments that can be used to provide feedback on a task. This endpoint allows you to create a new feedback comment template.'
+    params do
+      requires :comment_text_situation, type: String, desc: 'What the comment is about. Could be what is wrong with or what is good about a student\'s submission.'
+      requires :comment_text_next_action, type: String, desc: 'What the student should do next to improve their submission'
+      optional :criterion_option_id, type: Integer, desc: 'The criterion option to which the comment template is associated'
+    end
+    post '/feedback_comment_templates' do # pathname of URL
+      criterion_option = CriterionOption.find(params[:criterion_option_id])
+
+      unless authorise? current_user, criterion_option.unit, :update
+        error!({ error: 'Not authorised to create a feedback comment template for this unit' }, 403)
+      end
+
+      feedback_comment_template_parameters = ActionController::Parameters.new(params)
+                                                                         .permit(:comment_text_situation, :comment_text_next_action)
+
+      feedback_comment_template_parameters[:criterion_option] = criterion_option
+
+      result = FeedbackCommentTemplate.create!(feedback_comment_template_parameters)
+
+      present result, with: Entities::FeedbackEntities::FeedbackCommentTemplateEntity
+      # presents JSON format of the newly posted FeedbackCommentTemplate object from the FeedbackCommentTemplateEntity
+    end
+
+    desc 'This endpoint allows you to get all the feedback comment templates for a given criterion_option.'
+    params do
+      requires :criterion_option_id, type: Integer, desc: 'The criterion option to which the comment template belongs'
+    end
+    get '/feedback_comment_templates' do
+      criterion_option = CriterionOption.find(params[:criterion_option_id])
+
+      unless authorise? current_user, criterion_option.unit, :read
+        error!({ error: 'Not authorised to read feedback comment templates for this unit' }, 403)
+      end
+
+      present stage.feedback_comment_templates, with: Entities::FeedbackEntities::FeedbackCommentTemplateEntity
+    end
+
+    desc 'This endpoint allows you to update the comment text situation or comment text next action for a feedback comment template.'
+    params do
+      optional :comment_text_situation, type: String, desc: 'The new comment text situation for the feedback comment template'
+      optional :comment_text_next_action, type: String, desc: 'The new comment text next action for the feedback comment template'
+    end
+    put '/feedback_comment_templates/:id' do
+      feedback_comment_template = FeedbackCommentTemplate.find(params[:id])
+
+      unless authorise? current_user, feedback_comment_template.unit, :update
+        error!({ error: 'Not authorised to update feedback comment templates for this unit' }, 403)
+      end
+
+      feedback_comment_template_parameters = ActionController::Parameters.new(params)
+                                                                         .permit(:comment_text_situation, :comment_text_next_action)
+
+      feedback_comment_template.update!(feedback_comment_template_parameters)
+
+      present feedback_comment_template, with: Entities::FeedbackEntities::FeedbackCommentTemplateEntity
+    end
+
+    desc 'This endpoint allows you to delete a feedback comment template.'
+    delete '/feedback_comment_templates/:id' do
+      feedback_comment_template = FeedbackCommentTemplate.find(params[:id])
+
+      unless authorise? current_user, feedback_comment_template.unit, :update
+        error!({ error: 'Not authorised to delete feedback comment templates for this unit' }, 403)
+      end
+
+      feedback_comment_template.destroy!
+    end
+  end
+end

app/api/feedback_api/stage_api.rb

@@ -6,7 +6,10 @@ class StageApi < Grape::API
     params do
       requires :task_definition_id, type: Integer, desc: 'The task definition to which the stage belongs'
       requires :title, type: String,  desc: 'The title of the new stage'
-      requires :order, type: Integer, desc: 'The order to determine the order in which to display stages'
+      requires :order, type: Integer, desc: 'The order in which to display the stages'
+      optional :entry_message, type: String, desc: 'The message to display to students when they enter the stage'
+      optional :exit_message_good, type: String, desc: 'The message to display to students who have achieved a passable level of work'
+      optional :exit_message_resubmit, type: String, desc: 'The message to display to students who have not achieved a passable level of work'
     end
     post '/stages' do
       task_definition = TaskDefinition.find(params[:task_definition_id])
@@ -16,13 +19,13 @@ class StageApi < Grape::API
       end
 
       stage_parameters = ActionController::Parameters.new(params)
-        .permit(:title, :order)
+                                                     .permit(:title, :order) # only `:title` and `:order` fields of the Stage model can be set directly from the user input.
 
       stage_parameters[:task_definition] = task_definition
 
       result = Stage.create!(stage_parameters)
 
-      present result, with: Entities::StageEntity
+      present result, with: Entities::FeedbackEntities::StageEntity
     end
 
     desc 'This endpoint allows you to get all the stages for a given task definition.'
@@ -36,7 +39,7 @@ class StageApi < Grape::API
         error!({ error: 'Not authorised to get feedback stages for this unit' }, 403)
       end
 
-      present task_definition.stages, with: Entities::StageEntity
+      present task_definition.stages, with: Entities::FeedbackEntities::StageEntity
     end
 
     desc 'This endpoint allows you to update the name and order of a stage.'
@@ -53,11 +56,11 @@ class StageApi < Grape::API
       end
 
       stage_params = ActionController::Parameters.new(params)
-        .permit(:title, :order)
+                                                 .permit(:title, :order)
 
       stage.update!(stage_params)
 
-      present stage, with: Entities::StageEntity
+      present stage, with: Entities::FeedbackEntities::StageEntity
     end
 
     desc 'This endpoint allows you to delete a stage.'

app/models/feedback/criterion_option.rb

@@ -2,7 +2,7 @@ class CriterionOption < ApplicationRecord
   # Associations
   belongs_to :criterion
   belongs_to :task_status
-  has_many :feedback_comment_templates
+  # has_and_belongs_to_many :feedback_comment_template
   has_many :feedback_comments
 
   # Constraints