Assessment states

This article covers state, how it is used and what it does across Learnosity Assessment APIs. States are used to control the startup modes of the APIs, to allow for different API behaviors during an assessment.

The state will determine the mode each API should use to initialize.
Based on its value, you will be able to start/preview a new activity or continue/review an existing one. Therefore, there are four possible values: "initial", "preview", "resume", and "review".

It is not always necessary to define state and each API has some subtleties about its use which are clarified in the following sections.

In Questions API, the state is associated with the session_id and/or the practice type.

  • "initial": renders the question in its initial and unattempted state.
  • "preview": renders the same view as "initial" but also locks any ability for user to interact with the question.
  • "resume": reloads the question with any pre existing responses associated with the question.
  • "review": renders the question displaying the validation UI (whether it has been attempted or not), while also locking any interaction by the user. This mode is typically used by a teacher or student to review the answers.

In Local Practice, no session is saved to the server. So if you want to resume/review an activity, you will have to pass the response JSON during the initialization.

In Submit Practice, everything relies on the session_id, which is associated to a session saved to the server. A session contains details such as user responses, metadata and so on.
There are two important things to remember when setting state for Submit Practice:

  • Using "initial" with an existing session_id will throw an error. You cannot re-initialize an already existing session.
  • Using "resume" with a new session_id will also throw an error unless you are using the "captureOnResumeError" flag. When set to true, this flag allows the API to bypass the error, creating a new session instead of trying to resume. This is the same as setting state to "initial" with a new session_id.

More information about Practice Types can be found in our Local Practice & Submit Practice Knowledge Base article.

In Assess API, the state defined in questionsApiActivity is used to initialize Questions API internally and based on its value, Assess API will render/behave accordingly.

  • "initial": renders the assessment for the first time. It will load the first Item or the intro Item if included.
  • "preview": same as "initial" but the activity cannot be saved or submitted, nor the items interacted with by the user.
  • "resume": reloads the assessment with any pre existing responses and metadata associated with the contained items.
  • "review": each item will be rendered with the validation UI. In this mode the activity cannot be saved or resumed, while also locking any interaction by the user.

During initialization, Assess API can be passed the existing_session flag that defines how Assess API will render/behave.
Note This flag has no impact on Questions API initialization.

  • When existing_session is set true it will load Assess API as if it was in resume mode. Hence disabling certain functionality such as the intro item.
  • When existing_session is set false it will load Assess API as if it was in initial mode.
  • If existing_session is not set, Assess API will fall back to whatever value is set for state.

When initialising Items API, the state does not need to be set for initial or resume mode, internally the API will check whether a session exists for a given session_id.

  • If an existing session is found the assessment will be initialized in resume mode.
  • If no existing session is found a new assessment will be created.

However, if you want to initialise an assessment in review or preview mode, the state needs to be set using either "review" or "preview" as required.