Pearson
Always Learning

API Group: 

Overview

This gudie describes the API sequence for a user retaking an exam after completing it at least once. The exam must be retakable in order for this to work.

  • If the user is taking an exam for the first time or the entire exam has been reset, see the Begin and Take a New Exam How To Guide.

During an exam retake, the original question set (the exam instance) is preserved; thus, the original set of questions/choices will be re-presented during the exam retake. The previous attempts instance is replaced with a new attempts instance with no saved answers. Any answers that had been saved in the previous attempts are deleted.

Note: The following use case supports retrieving the entire set of questions for the exam before the user answers any questions. This scenario supports presenting multiple questions on a UI single page. Optionally, a single question can be retrieved and its answer can be saved before the next question is retrieved. Just be sure to repeat this process for each question in a section and each section in the exam.

Important: An exam cannot be started using the LearningStudio user interface and then modified or completed using the Exam API. If the exam is started using the LearningStudio UI, it must be completed using the UI.

The following sequence maps the parallel processes between the typical actions of a user retaking an exam and the Exam Resources performing the processing. Click the resource link to open its detailed description.


User Interface API Notes
User opens exam. 1. (Optional) Get the system time from the LearningStudio server to coordinate durations.

GET /systemDateTime

 

2. Get the array of exam IDs associated with the user (the user's exam instance IDs) from course items. If the specific exam ID is known, skip this step.

GET /users/{userId}/courses/{courseId}/exams

Retaking an exam is allowed only between the scheduled start and end date/times of exam.
User starts exam retake. 3. Create attempts instance where user answers are stored.

POST /users/{userId}/courses/{courseId}/exams/{examId}/attempts

 

  • Do create attempts instance only once per user ID per exam ID. If a POST is reattempted with an attempts instance whose isCompleted attribute is still set to False, an error code is returned.
  • Response body includes attempt ID and pearsonExamToken.
  • The Pearson-Exam-Token token must be included in the request header in further transactions for the attempts instance.
  • The Pearson-Exam-Token token is unique to each attempt. The Pearson-Exam-Token token that was created for the previous attempts instance is invalid for the exam retake.
  • Exam duration begins on the LearningStudio server ("clock starts").
4. Get exam structure.

 

  a. Get array of sections within exam.

GET /users/{userId}/courses/{courseId}/exams/{examId}/sections

 

  b. Get array of questions for each section. Repeat for each section in exam.

GET /users/{userId}/courses/{courseId}/exams/{examId}/sections/{sectionId}/questions

Optionally, the question count, question types, and total number of possible points can be displayed to the user.
5. Get exam contents (data and choices for each question type). Repeat for each question of the same type within each section.

 

  a. Get True/False question and array of choices.

GET /users/{userId}/courses/{courseId}/exams/{examId}/sections/{sectionId}/trueFalseQuestions/{questionId}

 

GET /users/{userId}/courses/{courseId}/exams/{examId}/sections/{sectionId}/trueFalseQuestions/{questionId}/choices

 

  b. Get Multiple-Choice question and array of choices.

GET /users/{userId}/courses/{courseId}/exams/{examId}/sections/{sectionId}/multipleChoiceQuestions/{questionId}

 

GET /users/{userId}/courses/{courseId}/exams/{examId}/sections/{sectionId}/multipleChoiceQuestions/{questionId}/choices

 

  c. Get Many Multiple-Choice question and array of choices.

GET /users/{userId}/courses/{courseId}/exams/{examId}/sections/{sectionId}/manyMultipleChoiceQuestions/{questionId}

 

GET /users/{userId}/courses/{courseId}/exams/{examId}/sections/{sectionId}/manyMultipleChoiceQuestions/{questionId}/choices

 

  d. Get Matching question, array of premises, and array of choices.

GET /users/{userId}/courses/{courseId}/exams/{examId}/sections/{sectionId}/matchingQuestions/{questionId}

 

GET /users/{userId}/courses/{courseId}/exams/{examId}/sections/{sectionId}/matchingQuestions/{questionId}/premises

 

GET /users/{userId}/courses/{courseId}/exams/{examId}/sections/{sectionId}/matchingQuestions/{questionId}/choices

 

  e. Get Short Answer question.

GET /users/{userId}/courses/{courseId}/exams/{examId}/sections/{sectionId}/shortQuestions/{questionId}

 

  f. Get Essay question.

GET /users/{userId}/courses/{courseId}/exams/{examId}/sections/{sectionId}/essayQuestions/{questionId}

 

  g. Get Fill-in-the-Blank question.

GET /users/{userId}/courses/{courseId}/exams/{examId}/sections/{sectionId}/fillintheblankQuestions/{questionId}

 

Optionally, the sequence can be GET each question and then submit its answer instead of GET all questions and then submit each answer as it is completed. Be sure to repeat for all questions in a section and all sections in an exam.
User submits answers.

6. Add answer for each question.

POST /users/{userId}/courses/{courseId}/exams/{examId}/attempts/{attemptId}/answers/{answerId}

 

  • {answerId}={questionId} being answered.
  • POST each answer ID only once. Repeating the POST to an existing answer will return an error.
User changes previously submitted answer. 7. Get answer.

GET /users/{userId}/courses/{courseId}/exams/{examId}/attempts/{attemptId}/answers/{answerId}

 

8. Update answer.

PUT /users/{userId}/courses/{courseId}/exams/{examId}/attempts/{attemptId}/answers/{answerId}

If user manually completes exam...

9. Update attempt to completed status.

PUT /users/{userId}/courses/{courseId}/exams/{examId}/attempts/{attemptId}

  • Attempt instance is locked against any further changes.
  • Response body includes exam end time and links to user's exam instance and attempt instance.
  • Automatic processing occurs (for example, auto-grading if it had been enabled, notifications sent, etc.).
If exam duration is about to expire... 10. POST/PUT any saved answers before the exam duration expires (see steps 6 through 8).

 

11. Update attempt to completed status (see step 9).

  • Attempt instance is locked against any further changes once the Pearson_exam_token expires. The exam duration is calculated using the LearningStudio server time.
  • Any answers that are not POST/PUT to the attempt instance will be blocked once the Pearson_exam_token expires.
If exam duration expires... 12. Update attempt to completed status (see step 9).
  • Attempt instance is locked against any further changes.
  • Automatic processing occurs (for example, auto-grading if it had been enabled, notifications sent, etc.).
Optionally, display a summary of the grading results.

Review Exam Attempt

2594 reads
Always Learning
Pearson