A Learnosity session represents a unique attempt of an assessment by a student at a specific time. It records all the Questions presented to the student in that assessment, the student's responses to those Questions, as well as metadata about the assessment.
The most basic lifecycle for a session includes creation, submission and reporting. Learnosity also supports more complex session lifecycles with save/resume and manual scoring. Each of these stages of a session's lifecycle are detailed in the sections below.
Figure 1: Possible lifecycles of a Learnosity session.
Creating a session
The usual way to create a new session is to initialize a new assessment in a web browser via Items API, and pass a new
session_id as part of your initialization options. The new session will be persisted in Learnosity's data stores when the first save, autosave or submit action is processed for the assessment.
When it is first created by a save or autosave action, the session will be in the "Incomplete" status. More information about status can be found in the session statuses section below.
To prevent users from losing progress on an assessment they haven't saved yet (or haven't saved since their last update), Learnosity Assessments will warn the user that they have unsaved changes if they attempt to navigate away from the assessment. Learnosity's assess player can optionally display a "Save and Exit" button to provide a structured way for users to save their changes and navigate away.
Note that autoscoring is run on a user's responses every time they are saved. This allows back-end scores to be available via Data API for an Incomplete session before its final submission. However, the autoscoring is asynchronous, so there can be a short delay between the user's updates and the scores reflecting in Data API.
If required, you can programmatically trigger Items API to perform a save operation by calling the itemsApp.save() method.
Submitting a session
Submitting a session generally means finalising the user's responses to their assessment. The assessment data is lodged for final grading and reporting. A session can be submitted in the following ways:
- The user performs the submit action in their browser-based assessment.
- Programmatically trigger Items API to perform a submit operation by calling the itemsApp.submit() method.
- The session is forcefully updated to "Completed" status via Data API's UPDATE /jobs/sessions/statuses endpoint.
When a session is submitted, the following processing is triggered (in sequence):
- Autoscoring is rerun on all the user's responses.
- If the status of the session was "Incomplete", it is updated to "Completed".
- The session data is published via Learnosity Firehose (if applicable).
Other asynchronous processes are also triggered and do not have a defined sequence or completion time. For example:
- Subscores are calculated for the session and stored for retrieval via Data API.
- Adaptive session data is compiled for retrieval via Data API's GET /sessions/reports/adaptive endpoint.
- Session data is ingested into Learnosity Analytics for use in tag-based reporting and aggregate reports.
Resuming a session
Sessions in any status can be resumed by Initializing Items API with the same
session_id and list of Items from the original session. Any saved responses will be restored into the browser and can be reviewed/updated.
Since status does not affect whether Learnosity will allow the session to be resumed, there are some important things to note:
- A session that has been put into the Discarded or Completed status can still be resumed, if your implementation allows it.
- Sessions can be submitted multiple times (e.g. after resuming a session that was already submitted).
Take those into consideration as you design your Learnosity integration.
Reporting on a session
A submitted session can be reported on using Learnosity's Reports API.
Simply initialize the desired report type via Reports API and pass the combination of
session_id filters for the relevant session/s.
Note that sessions in Incomplete or Discarded status are not available in Reports API.
Manual scoring for a session
For non-autoscored Question types like short text, essays, audio and video, it is common to implement a manual scoring process whereby an instructor, scorer or grader manually assigns a subjective score to the student's response.
Those scores can be uploaded to Learnosity via the UPDATE /sessions/responses/scores endpoint. This ingests them into Learnosity's analytics engine so they are accessible via Reports API and Data API.
Where appropriate, reports will show a "Not marked" score component for sessions, Items or Questions that still require manual grading.
Interacting with sessions via Data API
You can interact with sessions programmatically via Learnosity's Data API.
The most common interaction is to retrieve session data based on a variety of filters like users, activities, timeframe or status. Data API has endpoints for retrieving a session's scores, response data, metadata, and more.
There are also various ways to manipulate sessions:
- You can forcibly change a session's status using the UPDATE /jobs/sessions/statuses endpoint.
- You can update the scores of a session using the UPDATE /sessions/responses/scores endpoint. This can be used to upload manual scores for a session, or to override the scores of autoscored Questions.
- You can import session data from a paper-based exam or from a failed submission packet via the SET /sessions endpoint. A failed submission packet is a secure data packet that is provided to students who encounter network issues while trying to submit their test.
You can retrieve the status of a session using Data API's various endpoints (eg. GET /sessions/statuses, GET /sessions/scores, etc.). You can also use the session status as a filter in Data API's endpoints, to retrieve only those sessions matching one or more desired status values.
You can forcibly change a session's status between any of the possible statuses using the UPDATE /jobs/sessions/statuses endpoint.
There are three possible statuses for a Learnosity session:
New sessions are in this status when they are first created by a save. Incomplete sessions are invisible to Learnosity's reporting (via Reports API).
Submitting an Incomplete session will move it to Completed status.
You can also Force a session to Completed status via the UPDATE /jobs/sessions/statuses endpoint. Doing so triggers the transition steps and asynchronous processes detailed for Submitting a session (even if its status is already "Completed").
A session can be moved into this status when the user performs the discard action in the assessment player. Discarded sessions are invisible to Learnosity's reporting (via Reports API).