API Documentation
Using the API
To get started:
- This process is the same for all versions of AICC, SCORM, cmi5, and Tin Can. You should already have your course created — your HTML, your movies, images, all assets for your content.
- Take all of the files that comprise your course, and drop them in the
scormcontent
folder. If your copy of Driver doesn’t have ascormcontent
folder, just create one at the top level and continue to follow these instructions after you’ve done so. Note what the file name is for the first page of your course. You’ll need it for the next step. N.B. You shouldn’t drop just one folder that contains your files into thescormcontent
folder, you should drop your actual HTML and content files into thescormcontent
folder. - In your Driver folder, you should have a
scormdriver
folder containingindexAPI.html
. In that file, you will see this line:strContentLocation = "../scormcontent/index.html";
Update that line to reference the start page of your content, or make sure that your content start page is called "index.html". - Add functionality and AICC / SCORM / cmi5 / Tin Can integration to your content by calling any of the functions described in the Function List found below. The only function that must be called for proper operation is
Finish
. If you would prefer to not have your content call any functions, there is a simple change to make this possible, see the description of theFinish
function for more information. N.B. you should only call functions listed in the Function List. These functions are present in theAPI.js
file; calling other functions outside of this list is not recommended. - To launch your content, simply open your
indexAPI.html
file in a web browser. For most browsers you can use File->Open to browse to your file. - Package your content and import it into an AICC / SCORM / cmi5 / Tin Can conformant LMS (see packaging instructions below).
Function List
All functions that set a value return true
to indicate if they successfully set the value or false
to indicate failure. Functions that retrieve values will return null
to indicate a failure.
Functions marked with an asterisk (*) may not be supported on all LMSs. Functions that set a value will return false
when the element is not supported. Functions that retrieve a value will return the default value for the specified data element.
Start / Finish Functions
Start()
— Called automatically when the frameset loads. Initializes the API and begins communication with the LMS. Start must be called before any other functions (except Time Tracking functions) may be called. This function is called automatically by the onload
event of the indexAPI.html
file and it should not need to be called again in most cases.
These next four functions represent different ways you can indicate that the content is complete. The primary difference is the reason for leaving the content.
Finish()
— Call this function when the user is completely finished with the content. Calling this function is optional, but if you choose not to ever call it, you should change the DEFAULT_EXIT_TYPE
constant in Configuration.js
to ensure that the content is properly completed (see comments in the file for the exact change).
Suspend()
— Call this function when the user wants to pause the content with the intention of resuming later. If you want saved values to be persisted for the next time the user enters the content, it is wise to use the Suspend function to exit the content. In some rare cases, the LMS may choose to only persist data if the content specifically indicates that it is being “suspended”.
TimeOut()
— Call this function when the user is being kicked-out of the content because he/she has exceeded the maximum time allowed for completion of the content (see Time Tracking functions below).
Unload()
— This function is called automatically when the frameset is unloaded. It ensures that Finish is called if the user just closes out the content. This function should not need to be called in most cases.
SetReachedEnd()
— You can optionally call this function to indicate that the user has made sufficient progress in the content to be considered complete. Essentially after calling this function, no matter what type of Finish function above winds up actually getting called when the user exits the content, the LMS will be told that the user finished the content (just as if the Finish
function had been called). This function is useful for content that has a final diploma or confirmation page. When that final page is reached, you should call SetReachedEnd
, that way if the user closes the browser before initiating an action that calls Finish
, the LMS will be told that the user completed the content instead of unloading the content.
ConcedeControl()
— This function will pass control back to the LMS and will optionally close the content window or navigate to a specific URL as determined by the EXIT_BEHAVIOR
parameter in the configuration file. This function is a useful alternative to calling a specific Finish
function. N.B. This function call should originate from a child (or descendent) frame of the indexAPI.html
page. It should not be invoked from a popped up window.
Utilities
IsLoaded()
— Can be called by child frames to ensure that the API is fully loaded and initialized.
WriteToDebug(strInfo)
— The API maintains an extensive set of debug information. This information is basically a log of everything that happens within the API. If you wish to record more information about what is going on in your content, you can call this function to add a line to the debug information.
ShowDebugWindow()
— This function will display a new window containing all of the available debug information. As new debug information is recorded, the contents of this window will be updated to reflect the new information. We recommend that you set up some form of event capture within your content that when fired, will call this function to display the current debug information. Alternatively, if you append the querystring parameter ShowDebug=true
to the launch URL, the debug window will be displayed as soon as the content launches. A lot of processing occurs before your content is actually loaded, if you need to view the debug information during this time, it can be accessed by clicking on the screen and pressing the question mark key (?) three times consecutively.
GetLastError()
— If a function returns a value that indicates an error has occurred (false
for functions that set values, null
for functions that retrieve values), then you can call this function to get an error code. The error code is an integer and constants representing the possible error codes are defined in APIConstants.js
.
GetLastLMSErrorCode()
— If the LMS is reporting an error, this returns the code as set by the LMS.
GetLastErrorDesc()
— If an error was detected, this function will return a string describing the error in detail. When debugging, it is often useful to combine this information with the information in the debug log.
CommitData()
— This function will tell the LMS that you want to ensure all of the data you have sent to it is immediately persisted. Some LMSs will cache data for a while before saving it permanently, invoking this function ensures that any cached data is permanently saved. It is useful to call this function periodically; however excessive use may slow down the content because it may require the LMS to make extra round trips between the client and the server. In most cases, simply setting a value will be sufficient to ensure that it is saved. For cmi5 and Tin Can CommitData
must be called at least once to persist the xAPI Statement data to the LRS, because of this requirement it is automatically called by Finish
for those standards.
Standard
— This property (N.B. This is a property, not a method, so do not use parentheses when reading it.) of the API returns the learning standard being used to communicate with the LMS. Possible values include: “SCORM” (for SCORM 1.1 or SCORM 1.2), “SCORM2004” (for either SCORM 2004 2nd Edition or SCORM 2004 3rd Edition), “AICC”, “CMI5”, “TCAPI” (for Tin Can), or “NONE” (for standalone mode).
Storing and Retrieving General Data
GetStudentID()
— Returns the ID of the student currently taking the content. There is no technical reason why you should need this value unless your content is performing some functionality that is outside the scope of the standards or unless the content displays the student’s id. For cmi5 the value is the account.name
property of the Agent set as the actor
provided by the launching system. For Tin Can the value is the IFI of the Agent provided as the actor
by the launching system, in the case of an account IFI only the name
property will be returned.
GetStudentName()
— Returns the name of the student currently taking the content. Formatted “Last Name, First Name”. For cmi5 and Tin Can the value is determined by the launching system and passed through as the 'actor' query string parameter which is stringified using either the name
property or the IFI of the Agent.
SetBookmark(strBookmark, strDesc)
— Saves a string that represents the user’s current location in the content. This string can be formatted however you choose as long as it is less than 255 ASCII characters. This function should be called periodically as the user progresses through the content. For cmi5 and Tin Can setting a bookmark additionally queues an xAPI Statement to be sent during the next commit.
GetBookmark()
— This function returns the last value that was saved using SetBookmark
. If SetBookmark was not called previously, this function returns an empty string. This function is useful to call at the beginning of the content to retrieve the user’s last location and give him/her the option to return to that location.
SetDataChunk(strData)
— This function allows you to save a string of data up to 4000 characters. This data can represent anything; it is just an arbitrary chunk of data. This function is useful for saving internal state data that does not correspond to any other data element.
GetDataChunk()
— This function returns the last value that was saved using SetDataChunk. If SetDataChunk was not called previously, this function returns an empty string.
GetLaunchData()
— When you package your content in a manifest file, you can optionally include a data string that should be passed to the content upon launch. This data is useful for setting configuration options within the content that are not included below in the Preferences functions. GetLaunchData
will retrieve this data.
WriteComment(strComment)
* — Some LMSs allow the trainee to make comments about the training as he/she is taking it. This function will save a trainee’s comment to the LMS. The total length of all comments cannot exceed 4096 characters. Additionally, the API uses a 3 character delimiter to separate each individual comment.
N.B. This functionality is not supported at all in AICC. The API will return values that you have set using WriteComment during the current session, but values from previous sessions will be lost in an AICC environment. Similarly, it is not supported in Tin Can (although it could be implemented through use of the State API).
GetLMSComments()
* - Some LMSs send comments from the administrator to the trainee. This function will retrieve those comments. Returns an empty string if element is not supported.
Time Tracking
These functions allow you to provide functionality based on the time the user has spent in your training module. The total time spent in training is automatically tracked by the API and saved to the LMS when a Finish function is called. These functions only need to be used if you desire more functionality than just reporting total time spent. All Time Tracking functions represent time in milliseconds.
GetPreviouslyAccumulatedTime()
— Returns the total number of milliseconds spent in training before this session.
GetSessionAccumulatedTime()
— Returns the total number of milliseconds spent in training during this attempt.
SetSessionTime(intMilliseconds)
— Call this function to override the automatic time tracking and reporting with a value of your choosing. This function only needs to be called if you want to record a value other than the actual time spent in training.
PauseTimeTracking()
— Temporarily pauses the automatic time tracking until ResumeTimeTracking
is called. This function is useful if your content implements a pause function and you do not want to report the time spent while the content was paused as time spent in training.
ResumeTimeTracking()
— Resumes automatic time tracking after PauseTimeTracking
has been called. Note that if you use this function without previously calling PauseTimeTracking
the system will treat it as an attempt to start all time tracking from this point on. In other words, you can call this function near the start of the content to begin actual time tracking at a moment other than the initial launch of the content. This functionality could be useful if you only want to record the time spent after any introductory materials have been presented.
GetMaxTimeAllowed()
* — Some LMSs will specify the maximum time a trainee may spend attempting a lesson. This function returns that value in milliseconds. If no timeout value is specified, this function will return 36002439990 which is the maximum amount of time that SCORM can store (equivalent to 9999 hours, 99 minutes and 99.99 seconds).
DisplayMessageOnTimeout()
* — If the LMS specifies a timeout value, it will likely also specify whether or not you should display a message to the user when his or her time has expired. This function returns true
or false
to indicate whether or not to display a message.
ExitOnTimeout()
* — If the LMS specifies a timeout value, it will likely also specify whether or not you should force the user to exit from the content when his or her time has expired. This function returns true
or false
to indicate whether or not to forcibly exit.
Testing
GetPassingScore()
* — Some LMSs allow the content to retrieve the score that is necessary for the student to pass the content. This function returns that score as a number (float) between 0 and 100. If no value is specified, the API returns 0.
SetScore(intScore, intMaxScore, intMinScore)
— Allows you to record the score that the user achieved in the content to the LMS. In addition, you should also specify the minimum and maximum scores that were available. All scores should be numbers (float) between 0 and 100.
GetScore()
— Retrieves a score (float) previously recorded by SetScore
. If no score was previously set, this function returns an empty string.
The following functions record how the learner responded to various question types. Each function accepts the same set of arguments that will be described once below. Note that there are special packaging requirements for using these functions under AICC, see the AICC packaging section for more detail.
strID
— A unique identifier for the question within your content. This value should be a valid URI.response
— The response that the learner gave to the question. Each question type has specific requirements for this value’s format.blnCorrect
— A boolean value that indicates whether or not the answer was correct. This parameter can also accept one of the “interaction result” constants as defined in theAPIConstants.js
file for finer control.correctResponse
(optional) — The correct response to the question. Each question type has specific requirements for this value’s format.strDescription
(optional) — A string describing the interaction (only recorded in SCORM 2004, cmi5, and Tin Can).intWeighting
(optional) — A number that indicates the importance of this question relative to other questions.intLatency
(optional) — The number of milliseconds it took for the user to respond to the question.strLearningObjectiveID
(optional) — The identifier of a learning objective that this interaction is associated with. This identifier could correspond to a value set using the Objectives functions.
ResponseIdentifier
s — Some of the interaction recording functions below can accept ResponseIdentifier
objects as arguments. The purpose of these objects is to allow you to report the most verbose information possible across systems. Some LMS systems have stringent restrictions on the types of response information that can be recorded. These restrictions, while conformant, are often too strict to be practical, for instance only a single letter can be recorded to report the result of a multiple choice question. To accommodate these systems while still providing verbose information to systems that will accept it, you can create a ResponseIdentifier
object which contains both a short and a long version of the result you wish to report. The short version should be a single character that is either a letter or a number. The long version should be a string that is less than 255 characters. A ResponseIdentifier
object can be created by calling the CreateResponseIdentifier(strShort, strLong)
function.
RecordTrueFalseInteraction(strID, blnResponse, blnCorrect, blnCorrectResponse, strDescription, intWeighting, intLatency, strLearningObjectiveID)
* — Records the result of a true/false question. blnResponse
, blnCorrect
, and blnCorrectResponse
must each be a JavaScript Boolean
.
RecordMultipleChoiceInteraction(strID, aryResponse, blnCorrect, aryCorrectResponse, strDescription, intWeighting, intLatency, strLearningObjectiveID)
* — Records the result of a multiple choice question. aryResponse
and aryCorrectResponse
can each be either:
- A single character alphanumeric string representing the response
- A single
ResponseIdentifier
object - An array of
ResponseIdentifier
objects representing multiple selections that must be / were made
RecordFillInInteraction(strID, strResponse, blnCorrect, strCorrectResponse, strDescription, intWeighting, intLatency, strLearningObjectiveID)
* — Records the result of a fill-in question. strResponse
and strCorrectResponse
are both strings, less than 255 characters. In SCORM 2004, LMSs can handle up to 4000 characters.
RecordMatchingInteraction(strID, aryResponse, blnCorrect, aryCorrectResponse, strDescription, intWeighting, intLatency, strLearningObjectiveID)
* — Records the result of a matching question. A matching interaction requires the learner to match items from one set of values with corresponding items in another set of values. The aryResponse
and aryCorrectResponse
values each must contain both a source and a target for the matching. These value are represented in a MatchingResponse
object created with the MatchingResponse
constructor (var x = new MatchingResponse(source, target)
). aryResponse
and aryCorrectResponse
can be either:
- A single
MatchingResponse
object - An array of
MatchingResponse
objects representing multiple selections that were made
RecordPerformanceInteraction(strID, strResponse, blnCorrect, strCorrectResponse, strDescription, intWeighting, intLatency, strLearningObjectiveID)
* — Records the result of a performance question. A performance interaction requires the learner to perform a series of steps. Both strResponse
and strCorrectResponse
are simply represented as a string.
RecordSequencingInteraction(strID, aryResponse, blnCorrect, aryCorrectResponse, strDescription, intWeighting, intLatency, strLearningObjectiveID)
* — Records the result of a sequencing question. A sequencing interaction requires the learner to identify the logical order for members of a list. aryResponse
and aryCorrectResponse
can be either:
- A string representing the response
- A single
ResponseIdentifier
object - An array of
ResponseIdentifier
objects representing multiple steps that must be/were made
RecordLikertInteraction(strID, response, blnCorrect, correctResponse, strDescription, intWeighting, intLatency, strLearningObjectiveID)
* — Records the result of a likert question. A likert question asks the user to select from a discrete set of choices along a scale. These are often used for survey questions such as “Rate your experience on a scale from 1 to 10”. response
and correctResponse
can be either:
- A string representing the response
- A single
ResponseIdentifier
object
RecordNumericInteraction(strID, strResponse, blnCorrect, strCorrectResponse, strDescription, intWeighting, intLatency, strLearningObjectiveID)
* — Records the result of a numeric question. strResponse
and strCorrectResponse
are represented by a single number (which may or may not contain a decimal point).
The following functions retrieve interaction values from the LMS contingent on the content previously reporting those interactions. Put simply, if interactions have been recorded using the prior “Record” functions, those interactions can be retrieved below. It is crucial to note that only SCORM 2004 and cmi5 support the retrieval of interactions. All other standards will return null or empty values.
It is also important to note that each of these methods takes a parameter (strInteractionID
) that specifies the interaction being requested. This is the “long” parameter accepted by the ResponseIdentifier
when setting the interaction data.
In each case, interactions are implemented using a journaling scheme. This means that each interaction is recorded, even if it has the same identifier. But when requesting these items, only the most recent interaction with that identifier is returned.
GetInteractionType(strInteractionID)
* — Returns the type of interaction (as enumerated in APIConstants.js
). Possible values include, true-false, matching, etc.
GetInteractionTimestamp(strInteractionID)
* — Returns a JavaScript date indicating the time of most recent interaction with this identifier.
GetInteractionCorrectResponses(strInteractionID)
* — Returns an array containing each of the correct responses as previously reported by the content. Depending on the type of interaction, this can return a MatchingResponse
or a standard string. It is important to note that this always returns an array even if it is a single response.
GetInteractionWeighting(strInteractionID)
* — Returns the weighting reported by the content for this interaction.
GetInteractionLearnerResponses(strInteractionID)
* — Returns an array containing the learner’s responses as reported previously by the content. Again, this is an array and must be treated as such.
GetInteractionResult(strInteractionID)
* — Returns the “correctness” of the response given by the learner and reported by the content.
GetInteractionLatency(strInteractionID)
* — Returns the latency (in milliseconds) of the learner in responding to the interaction (as reported previously by the content).
GetInteractionDescription(strInteractionID)
* — Returns the description previously provided by the content.
State Functions
These functions allow you to determine the state or status of the content. Possible statuses are described as constants in the APIConstants.js
file.
GetStatus()
— Returns the current status of the content.
SetPassed()
— Sets the current status of the content to passed. If there is a mastery score stored in the LMS (as specified in your content packaging) and if you record a score for the content, then this function does not need to be called; the LMS will automatically compare the score to the mastery score to determine if the content was passed or failed. In cmi5 the comparison to the mastery score will be done in the content, but automatically by Driver. Tin Can has no concept of a mastery score, so to get a stored passed value you must call SetPassed
.
SetFailed()
— Sets the current status of the content to failed. If there is a mastery score stored in the LMS (as specified in your content packaging) and if you record a score for the content, then this function does not need to be called; the LMS will automatically compare the score to the mastery score to determine if the content was passed or failed. In cmi5 the comparison to the mastery score will be done in the content, but automatically by Driver. Tin Can has no concept of a mastery score, so to get a stored failed value you must call SetFailed
.
ResetStatus()
— Resets the status of the content back to incomplete if you previously set it to passed or failed. In cmi5 status can only be reset up until a commit following a completion or passed.
GetEntryMode()
— Determines if the user has previously taken this content. Constants are defined in APIConstants.js
that indicate whether this is the user’s first time in the content, whether the user is resuming a previously paused attempt on this content or whether the user has previously completed the content and is now just reviewing it again.
GetLessonMode()
— Determines the mode in which the user is taking the content. Constants are defined in APIConstants.js
to specify if the user is just browsing the content, is reviewing the content or is making a normal attempt at the content.
GetTakingForCredit()
— Determines if the user is taking the content for credit or if the user is just “auditing” the lesson.
Objectives
Some LMSs allow you to record the results of individual objectives within your content. These objectives are arbitrarily determined by the content author but are intended to reflect the completion of distinct sections of your content. Note that there are special packaging requirements for using these functions under AICC, see the AICC packaging section for more detail. In cmi5 and Tin Can, these are no-ops by default. It would be possible, though, to send xAPI statements for virtually anything.
SetObjectiveStatus(strObjectiveID, Lesson_Status)
* — Allows you to record the current status of an objective within the content. Possible values for Lesson_Status are defined as constants in the APIConstants.js
file and are the same values that may be used for the status of the lesson as whole. Objective ID is a string that uniquely identifies the objective within your content.
GetObjectiveStatus(strObjectiveID)
* — Returns the previously set status of an objective. ObjectiveID is the ID that was passed to SetObjectiveStatus to uniquely identify the objective. If no status was previously set for this ID, this function returns LESSON_STATUS_NOT_ATTEMPTED.
SetObjectiveScore(strObjectiveID, intScore, intMaxScore, intMinScore)
* — Records the score achieved for a particular objective. ObjectiveID is a string that uniquely identifies the objective within the content. Score is the actual score that the trainee earned while MaxScore and MinScore are the best and worst scores respectively that the trainee could have earned. All scores must be numbers (float) between 0 and 100.
GetObjectiveScore(strObjectiveID)
* — Returns the score previously saved for this objective. ObjectiveID
is a string that uniquely identifies the objective within this lesson. If no score was previously set, this function returns an empty string.
SetObjectiveDescription(strObjectiveId, strObjectiveDescription)
* — Allows you to record a textual description of the objective being saved. ObjectiveID
is a string that uniquely identifies the objective within the content. ObjectiveDescription is the text you wish to save. N.B. Objective descriptions are only supported by SCORM 2004.
GetObjectiveDescription(strObjectiveId)
* — Returns the description previously saved for this objective. ObjectiveID
is a string that uniquely identifies the objective within this lesson. If no description was previously set, this function returns an empty string. N.B. Objective descriptions are only supported by SCORM 2004.
SetObjectiveProgressMeasure(strObjectiveId, strObjectiveProgressMeasure)
* — Allows you to record a measure of the progress the learner has made toward completing the SCO. ObjectiveID is a string that uniquely identifies the objective within the content. ObjectiveProgressMeasure
is a string representation of a float indicating the progress you wish to save.
GetObjectiveProgressMeasure(strObjectiveId)
* — Returns the progress measure previously saved for this objective. ObjectiveID
is a string that uniquely identifies the objective within this lesson. If no measure was previously set, this function returns an empty string.
Preferences
SetAudioPreference(PlayPreference, intPercentOfMaxVolume)
* — If your content offers audio content, this allows you to save a setting that determines if the user has selected to have that audio content played. You can also save a setting that represents a relative volume at which the user prefers to hear his/her audio. Use the constants PREFERENCE_ON
and PREFERENCE_OFF
defined in APIConstants.js
to pass to the PlayPreference
parameter. Use an integer between 1-100 to pass to the intPercentOfMaxVolume
parameter (100 is loudest volume, 1 is softest volume).
GetAudioPlayPreference()
* — Retrieves the user’s preferred audio play setting as set by SetAudioPreference
. If PREFERENCE_ON
is returned, the user prefers to hear audio, if PREFERENCE_OFF
is returned, the user does not prefer to hear audio. If PREFERENCE_DEFAULT
is returned, that user will accept whatever the default setting is for your content. (Constants are defined in APIConstants.js
.)
GetAudioVolumePreference()
* — Returns an integer between 1 and 100 that indicates the relative volume at which the listener prefers to hear audio. 1 is the softest, 100 is the loudest. Default is 100.
SetLanguagePreference(strLanguage)
* — Allows you to save a string that indicates which language the trainee prefers to have content delivered in. This string can be in any format that you choose.
GetLanguagePreference()
* — Retrieves the string previously set by SetLanguagePreference
. If SetLanguagePreference
has not been called before, returns an empty string.
SetSpeedPreference(intPercentOfMax)
* — Allows you to save an integer that indicates a relative speed at which the user prefers to experience the content. The integer can be between 1 and 100 with 1 being the slowest and 100 being the fastest. Note that this function is not the same as SetAudioPreference
. This function represents the content as a whole while SetAudioPreference
only represents the audio within the content.
GetSpeedPreference()
* — Returns the integer previously set by SetSpeedPreference
. If SetSpeedPreference
has not been called before, returns 100.
SetTextPreference(intPreference)
* — Allows you to save a setting that determines if the trainee prefers to have a text narration accompanying audio playback. Pass the constants PREFERENCE_ON
or PREFERENCE_OFF
defined in APIConstants.js
.
GetTextPreference()
* — Allows you to retrieve a previous text preference value set using SetTextPreference
. If SetTextPreference
has not been called previously, then PREFERENCE_DEFAULT
is returned.
Shared State
Driver includes support for a standard known as IMS Shared State Persistence (SSP). SSP allows content to save arbitrarily large amounts of data in “buckets”. These buckets of data can be shared across different parts of the course. Unfortunately, support for SSP by LMSs is still quite limited so take care when using these functions to be able to gracefully degrade when support is not available.
DetectSSPSupport()
— Returns true if the current LMS supports SSP, false otherwise. Use this function to check for support before using other SSP functions.
CreateDataBucket(strBucketId, intMinSize, intMaxSize)
* — Before a SSP bucket can be used, it must first be created. strBucketId
is a unique identifier you will use to reference this bucket of data. This identifier must be unique within your course (across all SCOs if using a multi-SCO course). Content must also request a storage allotment. intMinSize
represents the minimum size you will require for this bucket. intMaxSize
represents the maximum size the content could take advantage of. Both size values are represented in characters (i.e. if you need to store a 10,000 character string, send a size request of 10,000 which actually corresponds to 20,000 bytes since JavaScript characters are Unicode). The LMS has the option to grant the max size, the min size or no allotment (N.B. It will always be one of these three values. Nothing in between is allowed). Use the GetBucketInfo
function to determine what allotment the LMS granted this bucket.
GetBucketInfo(strBucketId)
* — Returns an SSPBucketSize
object detailing the total amount of space that was allocated to the specified bucket and the total amount of space currently used in the specified bucket. The SSPBucketSize
object has two properties, TotalSpace
and UsedSpace
, both of which are integers representing a size in characters.
GetDataFromBucket(strBucketId)
* — Returns the data currently stored in a bucket as a string.
PutDataInBucket(strBucketId, strData, blnAppendToEnd)
* — Adds data to an existing bucket. Setting blnAppendToEnd
to true will append the value passed in strData
to the end of the existing data in the bucket. Setting blnAppendToEnd
to false
will replace any existing data with the value stored in strData
.
Packaging Your Content - SCORM
Once you have added functionality to your content using the API functions, it is time to package it up and send it to your customer to be imported into a SCORM / AICC / cmi5 / Tin Can compliant LMS.
Edit the Content’s Manifest
- Open the
imsmanifest.xml
file in a text or XML editor (note that some XML editors will not consider this document to be well-formed). - Scroll down to line number 116 at the end of the document: <!--** FILES **-->
- Every file that is necessary for your content to play must be listed as a new file element here. At the very least, this will include the main page of your content listed in Step 2. This listing may also need to include images, Flash movies, embedded audio or video or any other type of file. A good rule of thumb is that if
CONTENT_DIR
contains all the files needed for the content, then you should list every file inCONTENT_DIR
and in every subdirectory ofCONTENT_DIR
. - To create a new file element, simply copy the current file element and paste it onto the next line: File Element:
<file href="YourContent.html"/>
- Then replace “YourContent.html” with the relative path to the file you wish to add. Repeat this step for every file that is needed for the content.
Edit the Content’s Metadata (optional)
SCORM allows the content author to include some information describing the content he/she is packaging, such as a title, description, etc. Driver includes generic information in each of these fields by default. If you would like to include your specific information, follow the instructions below.
- Open the
imsmanifest.xml
file in a text or XML editor (note that some XML editors will not consider this document to be well-formed). - There are ten data elements that can be customized for your content; each is marked by a series of asterisks surrounding a numeric identifier.
For example:
<!--** 3 **-->
A description of each of these data elements and instructions for customization is located in the Metadata Customization section.
Metadata Customization
1 — Title
SCORM Description — Name given to this resource. The title can be an already existing one or it may be created by the indexer ad hoc.
English Description — The title of your content
To Customize — Replace “Title” with the title of your content. N.B. There are three instances of the Title element. You should replace all three of them.
Max length — 1000 characters
2 — Catalog Entry
SCORM Description - This sub-category defines an entry within a catalog (i.e. a listing identification system) assigned to this resource. It is intended to describe this resource according to some known cataloging system so that it may be externally searched for and located according to the methodology of the specified system.
English Description — This element is used as a way of categorizing your content. The best analogy would be a university that categorizes its classes into departments (catalogs) and class numbers (entries) — History 101 for example. Most content producers will use their company name as the Catalog and an arbitrary identifier for the Entry.
To Customize — Replace “Catalog” with your catalog name and “1” with your entry.
Max length — 1000 characters for each field
3 — Description
SCORM Description — A textual description of the content of this resource being described
English Description — A description of your content
To Customize — Replace “Description” with a description of your content
Max length — 2000 characters
4 — Keywords
SCORM Description — Keywords or phrases describing this resource.
This element should not be used for characteristics that can be described by other elements.
English Description — Keywords that users might use when searching for the content in a repository of many content modules.
To Customize — You can use up to 10 Keyword elements. Copy the entire Keyword block and replace “Training” with your keyword(s). Each block may have more than one keyword if you would like. There is no standard for including more than one keyword in a given block, but many developers will simply separate the keywords with spaces.
Max length — 10 blocks each consisting of 1000 characters
5 — Version
SCORM Description — The edition of this resource
English Description — If you have issued several versions of your content, use this field to distinguish among the versions.
To Customize — Replace “1” with your version number
Max Length — 50 characters
6 — Format
SCORM Description — Technical data type of this resource. This element shall be used to identify the software needed to access the resource. The string is restricted to be either a MIME type or ‘non-digital’.
English Description — If your content uses any applications other than a standard web browser (such as Flash, Windows Media Player, Microsoft Word, etc), then it can include a list of those applications here so that users of the content will know what they need in order to play the content. In most cases, if the application you use is fairly common and easy to install, then adding a format element won’t benefit you all that much, but it can’t hurt.
To Customize — Copy the entire format block and replace “text/html” with the MIME type of your plug-in. A list of common MIME types can be found on the web at http://www.iana.org/assignments/media-types/media-types.xhtml.
Max Length — 500 characters
7 — Cost
SCORM Description — Whether use of the resource requires payment.
English Description — Is the content free or do you want to be paid for it?
To Customize — The default for this element is that there is a cost associated with this content. If you would like to indicate that it is free, replace “yes” with “no”.
Max Length — N/A
8 — Copyright and Other Restrictions
SCORM Description — Whether copyright or other restrictions apply to the use of this resource.
English Description — Is the content copyrighted or is it in the public domain?
To Customize — The default for this element is that the content is copyrighted. To indicate that the content is in the public domain, replace “yes” with “no”.
Max Length — N/A
9 & 10 — Classification
SCORM Description — This category describes where this resource is placed within a particular classification system. To define multiple classifications, there may be multiple instances of this category.
English Description — A classification is basically another way of further categorizing your content. In all but the most advanced cases, you should simply copy the Description (#3) and Keywords (#4) from above into these elements.
Packaging Your Content - AICC
The procedure for packaging AICC content varies depending on the functionality of your content. If your course uses any of the Objectives, then special steps must be taken to properly package the course. We’ll start with a description of packaging a simple course that does not use the objectives functions.
Just like SCORM, AICC has special files that describe the contents of the course package. These files are located in the AICC Descriptor Files directory.
- Rename the descriptor files to something appropriate for your content. The four files in this directory all begin with “yourcourse” followed by a file extension. Only the file extension is important here, change the main file name to be something particular to your course, maybe an id, or an abbreviation of the title. Keep all four file names the same, just leave the four extensions as they are.
- Edit the URL in the .AU file. The first file in the directory is likely the file with the “.AU” extension. Open this file in a text editor such as Notepad. In the middle of the second line, you will see this text: "http://www.FillInYourDomainHere.com/courses/indexAPI.html"
- This URL needs to be changed to the launching URL of the course once it is installed on the client’s system. The first sections of the URL will vary based on where the content is installed on the web server, however you should always link to the
indexAPI.html
page. One of the major difficulties with the AICC standard is that this file needs to be changed for every client delivery and you will not always know ahead of time what the proper launch URL is going to be. Clients with AICC compatible LMSs are used to this dilemma and are often accustomed to changing this file themselves. - Open the .CRS file in a text editor and change the “Course_Creator”, “Course_Title” and “[Course_Description]” fields. To do this, replace the word “Company” on the second line of the file with your company name; replace the word “Title” on the fifth line of the file with the title of your course; and replace the word “Description” on the final line of the file with a description of your course.
- Open the .DES file in a text editor and change the “Title” and “Description” fields. To do this, replace the word “Title” on the second line of the file with the title of your content and replace the word “Description” on the second line of the file with a description of your content.
- Packaging for Interactions — Note that if you use any of the functions to record interactions, it is important that the
developer_id
field of the .DES file match the value of theAICC_LESSON_ID
setting in theConfiguration.js
file. By default, these values are both set to “1”, so no action should be necessary unless you make a specific change. - Packaging for Objectives — When objectives are used, additional lines must be added to the .DES file that describe the objectives. Each line in the .DES file describes an element of the course. Currently, there are two lines, a header and then one line that describes the course. When using objectives, you need to add one additional line for each objective on which you are reporting data. There are four fields of data that need to be entered:
system_id
,developer_id
,title
, anddescription
. Thesystem_id
is a sequential identifier for the element within the course, each type of element has an associated prefix. For example, the existing element represents the first “assignable unit” with the course, so itssystem_id
is “A1”. If there were more assignable units, they would have thesystem_id
s “A2”, “A3”, etc. The prefix for an objective is the letter “J”, so when you add your list of objectives, thesystem_id
s should be “J1”, J2”, J3”, etc. The next field is thedeveloper_id
field. This field represents a unique id that you will use to identify the element within the course. This id must match the id that you pass to the objectives functions when recording data. The title and description fields describe the objective in a human readable form. A .DES file for a course with three objectives might look like this:
"system_id","developer_id","title","description"
"A1","1","Baseball 101","This course will teach you how to play baseball."
"J1", "obj1", "Hitting", "Demonstrates the fundamentals of hitting."
"J2", "obj2", "Pitching", "Objective teaches various pitching techniques."
"J3", "obj3", "Fielding", "Communicates the importance of proper positioning.”
Packaging Your Content - cmi5
Driver comes with a sample cmi5.xml
Course Structure file that is set up for single AU usage. More complicated Course Structure files are possible, and Driver resources could even be shared amongst Assignable Units (AUs) within a single file but that is beyond the scope of this document. If you would like assistance with creating more complex course structures using Driver please contact support@scorm.com.
Edit the Course Structure (cmi5.xml
)
Open the file in your text editor and change the following:
- --CourseId--: Globally unique identifier for the course, an IRI, it is the identifier of the
object
of the Satisfied xAPI statement recorded for satisfying the course requirements. - --CourseTitle--: Title of the course as a whole. Multiple
<langstring>
elements may be included allowing for multiple translations, each must include alang
attribute specifying the language code for that translation. - --CourseDescription--: Description of the course as a whole. Multiple translations are allowed as with title.
- --AUId--: Globally unique identifier for the AU, an IRI, it is the identifier of an xAPI Activity included in the
context.contextActivities.grouping
list of the "cmi5 defined" xAPI statements recorded both by the LMS and by Driver for the AU session. - --AUTitle--: Title of the Assignable Unit. Multiple translations are allowed as with course title.
- --AUDescription--: Description of the Assignable Unit. Multiple translations are allowed as with course description.
For more specifics about including launchParameters
, masteryScore
, or other AU metadata please see the cmi5 specification or contact support@scorm.com.
Packaging Your Content - Tin Can
After you’ve downloaded Driver with Tin Can API support, you’ll need to modify two files that are found in the root directory of the download.
tincan.xml
The first is “tincan.xml”. Open the file in your text editor, and change the following lines:
Here’s what to modify in tincan.xml
:
- ActivityID: Globally unique identifier for the package, an IRI, it is provided to the content in the launch URL as a query parameter and is usually the identifier of the
object
of xAPI statements sent to the LRS by the content. - ActivityName: Replace this with the title of your course or activity.
- ActivityDesc: Replace this with a very brief description of your activity.
tc-config.js
The other file you need to modify for Tin Can use is tc-config.js
, also found in the root directory of your download. Here’s what to modify in tc-config.js
(it’s largely similar to how you updated tincan.xml
):
- ActivityID: Globally unique identifier for the package, an IRI, it is provided to the content in the launch URL as a query parameter and is usually the identifier of the
object
of xAPI statements sent to the LRS by the content. - ActivityName: Replace this with the title of your course or activity.
- ActivityDesc: Replace this with a very brief description of your activity.
To Use the Converted Content
- To configure the content to use the proper LMS standard, simply open the
Configuration.js
file and change the “strLMSStandard” variable (details are available in the comments within the file). Most clients will be able to tell you which standard is required, however you can have the content automatically determine which standard to use by setting this value to “AUTO”. - To send the content to a customer, simply send a copy of all the files in CONTENT_DIR. Alternatively, you can package all of these files into a ZIP file and send just the one file (be sure that the
imsmanifest.xml
,cmi5.xml
, ortincan.xml
file is located at the root of the ZIP file). - To import the content into a SCORM compliant LMS, simply use the LMSs import mechanism to select the
imsmanifest.xml
file located in CONTENT_DIR. - To view the content outside of a SCORM compliant LMS, simply copy CONTENT_DIR to a web published directory. Point your browser to
http://yourserver/content_directory/indexAPI.html?StandAlone=true
and the content should play. The querystring parameterStandAlone=true
replaces the SCORM / AICC / cmi5 / Tin Can integration functions with dummy functions that replicate an LMSs behavior. - Be sure to test your content at Cloud [https://cloud.scorm.com], our hosted training delivery platform (where you can set up a free trial account). It will be more forgiving than some LMS's, but it's a great place to get started.
Other Notes
A Few Notes on Well-Behaved SCORM Content
- Avoid having your content reference other windows outside of the content, especially “_top”. Similarly, avoid trying to close the current window. SCORM compliant LMSs are free to launch content in whatever manner they choose. Quite often this means that content is launched in a frameset and referencing the “_top” window or trying to close the current window may result in an error. Also, do not make any assumptions about the size of the window your content will be launched in. Calling the ConcedeControl function with the SCORM_RECOMMENDED exit behavior setting is the best way to exit a course. Some LMSs require specific behaviors on exit, in these situations, you may have to change the exit behavior setting in the
Configuration.js
file. - Be sure to close any windows that you open before exiting the content. The
onunload
event is useful to ensure that all child windows are closed before the content is exited. - Try to space calls to the API evenly throughout the content and avoid bunching a lot of calls at the end of the content (especially in the last
onunload
event). Many LMSs require a round-trip between the client and server every time a value is saved to the LMS. Many calls grouped together may take a while to execute and may not all get processed when invoked from anonunload
event. Especially when using the AICC standard, try to call the CommitData function well before the content is unloaded. - Be sure to list ALL necessary files in the SCORM manifest. Some LMSs only make available the files that you list regardless of what exists in your content directory.
- Avoid using any server-side code in your content. SCORM content is meant to be packaged and physically transferred to any LMS. Since different LMSs run on different platforms, you cannot count on a particular server-side technology being available when your content is distributed. All dynamic content should be either generated on the client-side or re-written as static HTML. Please contact us for help with this transition.
The Cross Domain Scripting Problem
As a workaround to not knowing what technologies are available on a remote LMS, many content vendors want to host SCORM compliant content on their own servers to preserve access to server-side scripting. While this is technically possible, it is very difficult to make work properly.
The problem you run into is called the “Cross Domain Scripting Problem” or “3-Node Problem”. Essentially when two HTML pages are loaded in a frameset (or parent/child browser windows), script in one frame can only reference script in the other frame if the two frames originated from the same domain (due to browser security restrictions). Since SCORM relies on cross-frame/window scripting for communication with the API, content served from one server will not be able to communicate with an LMS served from a different server.
There are several workarounds to this problem, most of which are complex to administer. One option is to trick the browser into thinking that the content and LMS are actually coming from the same domain by modifying the DNS entries on both servers. Another option involves putting a portion of the LMS or a portion of the content on the other server and writing a non-standards-based communication interface. Please contact us if you would like help developing a 3-node solution.
When deploying content as AICC you have more options for circumventing the problem. One option includes running a server-side page on the content server that relays information to and from the LMS server. An example of this solution is included in the AICC Relay directory. Another solution is to fall back on a write-only mode in which data is saved to the LMS, but data cannot be read back from the LMS. Driver will automatically fallback to a write-only mode if it is deployed in an AICC cross domain environment.
Why Doesn’t the XML Validate in My Parser
The SCORM manifest file was developed using the latest version of the W3C Specification which many XML parsers do not yet support. More information can be found at http://www.w3.org/.