SCORM Run-Time Environment

| 13 Jan 2009 | Permalink

Overview of the SCORM Run-Time

The SCORM run-time specification controls how the LMS launches content and how the content then communicates with the LMS. All of this communication happens within the context of a single attempt on a single SCO.  The navigation between SCOs is governed by the sequencing specified in the manifest, and explained further here.

Launching Content

All SCORM content must be web-deliverable and all SCORM communication occurs within the context of a web browser session. The LMS will launch one SCO at a time, as selected by the user, or as determined by SCORM 2004 sequencing rules. In versions prior to SCORM 2004 3rd Edition, there were no formal requirements for the user interface provided by an LMS. Every LMS is slightly different, but for the most part, it is fair to expect an LMS to provide an interface similar to the one pictured below. At a minimum, it should contain some form of navigable table of contents as well as controls for flow navigation (previous and next buttons). These navigational elements control the navigation between SCOs. If navigation is needed within a SCO, the SCO must provide its own navigational elements.

lms-interface

The LMS has two options for launching a SCO. It can either launch the SCO in a frameset (as pictured above), or it can launch the SCO in a new window. Some LMS’s will always launch content one way or the other. Commonly though, if a course only contains one SCO (and thus doesn’t require and navigational elements from the LMS), the SCO will be launched in a popup window. Conversely, if the course contains many SCOs, then the LMS will commonly launch the SCOs in a frameset surrounded by navigational elements. Some LMS’s will allow the content authors to control precisely how SCOs are launched, which navigational elements are available and even the size of the SCO windows.

The API

All communication between a SCO and the LMS happens through an ECMAScript (JavaScript) API. This is the only way for communication to occur. There are no other communication channels available. Content can not communicate through web services, form posts, database writes or any other mechanism, only through the JavaScript API provided by the LMS.

Finding the API

The LMS is responsible for providing a specifically named JavaScript object in a specific location within the browser’s DOM. Thus, the content, can always locate this API using a common algorithm.

In SCORM 1.1 and SCORM 1.2, the API object is always named “API”. In SCORM 2004, the object is named “API_1484_11″.

The API object should be located in a window that is a parent of the SCO or a parent of the opener window of the SCO. A “parent” window is defined to be the entire chain of parent windows all the way up to the root browser window. So, the API could be in the SCO’s parent, the SCO’s parent’s parent, the SCO’s parent’s parent’s parent, etc. Similarly, the API could be in the opener window, the opener’s parent, the opener’s parent’s parent, etc. The diagrams below from the SCORM 2004 3rd Edition specification illustrate the possible API locations.

api_locations

SCORM includes specific algorithms that content can use to find the SCORM API.

Using the API

Once a SCO has found the SCORM API, it can use the API to communicate with the LMS. Note, that only the SCO can initiate communication. The LMS is a passive entity that simply responds to the API calls made by the content. The LMS can’t initiate any communication, it simply launches the content and responds to requests.

The SCORM API contains eight methods with the following signatures:

SCORM 2004

Initialize( “” ) : bool
Terminate( “” ) : bool
GetValue( element : CMIElement ) : string
SetValue( element : CMIElement, value : string) : string
Commit( “” ) : bool
GetLastError() : CMIErrorCode
GetErrorString( errorCode : CMIErrorCode ) : string
GetDiagnostic( errocCode : CMIErrorCode ) : string

SCORM 1.1 / SCORM 1.2

LMSInitialize( “” ) : bool
LMSFinish( “” ) : bool
LMSGetValue( element : CMIElement ) : string
LMSSetValue( element : CMIElement, value : string) : string
LMSCommit( “” ) : bool
LMSGetLastError() : CMIErrorCode
LMSGetErrorString( errorCode : CMIErrorCode ) : string
LMSGetDiagnostic( errocCode : CMIErrorCode ) : string

The method names vary slightly between SCORM versions, but conceptually the methods are identical.

Notes:

  • The bool type is a SCORM boolean, which is actually a string having the value “true” or “false”.
  • The “” parameter is required by all SCORM methods that don’t accept any other arguments. SCOs are simply required to pass an empty string parameter to these methods.
  • The CMIElement data type is a string corresponding to the SCORM data model elements described below.
  • The CMIErrorCode data type is a three digit number, represented a string, that corresponds to one of the SCORM Run-Time error codes.

Initialize / LMSInitialize

