Quiz Submissions API - Create & Complete

Allows users to start a "quiz-taking session" via the API by creating
a QuizSubmission and later on completing it.

Note that this patch isn't concerned with actually using the QS to
answer questions. That task will be the concern of a new API controller,
QuizSubmissionQuestions.

closes CNVS-8980

TEST PLAN
---- ----

- Create a quiz
- Keep a tab open on the Moderate Quiz (MQ from now) page

Create the quiz submission (ie, start a quiz-taking session):

- Via the API, as a student:
  - POST to /courses/:course_id/quizzes/:quiz_id/submissions
    - Verify that you receive a 200 response with the newly created
      QuizSubmission in the JSON response.
    - Copy the "validation_token" field down, you will need this later
    - Go to the MQ tab and verify that it says the student has started a
      quiz attempt

Complete the quiz submission (ie, finish a quiz-taking session):

- Via the API, as a student, prepare a request with:
  - Method: POST
  - URI: /courses/:course_id/quizzes/:quiz_id/submissions/:id/complete
  - Parameter "validation_token" to what you copied earlier
  - Parameter "attempt" to the current attempt number (starts at 1)
  - Now perform the request, and:
    - Verify that you receive a 200 response
    - Go to the MQ tab and verify that it says the submission has been
      completed (ie, Time column reads "finished in X seconds/minutes")

Other stuff to test (failure scenarios):

The first endpoint (one for starting a quiz attempt) should reject your
request in any of the following cases:

  - The quiz has been locked
  - You are not enrolled in the quiz course
  - The Quiz has an Access Code that you either didn't pass, or passed
    incorrectly
  - The Quiz has an IP filter and you're not in the address range
  - You are already taking the quiz (you've created the submission and
    did not call /complete yet)
  - You are not currently taking the quiz, but you already took it
    earlier and the Quiz does not allow for multiple attempts

The second endpoint (one for completing the quiz attempt) should reject
your request in any of the following cases:

  - You pass in an invalid "validation_token"
  - You already completed that quiz submission (e.g, you called that
    endpoint earlier)

Change-Id: Iff8a47859d7477c210de46ea034544d5e2527fb2
Reviewed-on: https://gerrit.instructure.com/27015
Reviewed-by: Derek DeVries <ddevries@instructure.com>
Tested-by: Jenkins <jenkins@instructure.com>
QA-Review: Myller de Araujo <myller@instructure.com>
Product-Review: Ahmad Amireh <ahmad@instructure.com>

Author: amireh

app/controllers/quiz_submissions_api_controller.rb

@@ -127,9 +127,12 @@
 class QuizSubmissionsApiController < ApplicationController
   include Api::V1::QuizSubmission
   include Api::V1::Helpers::QuizzesApiHelper
+  include Api::V1::Helpers::QuizSubmissionsApiHelper
 
   before_filter :require_user, :require_context, :require_quiz
-  before_filter :require_quiz_submission, :only => [ :show ]
+  before_filter :require_overridden_quiz, :except => [ :index ]
+  before_filter :require_quiz_submission, :except => [ :index, :create ]
+  before_filter :prepare_service, :only => [ :create, :complete ]
 
   # @API Get all quiz submissions.
   # @beta
@@ -175,25 +178,110 @@ def index
   #  }
   def show
     if authorized_action(@quiz_submission, @current_user, :read)
-      render :json => quiz_submissions_json([ @quiz_submission ],
-        @quiz,
-        @current_user,
-        session,
-        @context,
-        Array(params[:include]))
+      render_quiz_submission(@quiz_submission)
     end
   end
 
