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.
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:
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 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:
"initial"with an existing
session_idwill throw an error. You cannot re-initialize an already existing session.
"resume"with a new
session_idwill 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
"initial"with a new
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.
trueit will load Assess API as if it was in resume mode. Hence disabling certain functionality such as the intro item.
falseit will load Assess API as if it was in initial mode.
existing_sessionis not set, Assess API will fall back to whatever value is set for
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
- 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
"preview" as required.