The Initialize method indicates to the LMS that the content would like to begin a communication session. All SCOs must call Initialize before performing any other communication. The LMS returns a boolean indicating the success or failure of the initialization. Typically, LMS’s don’t need to do a lot of initialization and will always return “true”.

Terminate / LMSFinish

The Terminate method indicates to the LMS that the content is done communicating. All SCOs must call Terminate. Calling Terminate doesn’t necessarily indicate that the user is done with the SCO, technically it only indicates the the SCO is done communicating. In practice however, content will be more compatible and usable if Terminate is only called when the content can be taken away from the user. Since Terminate is required to always be called, no matter how the learner exits the SCO, it is wise to place a call to Terminate in the onunload event of a SCO. The boolean value returned by the LMS often indicates whether or not SCO data was successfully persisted to the server.

GetValue / LMSGetValue

The GetValue method allows a SCO to retrieve data from the LMS. The data that is always retrieved is one of the defined SCORM data model elements. Each of these data model elements holds a different piece of data. Some of the data model elements have values initialized by the LMS which speak to the circumstances under which the SCO is being launched. Other values are initialized by the SCO through calls to SetValue. If the call to GetValue returns an empty string, it is possible that an error occurred and the GetLastError method should be invoked to check for problems.

SetValue / LMSSetValue

The SetValue method allows the SCO to persist data to the LMS. The data is always stored in one of the defined SCORM data model elements. Some data model elements are constrained to having values in a limited vocabulary (for instance, status might be “completed” or “passed”), others are constrained to being a specific data type (for instance, score must always be a number) while others allow the SCO to persist free text data with no semantic meaning. The SetValue call returns a boolean indicating the success or failure of the call.

Commit / LMSCommit

The Commit method signals to the LMS that a significant chuck of data has been saved and that it should ensure the data is properly persisted. There are no requirements for how the LMS should implement the Commit method, it is simply an informative signal. Some LMS’s will make a round trip to the server for every call to Commit to ensure that all data is persisted. While intuitive, this implementation strategy can lead to scalability problems. Take care not to call Commit excessively so as not to overburden these LMS’s.

GetLastError / LMSGetLastError

The GetLastError method checks to see if the last SCORM API call caused an error. If so, this method returns an error number that corresponds to a defined set of possible errors. Some error numbers represent perfectly legitimate situations (such as 403 – Data Model Element Not Initialized). SCO authors should take care to only flag legitimately unexpected errors to the user. The complete list of error codes can be found in the SCORM run-time reference chart.

GetErrorString / LMSGetErrorString

Given a particular error number (usually the error number returned from GetLastError), the GetErrorString method will return a textual description of what the error code means. For instance, in SCORM 2004, passing error number “406″ will return a string saying “Data Model Element Type Mismatch” to indicate that the result of the previous call (likely a SetValue) failed because the data being stored was not in the correct format.

GetDiagnostic / LMSGetDiagnostic

The GetDiagnostic method allows the LMS to return detailed information about the prior error that can be useful in diagnosing the problem. For instance the diagnostic information for the “406″ error mentioned above might be “The value ‘zero’ is not allowed for cmi.score.raw. The cmi.score.raw element must contain a valid number represented only as digits”.

The SCORM Run-Time Data Model

The run-time data model contains many elements, each which has its own meaning. The elements can be read and written using the API. The SCORM run-time reference chart contains a list of each data model element along with its data type and a short description of its meaning and usage.

Every SCO has its own set of run-time data. Each of these data model elements has a separate value for each SCO within a course, data model elements are not shared across SCOs. Furthermore, each “attempt” on a SCO has it’s own set of run-time data. When the learner starts a new attempt on a SCO, the data model values will be reset for the start of the new attempt.

The data model elements are slightly different across SCORM versions, but for the most part there is a corresponding element in each version of the standards. SCORM 1.1 and SCORM 1.2 have identical data models. SCORM 2004 has a different data model set. There are minor subtle differences between the editions of SCORM 2004 as well. The chart provides a comprehensive reference for each version/edition. The most significant changes in SCORM 2004 include:

  • Minor renaming, mostly removing the “core” from the data model element names.
  • Separation of status. In SCORM 1.2 a single element, cmi.core.lesson_status represents the SCO’s status. In SCORM 2004, status is broken down into two separate elements, cmi.completion_status (completed vs incomplete) and cmi.success_status (passed vs failed).
  • Interactions (question results) are read/write instead of write-only. Interactions also contain a description field that was lacking in SCORM 1.2.
  • Addition of adl.nav.* data model elements that allow the SCO to initiate sequencing requests

