Assessment Test Session Management

Assessment Test Session Management

The QTI-SDK enables to run a QTI test by providing an API enabling to track the following candidate actions:

• Begin and end attempts on item. Ending an attempt lead to item responses to be submitted, and response/outcome processing to be triggered if required
• Move back and forward across the test. Backward moves will be allowed only in case of the current QTI navigation mode is non linear
• Jump from items to items, in case of the current QTI navigation mode is non linear

Basic Assessment Test Session Instantiation

All the interactions of the candidate with the test can be registered using qtism\runtime\tests\AssessmentTestSession objects. Such objects are instantiated via a qtism\runtime\tests\SessionManager object, taking care of dealing with all the QTI aspects to be taken into account to deliver an Assessment Test Session e.g. Item selection and ordering, Branch Rules, Preconditions, ...

use qtism\runtime\tests\SessionManager;
use qtism\data\storage\xml\XmlCompactDocument;
use qtism\data\storage\xml\XmlDocument;
use qtism\common\datatypes\files\FileSystemFileManager;
use qtism\common\datatypes\QtiIdentifier;
use qtism\common\enums\BaseType;
use qtism\common\enums\Cardinality;
use qtism\runtime\common\ResponseVariable;
use qtism\runtime\common\State;

// Load a test composed of 3 items within a single section, in a single test part with linear navigation mode.
$testDoc = new XmlDocument();
$testDoc->load('test.xml');

/*
 * Compile the test definition into a single compact object. 
 *
 * All the information required to run a test session (outcome/response processing rules,
 * selection and ordering rules, branching and precondition rules, will be collected from 
 * the test and its related items.
 *
 * The resulting qtism\data\storage\xml\XmlCompactDocument can be persisted for later usage. 
 */
$compactDoc = XmlCompactDocument::createFromXmlAssessmentTestDocument($testDoc);

$manager = new SessionManager(new FileSystemFileManager());
$session = $manager->createAssessmentTestSession($compactDoc->getDocumentComponent());

// Begin test session.
$session->beginTestSession();

// Perform an attempt on 1st AssessmentItemSession and move to the next one.
// Candidate response is 'ChoiceA'.
$session->beginAttempt();
$session->endAttempt(new State([new ResponseVariable('RESPONSE', Cardinality::SINGLE, BaseType::IDENTIFIER, new QtiIdentifier('ChoiceA')))]);
$session->moveNext();

// Perform an attempt on 2nd AssessmentItemSession and move to the next one.
// Candidate response is 'ChoiceC'.
$session->beginAttempt();
$session->endAttempt(new State([new ResponseVariable('RESPONSE', Cardinality::SINGLE, BaseType::IDENTIFIER, new QtiIdentifier('ChoiceC')))]);
$session->moveNext();

// Perform an attempt on 3rd AssessmentItemSession and finish the AssessmentTestSession.
// Candidate response is 'ChoiceB'.
$session->beginAttempt();
$session->endAttempt(new State([new ResponseVariable('RESPONSE', Cardinality::SINGLE, BaseType::IDENTIFIER, new QtiIdentifier('ChoiceB')))]);
$session->moveNext();

// The last call to the moveNext() method causes the test session to automatically close, as there are no more items to be visited by the candidate.

Persisting Assessment Test Sessions

Assessment Test Sessions state can be persisted in order to be retrieved later on. Implementations of the abstract class qtism\runtime\storage\binary\AbstractQtiBinaryStorage enables you to deal with the multiple aspects of persistence like instantiating a test session, persisting and retrieving it. The QTI-SDK provides a LocalQtiBinaryStorage local storage implementation for testing purposes. Users of the SDK can produce their own implementation in order to meet their requirements.

use qtism\runtime\tests\SessionManager;
use qtism\data\storage\xml\XmlCompactDocument;
use qtism\data\storage\xml\XmlDocument;
use qtism\common\datatypes\files\FileSystemFileManager;
use qtism\runtime\storage\binary\LocalQtiBinaryStorage;

$testDoc = new XmlDocument();
$testDoc->load('test.xml');
$compactDoc = XmlCompactDocument::createFromXmlAssessmentTestDocument($testDoc);
$sessionManager = new SessionManager(new FileSystemFileManager());

// The storage deals with a SessionManager object, and a given test definition.
$storage = new LocalQtiBinaryStorage($sessionManager, $compactDoc->getDocumentComponent());

// Call the instantiate method to create new assessment test session.
$testSession = $storage->instantiate();

// The session ID will be useful to retrieve a persisted session.
$sessionId = $session->getSessionId();
$testSession->beginTestSession();

// ...

