API Documentation

Using the API

To get started:

  1. 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.
  2. Take all of the files that comprise your course, and drop them in the scormcontent folder. If your copy of Driver doesn’t have a scormcontent 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 the scormcontent folder, you should drop your actual HTML and content files into the scormcontent folder.
  3. In your Driver folder, you should have a scormdriver folder containing indexAPI.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".
  4. 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 the Finish function for more information. N.B. you should only call functions listed in the Function List. These functions are present in the API.js file; calling other functions outside of this list is not recommended.
  5. 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.
  6. 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.

ResponseIdentifiers — 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:

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:

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:

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:

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

  1. 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).
  2. Scroll down to line number 116 at the end of the document: <!--** FILES **-->
  3. 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 in CONTENT_DIR and in every subdirectory of CONTENT_DIR.
  4. To create a new file element, simply copy the current file element and paste it onto the next line: File Element: &lt;file href=&quot;YourContent.html&quot;/&gt;
  5. 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.

  1. 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).
  2. 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

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.

  1. 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.
  2. 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"
  3. 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.
  4. 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.
  5. 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.
  6. 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 the AICC_LESSON_ID setting in the Configuration.js file. By default, these values are both set to “1”, so no action should be necessary unless you make a specific change.
  7. 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, and description. The system_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 its system_id is “A1”. If there were more assignable units, they would have the system_ids “A2”, “A3”, etc. The prefix for an objective is the letter “J”, so when you add your list of objectives, the system_ids should be “J1”, J2”, J3”, etc. The next field is the developer_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:

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:

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):

To Use the Converted Content

Other Notes

A Few Notes on Well-Behaved SCORM Content

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/.