When accessing the Course Content Structure, Exams are identified as content items (of type "IQT"). When accessed via the LearningStudio User Interface (UI), LearningStudio renders the exam introduction as it would any other piece of content. However, in this case the content item can be thought of as a shell for an exam template.
An exam template is made up of the question pools, the exam structure (sections), and the exam settings such as duration, whether it can retaken, etc. Note that this template is global for the course, but when a student comes to take an exam, they are created their own exam instance.
An exam instance takes the template and applies it to the specific student taking the exam. If the exam is configured to pull questions from a question pool and/or randomize the questions, the instance provided to the student contains only the questions they are expected to answer (which may differ from other classmates').
Using the APIs, you will provision an exam instance for the student as the first step to their taking the exam. Only one instance can be provisioned via the APIs at a time. If the student wishes to or needs to reset the exam (meaning, get a new set of questions), that can be done by their professor in the LearningStudio UI. After that point, a new instance may be provisioned.
Once the student is ready to begin the exam (and start the clock, as it were, if the exam is timed), you use the APIs to create an "attempt." Behind the scenes, an attempt is like a temporary database tables where the students answers are stored while taking the exam. (Think of it like an answer booklet the student fills in at their desk.) As you submit the student's answers to the attempt, they are stored in this temporary location.
Once the student is done with their attempt, you will use the APIs to mark the attempt as complete. At that point, the answers are pushed from the temporary "attempt" location back into the official Exams system. (This is like the student turning in their answer booklet.) If the test is auto-graded, the grade will be calculated at this point. If the student wishes to retake the exam, and retakes are allowed by the exam's settings, you can create a new attempt for the student. The new attempt will use the same questions from the exam instance you provisioned at the outset.
Note: Only one attempt can be exist at a time. If the exam permits retakes, a new attempt may be created after the previous one is completed. But new attempts will erase the answers submitted from previous attempts.
Note: If the exam is timed, answers must be submitted before the time runs out even if the student is not done. Once the attempt is expired it won't accept additional answers (though you can still mark it as complete to submit the answers that are completed).
Resetting an Exam
An exam reset is defined as when a user's exam instance is deleted, which also deletes any related attempts instance (user's saved answers). In this case, the entire exam history is deleted for that user. If the user takes the exam again, the process would be the same as when the user took the exam for the first time.
Only professors or other course administrator roles can reset an exam for a user. Resets can be done via the LearningStudio User Interface or via an
DELETE request. See How to Reset an Exam
Retaking an Exam
An exam retake is defined as when the exam instance is preserved for a user, but the user's attempts instance is replaced with a new attempts instance. In this case, the original set of the exam's questions preserved and reused during the next attempt. Exams can only be retaken if the exam's settings allow for retaking the exam. See How to Retake an Exam
An exam retake cannot be performed if there is a previous attempts instance that is still open/active for that exam ID and user ID. The previous attempts instance must be marked as complete before a new attempt can be created. If the creation is attempted with the exam ID/user ID combination that has an open attempts instance, an error code of
403 - Forbidden is returned.