+  # @API Create the quiz submission (start a quiz-taking session)
+  # @beta
+  #
+  # Start taking a Quiz by creating a QuizSubmission which you can use to answer
+  # questions and submit your answers.
+  #
+  # @argument validation_token [String]
+  #   The unique validation token you received when this Quiz Submission was
+  #   created.
+  #
+  # @argument access_code [Optional, String]
+  #   Access code for the Quiz, if any.
+  #
+  # @argument preview [Optional, Boolean]
+  #   Whether this should be a preview QuizSubmission and not count towards
+  #   the user's course record. Teachers only.
+  #
+  # <b>Responses</b>
+  #
+  # * <b>200 OK</b> if the request was successful
+  # * <b>400 Bad Request</b> if the quiz is locked
+  # * <b>403 Forbidden</b> if an invalid access code is specified
+  # * <b>403 Forbidden</b> if the Quiz's IP filter restriction does not pass
+  # * <b>409 Conflict</b> if a QuizSubmission already exists for this user and quiz
+  #
+  # @example_response
+  #  {
+  #    "quiz_submissions": [QuizSubmission]
+  #  }
+  def create
+    quiz_submission = if previewing?
+      @service.create_preview(@quiz, session)
+    else
+      @service.create(@quiz)
+    end
+
+    log_asset_access(@quiz, 'quizzes', 'quizzes', 'participate')
+
+    render_quiz_submission(quiz_submission)
+  end
+
+  def update
+  end
+
+  # @API Complete the quiz submission (turn it in).
+  # @beta
+  #
+  # Complete the quiz submission by marking it as complete and grading it. When
+  # the quiz submission has been marked as complete, no further modifications
+  # will be allowed.
+  #
+  # @argument attempt [Integer]
+  #   The attempt number of the quiz submission that should be completed. Note
+  #   that this must be the latest attempt index, as earlier attempts can not
+  #   be modified.
+  #
+  # @argument validation_token [String]
+  #   The unique validation token you received when this Quiz Submission was
+  #   created.
+  #
+  # @argument access_code [Optional, String]
+  #   Access code for the Quiz, if any.
+  #
+  # <b>Responses</b>
+  #
+  # * <b>200 OK</b> if the request was successful
+  # * <b>403 Forbidden</b> if an invalid access code is specified
+  # * <b>403 Forbidden</b> if the Quiz's IP filter restriction does not pass
+  # * <b>403 Forbidden</b> if an invalid token is specified
+  # * <b>400 Bad Request</b> if the QS is already complete
+  # * <b>400 Bad Request</b> if the attempt parameter is missing
+  # * <b>400 Bad Request</b> if the attempt parameter is not the latest attempt
+  #
+  # @example_response
+  #  {
+  #    "quiz_submissions": [QuizSubmission]
+  #  }
+  def complete
+    @service.complete @quiz_submission, params[:attempt]
+
+    render_quiz_submission(@quiz_submission)
+  end
+
   private
 
-  def require_quiz_submission
-    unless @quiz_submission = @quiz.quiz_submissions.find(params[:id])
-      raise ActiveRecord::RecordNotFound
-    end
+  def previewing?
+    !!params[:preview]
   end
 
   def visible_user_ids(opts = {})
     scope = @context.enrollments_visible_to(@current_user, opts)
     scope.pluck(:user_id)
   end
+
+  def render_quiz_submission(qs)
+    render :json => quiz_submissions_json([ qs ],
+      @quiz,
+      @current_user,
+      session,
+      @context,
+      Array(params[:include]))
+  end
 end

app/models/quiz.rb

@@ -650,6 +650,16 @@ def generate_submission(user, preview=false)
     submission
   end
 
+  def generate_submission_for_participant(quiz_participant)
+    identity = if quiz_participant.anonymous?
+      :user_code
+    else
+      :user
+    end
+
+    generate_submission quiz_participant.send(identity), false
+  end
+
   def prepare_answers(question)
     if answers = question[:answers]
       if shuffle_answers && Quiz.shuffleable_question_type?(question[:question_type])

app/models/quiz_participant.rb