// Persist the test session after candidate interaction.
$storage->persist($session);

// You can retrieve the test session at anytime as soon as it has been persisted
// for the first time, using the provided session ID.
$testSession = $storage->retrieve($sessionId);

// ...

// And can be removed from persistence if required.
$testSession->delete($testSession);

Dealing with Exceptions

The business rules described in the QTI specification family are numerous, and it can lead the Assessment Test Session to be in an inconsistent state, depending on the flow of actions taken by the candidate and the complexity of the QTI Assessment Test being run. While interacting with a qtism\runtime\tests\AssessmentTestSession object, qtism\runtime\tests\AssessmentTestSessionException exceptions might be thrown. It is the responsibility of the client code to deal with these exceptions accordingly.

Depending on the value returned by the qtism\runtime\tests\AssessmentTestSessionException::getCode() method, the client code is able to determine what is the exact meaning of the exception.

• qtism\runtime\tests\AssessmentTestSessionException::STATE_VIOLATION: A method is called at an invalid moment regarding the current state of the test session, or the state of an item currently visited. For instance, the method qtism\runtime\tests\AssessmentTestSession::beginAttempt() method is called before the assessment test has properly begun using qtism\runtime\tests\AssessmentTestSession::beginTestSession().

• qtism\runtime\tests\AssessmentTestSessionException::NAVIGATION_MODE_VIOLATION: The navigation mode is not respected. For instance, this exception will be thrown in case of the current test part is in non linear mode, but the qtism\runtime\tests\AssessmentTestSessionException::moveBackward() or qtism\runtime\tests\AssessmentTestSessionException::jumpTo() method is called.

• qtism\runtime\tests\AssessmentTestSessionException::OUTCOME_PROCESSING_ERROR: An error occurs while performing outcome processing e.g. An operator is given invalid data.

• qtism\runtime\tests\AssessmentTestSessionException::RESPONSE_PROCESSING_ERROR: An error occurs while performing response processing e.g. An operator is given invalid data.

• qtism\runtime\tests\AssessmentTestSessionException::RESULT_SUBMISSION_ERROR: A problem occurred while submitting item or test results.

• qtism\runtime\tests\AssessmentTestSessionException::FORBIDDEN_JUMP: Call to the qtism\runtime\tests\AssessmentTestSessionException::jumpTo() method at an inappropriate position in the test flow.

• qtism\runtime\tests\AssessmentTestSessionException::TEST_PART_DURATION_OVERFLOW: Call to any method changing the state of the test session while the maximum time to be spent on a test part is exceeded.

• qtism\runtime\tests\AssessmentTestSessionException::ASSESSMENT_SECTION_DURATION_OVERFLOW: Call to any method changing the state of the test session while the maximum time to be spent on an assessment section is exceeded.

• qtism\runtime\tests\AssessmentTestSessionException::ASSESSMENT_ITEM_DURATION_OVERFLOW: Call to any method changing the state of the test session while the maximum time to be spent on an assessment item is exceeded.

• qtism\runtime\tests\AssessmentTestSessionException::ASSESSMENT_ITEM_ATTEMPTS_OVERFLOW: This exception code is used when the amount of allowed attempts on an assessment item session is exceeded.

• qtism\runtime\tests\AssessmentTestSessionException::ASSESSMENT_ITEM_INVALID_RESPONSE: This exception code is used when the base type or cardinality of the response provided while ending an attempt is not expected.

• qtism\runtime\tests\AssessmentTestSessionException::ASSESSMENT_ITEM_SKIPPING_FORBIDDEN: This exception code is used as soon as the method qtism\runtime\tests\AssessmentTestSessionException::skip() method is called but skipping is not allowed.

use qtism\runtime\tests\AssessmentTestSessionException;
use qtism\common\datatypes\QtiIdentifier;
use qtism\common\enums\BaseType;
use qtism\common\enums\Cardinality;
use qtism\runtime\common\ResponseVariable;
use qtism\runtime\common\State;

// ...

try {

    $testSession->beginAttempt();
    $testSession->endAttempt(new State([new ResponseVariable('RESPONSE', Cardinality::SINGLE, BaseType::IDENTIFIER, new QtiIdentifier('ChoiceA')))]);

} catch (AssessmentTestSessionException $e) {

    $code = $e->getCode();
    if ($code === AssessmentTestSessionException::ASSESSMENT_ITEM_ATTEMPTS_OVERFLOW) {
        // Amount of allowed attempts exceeded...
    } elseif ($code === AssessmentTestSessionException::RESPONSE_PROCESSING_ERROR) {
        // Response processing error...
    } else {
        // ...
    }
}