Integrate with the Scorpion API to administer exams

Scorpion now has the functionality of SEI. Scorpion can now be used in conjunction with an exam administration system that provides registration, authentication, payment, and scheduling. Follow this guide to integrate your administration system with Scorpion.

To perform the tasks in this guide for a given exam, your app will need to have the Delivery role in that exam.

 Generate Exam Launch and Proctor URLs

Examinees are not registered Scorpion users. Once your app has authenticated the examinee and authorized that they are able to take an exam, your app will POST to the following endpoint:

https://scorpion.caveon.com/api/exams/<exam_id>/deliveries

Exam_id is the UUID of the exam and can be found in the SEI Console.

Your payload should be a JSON object and may contain the following OPTIONAL values:

{
    "examinee_id": "<uuid4>",
    "examinee_info": {},
    "accommodations": {}
}

The examinee_id, if provided, must refer to an examinee belonging to the same sponsor organization of the exam. If no examinee_id is provided, one will be generated by Scorpion. Please store this ID in your database.

The examinee_info object can contain any data about examinee that the sponsor organization would like to see alongside their examinees’ response data and score reports. Allowed/required fields are configured in Scorpion.

An example POST request:

POST /api/exams/<exam_id>/deliveries HTTP/1.1
Host: https://scorpion.caveon.com
Authorization: Basic <base64 encoded id:secret>
Content-Type: application/json

{
    "examinee_info": {
 "First Name": "Evan",
 "Last Name": "Anderson",
 "Email": "evan.anderson@example.com",
 "Company": "Caveon"
 },
 "accommodations": {
 "time_limit": 3600
 }
}

This POST request returns the following JSON:

{
    "examinee_id": "<uuid4>",
    "delivery_id": "<uuid4>",
    "launch_token": "<token>",
    "proctor_token": "<token>"
}

The launch_token is good for a one-time launch of the exam. The proctor_token can be used to access the proctor tools (pause, resume, suspend) for as long as the delivery is in progress.

Generate your launch and proctor URLs by appending the tokens to the appropriate endpoints, like so:

https://scorpion.caveon.com/take?launch_token=<launch_token>
https://scorpion.caveon.com/proctor/<proctor_token>

Should an exam session crash or end prematurely for any reason, a fresh launch_token to the unfinished delivery can be regenerated by re-posting to the https://sei.caveon.com/api/exams/<exam_id>/deliveries endpoint with the examinee_id in the payload.

Alternatively, once the delivery_id is known, these tokens can be obtained individually by sending a GET request to the following endpoints:

https://scorpion.caveon.com/api/exams/<exam_id>/deliveries/<delivery_id>/get_launch_token
https://scorpion.caveon.com/api/exams/<exam_id>/deliveries/<delivery_id>/get_proctor_token

For obvious reasons the proctor should never see the launch_token and vice versa.

Accommodations

Accommodations override the default exam settings. Currently the only supported accommodation is time_limit. It should be an integer representing the seconds that should be given to this examinee to complete the exam. Add it to the accommodations object when posting a delivery.

"accommodations" {
    "time_limit": <integer (in seconds)>
}

Proctor Events

For tighter proctor integration than simply opening the proctor tools in a new tab, the delivery API has a proctor_events endpoint that your app can POST actions to.

https://scorpion.caveon.com/api/exams/<exam_id>/deliveries/<delivery_id>/proctor_events

{
    "event": "<event string>"
}

Supported events include “pause”, “resume”, and “suspend”.

The Delivery Endpoint

Your app can make GET requests to the delivery endpoint to get information about a given delivery:

https://scorpion.caveon.com/api/exams/<exam_id>/deliveries/<delivery_id>

By default this endpoint will return minimal information, but by using the ?include= query parameter, you can retrieve status, progress, and log information for your proctors. Just separate the desired fields with commas:

https://scorpion.caveon.com/api/exams/<exam_id>/deliveries/<delivery_id>?include=progress,logs

The following fields can be included:

• logs:An array of timestamped exam and browser events
• progress: An object containing delivery progress information such as question number, time remaining, etc.
• pic_urls: an array of image URLs uploaded by the administration system during the exam
• accommodations: object containing the accommodations requested for this user