@@ -0,0 +1,62 @@
+class QuizParticipant
+  attr_accessor :user, :user_code, :access_code, :ip_address, :validation_token
+
+  # An identity for a quiz participant, which can be an enrolled student,
+  # an anonymous user, or a teacher.
+  #
+  # @param [User] user
+  #   The person who wants to take the quiz.
+  #
+  # @param [String] user_code
+  #   A unique code to use for identifying the participant in case the user is
+  #   missing or is irrelevant (the case for preview mode). This code is usually
+  #   found in the Rails session. See ApplicationController#temporary_user_code
+  #   for more info.
+  #
+  # @param [String] access_code
+  #   Access code required to take the quiz (if any.)
+  #
+  # @param [String] ip_address
+  #   The IP address of the client's device that initiated the request.
+  #
+  # @param [String] token
+  #   Validation token for the participant's existing quiz submission.
+  #
+  # @return [QuizParticipant]
+  #   Participant instance ready for use by Quiz Services.
+  def initialize(user, user_code, access_code=nil, ip_address=nil, token=nil)
+    self.user = user
+    self.user_code = user_code
+    self.access_code = access_code
+    self.ip_address = ip_address
+    self.validation_token = token
+
+    super()
+  end
+
+  # Locate the Quiz Submission for this participant, regardless of them being
+  # enrolled students, or anonymous participants.
+  #
+  # @param [ActiveRecord::Association]
+  #   The pool of QuizSubmission instances to look in, defaults to all.
+  #
+  # @param [Hash] query_options
+  #   Options to pass to the AR query interface.
+  #
+  # @return [QuizSubmission]
+  #   The QS, if any, for the participant.
+  def find_quiz_submission(scope = QuizSubmission, query_options = {})
+    self.anonymous? ?
+      scope.find_by_temporary_user_code(self.user_code, query_options) :
+      scope.find_by_user_id(self.user.id, query_options)
+  end
+
+  # Is this a Canvas user (enrolled student, teacher, TA, etc.) or an anonymous
+  # person?
+  #
+  # Note that this does not actually take the Quiz's public-participation status
+  # into account, only the fact that the participant is authentic or not.
+  def anonymous?
+    self.user.nil? && self.user_code.present?
+  end
+end

app/models/quiz_submission.rb

@@ -294,8 +294,35 @@ def sanitize_params(params)
     params
   end
 
-  def snapshot!(params)
-    QuizSubmissionSnapshot.create(:quiz_submission => self, :attempt => self.attempt, :data => params)
+  # Generate a snapshot of the QS representing its current state and answer data.
+  #
+  # Multiple snapshots can be taken for a single QS, and they're further scoped
+  # to the QuizSubmission#attempt index.
+  #
+  # @param [Hash] submission_data
+  #   Answer data the snapshot should represent.
+  #
+  # @param [Boolean] full_snapshot
+  #   Set to true to indicate that the snapshot should represent both the QS's
+  #   current answer data along with the passed in answer data (patched).
+  #   This is useful for supporting incremental snapshots where you're only
+  #   passing in the part of the answer data that has changed.
+  #
+  # @return [QuizSubmissionSnapshot]
+  #   The latest, newly-created snapshot.
+  def snapshot!(submission_data={}, full_snapshot=false)
+    snapshot_data = submission_data || {}
+
+    if full_snapshot
+      snapshot_data = self.sanitize_params(snapshot_data).stringify_keys
+      snapshot_data.merge!(self.submission_data || {})
+    end
+
+    QuizSubmissionSnapshot.create({
+      quiz_submission: self,
+      attempt: self.attempt,
+      data: snapshot_data
+    })
   end
 
   def questions_as_object
@@ -533,6 +560,24 @@ def grade_submission(opts={})
     QuizRegrader.regrade!(options)
   end
 
+  # Complete (e.g, turn-in) the quiz submission by doing the following:
+  #
+  #  - generating a (full) snapshot of the current state along with any
+  #  additional answer data that you pass in
+  #  - marking the QS as complete (see #workflow_state)
+  #  - grading the QS (see #grade_submission)
+  #
+  # @param [Hash] submission_data
+  #   Additional answer data to attach to the QS before completing it.
+  #
+  # @return [QuizSubmission] self
+  def complete!(submission_data={})
+    self.snapshot!(submission_data, true)
+    self.mark_completed
+    self.grade_submission
+    self
+  end
+
   # Updates a simply_versioned version instance in-place.  We want
   # a teacher to be able to come in and update points for an already-
   # taken quiz, even if it's a prior version of the submission. Thank you
@@ -781,4 +826,24 @@ def grade_if_untaken
   delegate :assignment_id, :assignment, :to => :quiz
   delegate :graded_at, :to => :submission
   delegate :context, :to => :quiz
+
+  # Determine whether the QS can be retried (ie, re-generated).
+  #
+  # A QS is determined to be retriable if:
+  #
+  #   - it's a settings_only? one
+  #   - it's a preview? one
+  #   - it's complete and still has attempts left to spare
+  #   - it's complete and the quiz allows for unlimited attempts
+  #
+  # @return [Boolean]
+  #   Whether the QS is retriable.
+  def retriable?
+    return true if self.preview?
+    return true if self.settings_only?
+
+    attempts_left = self.attempts_left || 0
+
+    self.completed? && (attempts_left > 0 || self.quiz.unlimited_attempts?)
+  end
 end