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.
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.
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.
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.
SCORM includes specific algorithms that content can use to find the SCORM 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:
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.
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”.
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.
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.
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.
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.
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.
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.
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 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:
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):
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:
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.