Storage Providers

Exam data is stored via a storage provider, which is a list of functions. Each user action will trigger a storage event for which one of the functions provided by the storage provider is called. See dbi_storage_provider() for an implementation based on a DBI backend.

Details

Storage providers must implement all of the functions listed under Storage functions.

Arguments

The arguments to the storage functions are:

user: the user object (as returned from the configured authentication provider). May be NULL for get_section_data(), in which case data for all users is requested.
exam_id: the exam id as given in the Rmd file.
exam_version: the exam version string as given in the Rmd file.
seed: an integer representing the random seed associated with the attempt.
started_at: the timestamp when the attempt was started (as POSIXct object in the system's timezone).
finished_at: the timestamp when the attempt was finished (as POSIXct object in the system's timezone).
attempt_id: the attempt identifier as returned by start_attempt() or get_attempts().
section: the section identifier string. May be NULL for get_section_data(), in which case data for all sections is requested.
section_data: an R list object with arbitrary elements. The storage function should not make any assumptions on the make-up of this list.
points: an R list object with arbitrary elements. The storage function should not make any assumptions on the make-up of this list.
...: additional arguments for future extensions.

Storage functions

`create_attempt(user, exam_id, exam_version, seed, started_at, ...)`

Create a new attempt with the given seed and start time. The function should return a unique identifier for the attempt. In case of an error, the function should return FALSE.

`finish_attempt(attempt_id, finished_at, ...)`

Mark the attempt as finished. The function should return TRUE if the data is saved successfully and FALSE in case of an error.

`grade_attempt(attempt_id, points, ...)`

Grade the given attempt, i.e., assign the given points to the attempt. The function should return TRUE if the points are saved successfully and FALSE in case of an error.

`get_attempts(user, exam_id, exam_version, ...)`

Return a list of all previous attempts for the given filter. The argument user can be NULL, in which case the function should return the attempts for all users. The function must return a list of attempts. Each list object must contain the following:

id: the identifier associated with this attempt.
user: the user object associated with this attempt.
started_at: the time (as POSIXct object in the system's timezone) the attempt was started.
finished_at: the time (as POSIXct object in the system's timezone) the attempt was finished, or NULL if it has not been finished.
points: the R list object as given to grade_attempt(), or NULL if the attempt is not yet graded.

In case there are no attempts associated with this user and exam, or in the case of an error, the function should return an empty list.

`save_section_data(attempt_id, section, section_data, ...)`

Save the given section data. The function should return TRUE if the data is saved successfully and FALSE in case of an error.

`get_section_data(attempt_id, section, ...)`

Query the most recent section data for the given attempt. If section is NULL, the function should not filter data for this criterion. In this case the function should return only the most recent section data available for the given attempt. The function must return a list of section data objects matching the given filter. Each object must contain the following:

section: the section identifier string as given in the call to save_section_data().
timestamp: the time (as POSIXct object in the system's timezone) the section data was saved.
section_data: the section data object as given in the call to save_section_data().

In case of an error, or if there is no data available for the given filter, the function should return an empty list.

`get_last_section(attempt_id, ...)`

Get the identifier of the section for which the most recent data is available. The function should return a character with the section identifier of the section for which data was saved most recently. In case of an error, or if there is no data available for the given filter, the function should return NULL.

Details

Arguments

Storage functions

create_attempt(user, exam_id, exam_version, seed, started_at, ...)

finish_attempt(attempt_id, finished_at, ...)

grade_attempt(attempt_id, points, ...)

get_attempts(user, exam_id, exam_version, ...)

save_section_data(attempt_id, section, section_data, ...)

get_section_data(attempt_id, section, ...)

get_last_section(attempt_id, ...)