Using the Run-time

Using the SCORM run-time is largely optional from a strict conformance perspective, however the industry norm is to use at least a subset of the run-time data model elements available to you.

At the simplest, if your course contains nothing but launchable assets, no run-time calls are needed. The LMS simply launches each asset as requested by the user and the asset is considered to be completed immediately upon launch.

For a richer interaction, the first thing we need to do is enable run-time communication. That will involve finding the API and then ensuring that Initialize and Terminate are called. In most cases, Initialize should be called immediately after the SCO is launched. Once initialize has been called, it is essential that Terminate be called in every exit scenario.

Once communication has been initialized, it is time to start actually communicating data. The following “1st tier” data model elements are the most important and most commonly used (SCORM 1.2 equivalent in parentheses):

  • cmi.completion_status & cmi.lesson_status (cmi.core.lesson_status) – These data model elements are the most fundamental and important. They indicate when a user has finished a course and if he passed or failed. This fundamental information is essential to most LMS’s.
  • cmi.score.scaled (cmi.score.raw) – Indicates the score that the learner earned on any assessment within a SCO. Reporting a min and max score in conjunction with a raw score is also good form.
  • cmi.session_time (cmi.core.session_time) – Reports the amount of time that the learner spent in the SCO.
  • cmi.location (cmi.core.lesson_location) – Provides a free text field for the SCO to record a bookmark. If the SCO is bigger than just a couple HTML pages, it should consider implementing a bookmarking feature to let the learner resume a paused attempt.
  • cmi.exit (cmi.core.exit) – This value indicates how the learner is exiting the SCO. Setting cmi.exit to “suspend” will ensure that the current attempt is preserved and the run-time data is not reset the next time the SCO is launched. Setting cmi.exit to “” will indicate that the LMS should begin a new attempt with a new set of run-time data on the next launch of the SCO.

Industry norm expects all of the 1st tier data models elements to be used correctly in a SCO. Once that functionality has been enabled, the next most common data model elements, or 2nd tier, include:

  • interactions – Use the interactions data model elements to report the results of each question response. An interaction doesn’t have to be a traditional test answer. For instance, a SCO could document the learner’s choices as he progresses through a simulation. If possible, use all of the interactions elements to provide the most comprehensive picture of the learner’s responses. At a minimum, use “id”, “type”, “result” and “description” to allow LMS’s to provide basic reporting.
  • objectives – In large SCOs, consider reporting on the learner’s mastery of specific learning objectives using the objectives data model elements. Objectives allow for more granular reporting of the learner’s progress through and mastery of the training material.
  • cmi.progress_measure – Use the progress_measure element in SCORM 2004 to report the user’s progress towards completion of a SCO. The progress_measure is like a “percent complete” measure that would enable the LMS to provide a progress bar of overall completion of a course.

Entry, Mode and Credit

The cmi.entry (cmi.core.entry), cmi.mode (cmi.core.lesson_mode) and cmi.credit (cmi.core.credit) data model elements provide the SCO with some context it can use to provide the learner with the optimal experience.

  • cmi.entry indicates whether the user is starting the SCO for the first time or if it is resuming a prior attempt. If using bookmarking, the SCO might use this value to prompt the user to start from the beginning or from the point at which the previous attempt ended.
  • cmi.mode indicates whether the learner is launching this SCO: normally – in a “live” training session; in browse mode – the user is browsing a catalog of training and wants to “preview” this course; or, in review mode – the user has already completed the SCO and is coming back to review the material. In browse mode, the SCO author should consider altering the SCOs behavior to provide more free form navigation, provide an overview or map of the course and possibly hide assessments. In review mode, the SCO author should similarly consider allowing the leaner complete freedom of navigation. In review mode, the learner might also be able to freely navigate any tests and browse a list of correct answers. When launched in review mode, a SCO should be careful not to change the learner’s status or reset the score.
  • cmi.credit indicates whether or not this SCO is being attempt for credit, or whether or not it “counts”. Similar to browse mode, if a SCO is launched for no credit, the behavior should probably be altered.

SCORM Run-Time References

Run-Time Examples