Overview
Publishing with the SCORM 1.2 Template
Sequence of Operation
Differences from Previous Templates
Calling Template Functions from Actionscript
FS SCORM Sample Files
Command Reference
Core SCORM API Commands
Other Commands
Tips and Cautions
Avoid fscommands in Frame 1
Suspend Data
Customizing the Template
Credits
The 2003 SCORM 1.2 HTML Publishing Template for Flash MX is a replacement for the original fsSCORM template last updated in 2001. You specify this template as the publishing template to use in the Macromedia Flash authoring environment. The result is a .swf Flash movie file that when combined with HTML page, constitutes a SCORM conformant "shareable content object". The main difference with the previous version of the template is that most of the logic of finding and communicating with the LMS is embedded in the HTML file, so that you can focus your ActionScript on the interactive aspects of your movie without having to worry about the underlying housekeeping. The template is compatible with the Flash sample quiz movie template, as well as with earlier standard Flash Learning Components. In many cases, you can take a Flash movie that includes AICC compatible Learning Components, republish it with the HTML template, and it becomes SCORM conformant with no modifications to the .fla file or modification of the ActionScript.
To use the SCORM 1.2 Template, select File > Publish Settings... to access the Publish Settings Dialog. Select the HTML tab and choose the Template "SCORM 1.2 Template", as indicated in the figure below.
In addition to using the template when your movie is published, your movie itself will need to include callbacks to API methods using fscommands. The SCORM specification requires run time compliant content to:
See the ADL web site for more information and the most recent version of the SCORM specification. The FS SCORM sample movie named fsSCORM.fla, demonstrates how Flash movies can use fscommands to call back to API methods. The sections below explain more about the sample movie.
Before the runtime service of a Learning Management System (LMS) launches a shareable content object (SCO), it instantiates an API object that the SCO is expected to discover.
Launching the SCO means launching the HTML file created when you published the movie. This HTML file acts as a "wrapper" that contains the player object within which the movie itself will be loaded.
After the SCO has been loaded, its script searches for the API object provided by the runtime service. If such an API object cannot be found, the SCO gives up on trying to communicate.
If the API object can be found, the SCO initiates a communication session with the API object. This session continues until the SCO is unloaded, at which point it automatically closes the session. The session can also be closed earlier by the Flash movie.
The Flash movie is blissfully unaware of all this. All it has to do is call the scripts in the template with tracking data it wants to communicate to the runtime service. It can also call a function in the template to get a mandatory CMI data model value, such as "cmi.core.student_name", to establish whether the communication session with a SCORM conformant runtime service has been established successfully.
After the communication session is established, the first thing the template does is check the status of the SCO. If it was "not attempted", it changes it to "incomplete". The movie can then call the template at any time if it determines that the status should change to "completed". Optionally, you can edit one constant in the HTML file to make the template set the status to "completed" automatically just because the SCO was used.
The template scripts then wait for fscommands from ActionScript to communicate with the runtime service. This can take various forms, and the template scripts fix the data as necessary to meet the SCORM requirements. For example, if the data passed by a fscommand are in the old AICC format, a template script reshapes the data as SCORM CMI data and passes it on. If enough information is available, score values are also reshaped to fit the SCORM normalized score range of 0..100. If mastery score information is available from the runtime service, the score data from the movie can be used to automatically set the status to "passed" or "failed".
The previous SCORM template depended on having your movie call the LMSInitialize and LMSFinish functions to start and finish the communication session, and then manage the state of the session. This template takes care of this for you. For example, it guarantees that LMSFinish will be called properly even if the HTML page is unloaded before the movie reaches the last frame.
The previous SCORM template also depended on having your movie keep track of counters to set objectives and interaction data. With this HTML template you can simply set data by specifying the identifier for the objective or interaction, and the HTML script provides the correct index required to communicate the data in the CMI data model. This means, for example, that if your movie logic allows a user to skip certain frames that contain ActionScript to send objective status changes or question results, you don't have to worry about keeping track of an index counter. Just send the data with a unique identifier for each objective or question, in any order. However, the identifier is required for this to work.
The template functions are called by ActionScript fscommands. If the fscommand must return a value to ActionScript, the variable to hold the return value must be specified as a parameter of the fscommand. Also, a fscommand that should return a value can only be executed in the main time line of your movie.
The FS SCORM extension will copy the Flash sample file fsSCORM.fla to the "Flash MX/Samples" folder. If you have less than 24 sample files in that folder, the sample will also be available from the Flash menu, Help>Sample>fsSCORM.
In the sample file, the Actions for the scene "Intro Page" in the "Code" layer, frame 1 show how commands like API.LMSGetValue are called from ActionScript using fscommands. See below for an example as shown in the Flash authoring tool.
The sample directory also includes fsSCORM-PIF.zip which is a sample SCORM 1.2 compatible content aggregation package complete with a manifest. The content aggregation package can be used to import the sample file into your LMS and test the SCORM movie your browser and LMS configuration.
Description: Sets the value of a data element communicated to the SCORM runtime service.
Argument: "cmi.data.element, value"
Return: None (error posted in JavaScript alert)
ActionScript Example: FSCommand("LMSSetValue","cmi.core.lesson_status,completed");
Description: Gets the value of a data element from the SCORM runtime service.
Argument: "cmi.data.element, myVariable"
Return: Result put into Flash 'myVariable' store.
ActionScript Example: FSCommand("LMSGetValue","cmi.core.student_name,name");
The example places the student name into the Flash variable myVariable.
Description: Gets the numeric code of the last error status recorded by the runtime service.
Argument: "nil,myVariable"
Return: Result put into Flash 'myVariable' store.
ActionScript Example: FSCommand("LMSGetLastError","nil,err");
The example places the error string into the Flash variable myVariable.
Description: Gets a human readable string version of an error code.
Argument: "value,myVariable"
ActionScript Example: FSCommand"LMSGetErrorString","101,errString");
Return: Result put into Flash 'myVariable' store.
The example places the error string into the Flash variable myVariable.
Description: Gets implementation-specific diagnostic information from the runtime service.
Argument: "value,myVariable"
ActionScript Example: FSCommand("LMSGetDiagnostic","101,errString");
Return: Result put into Flash 'myVariable' store.
The example places the error string into the Flash variable myVariable.
Description: Asks the runtime service to commit any cached data to persistent storage.
Argument: ""
Return: None (error posted in JavaScript alert)
ActionScript Example: FSCommand("LMSCommit,"");
Description: Sets the value of cmi.core.lesson_status to "completed"
Return: None.
ActionScript Example: FSCommand("CMISetCompleted,"");
Description: Sets the value of cmi.core.suspend_data to the specified value. This value can be any string up to 4095 characters long. A LMS does not normally interpret this value in any way, but it can persist between sessions if cmi.core.exit is set to "suspend".
Argument: A string.
Return: None.
ActionScript Example: FSCommand("CMISetData","78,45,567,890,foo,bar,baz,x");
Description: Sets the value of cmi.core.lesson_status to "failed"
Return: None.
ActionScript Example: FSCommand("CMISetFailed","");
Description: Sets the value of cmi.core.location to the specified value. This value can be any string up to 255 characters long. A LMS does not normally interpret this value in any way, but it can persist between sessions if cmi.core.exit is set to "suspend".
Argument: A string.
Return: None.
ActionScript Example: FSCommand("CMISetLocation","5-1-xyz");
Description: Sets the value of cmi.core.lesson_status to "passed"
Return: None.
ActionScript Example: FSCommand("CMISetPassed","");
Description: Sets the value of cmi.core.score.raw to the specified value. For compatibility with SCORM 1.2 and to ensure proper reporting of results, this score should be a normalized value in the range of 0..100. If the value is not within this range it will not be recorded. If it is within that range but the scoring scale is not 0..100 the value will be recorded, but reported improperly by a SCORM 1.2 compliant LMS.
Argument: A raw score value (integer or floating point)
Return: None.
ActionScript Example: FSCommand("CMISetScore","78");
Description: Sets the value of cmi.core.lesson_status to "incomplete"
Return: None.
ActionScript Example: FSCommand("CMISetStarted,"");
Description: Handles a Macromedia Learning Components Fscommand that uses the AICC data model, and translates it to SCORM LMSSetValue calls to the runtime service.
Argument: A legal value for status, one of "not attempted", "incomplete", "completed", "passed", "failed", "browsed".
Return: None.
ActionScript Example: FSCommand("MM_cmiSetLessonStatus,"completed");
Description: Sets the value of cmi.core.session_time to the specified value.
Argument: A time string (see SCORM specification for proper format)
Return: None.
ActionScript Example: FSCommand("CMISetTime","00:12:02");
Description: Sets the value of cmi.core.exit to "timed-out".
Argument: ""
Return: None.
ActionScript Example: FSCommand("CMISetLocation","");
Description: Terminates the communication with the runtime service. Once terminated, session cannot be restarted without reloading the SCO. Not required because LMSFinish is handled automatically by this publishing template, but included for compatibility with certain older movies.
Argument: ""
Return: None (error posted in JavaScript alert)
ActionScript Example: FSCommand("LMSFinish","");
Description: Initialize the communication session. Actually, does nothing because LMSInitialize is handled automatically by this publishing template, but included for compatibility with certain older movies.
Argument: ""
Return: None (error posted in JavaScript alert)
ActionScript Example: FSCommand("LMSInitialize","");
Note: Not required
Description: Handles a Macromedia Learning Components Fscommand that uses the AICC data model, and translates it to SCORM LMSSetValue calls to the runtime service.
Argument: F_intData
Return: None.
ActionScript Example: FSCommand("MM_cmiSendInteractionInfo","");
Description: Handles a Macromedia Learning Components Fscommand that uses the AICC data model, and translates it to SCORM LMSSetValue calls to the runtime service.
Argument: F_objData
Return: None.
ActionScript Example: FSCommand("MM_cmiSendObjectiveInfo","");
Description: Calls the API function (any name) with any argument passed.
Argument: Any string.
Return: If a variable name for a return value is specified, returns the result of the call. If the function called does not exist, returns "undefined" as the result.
ActionScript Example: FSCommand("AcmeExtFunction","StockPrice,myStockPrice");
You should avoid using fscommands in frame 1 of your movie. When frame 1 is being played the Flash player fscommand engine may not be fully initialized yet. The solution is to let frame 1 play through to frame 2 and put your initial fscommands there.
If you want to be able to resume your movie at a given place if the SCO execution is suspended, then resumed later, you must set the value of cmi.core.exit to "suspend". You can set this at any time, even just after starting the movie (note the caution about frame 1, above). Then you must save a value you can use in a later session, typically in cmi.core.suspend_data. The value can be any string, and only you can interpret it.
When the SCO is relaunched, the value of cmi.core.entry will be "resume" if the previous session was suspended. You can then get the value of cmi.core.suspend_data and use it to restore the state you want. For example, you may have stored the last played frame, and resume playback from that point. Or you may use cmi.core.suspend_data to store the state information necessary to restore variables or interaction objects.
You can also use cmi.core.location instead of cmi.core.suspend_data if all you want to store is a location. For example, if you set cmi.core.exit to "suspend" initially, and then set cmi.core.location to the frame number each time you start playing a significant frame, you should be able to retrieve the frame number value by checking cmi.core.location later if the SCO is resumed. The value of cmi.core.location is meaningful only to you. The LMS or runtime service does not interpret it in any way.
A few elements of the HTML template can be customized to meet your needs. It is recommended that you edit the HTML file created by the Flash publishing process, rather than the original template. If you must modify the original template, change its name (on the first line) and description to avoid confusion.
You can modify the following pseudo-constants in the template to get the desired behavior.
|
Variable |
Description |
Default value |
|
g_bShowApiErrors |
If true, show error messages for errors involving the API |
true |
|
g_bSetCompletedAutomatically |
Change to true if you want the status to be set to completed automatically when calling LMSFinish. Normally, this flag remains false if the Flash movie itself sets status to completed by sending a FSCommand to set status to "completed", "passed" or "failed" (both of which imply "completed") |
false |
|
g_bAutoPlayOnceLoaded |
Change this flag below to true if the movie is published with "Paused at Start" checked in Publish Settings, but you want it to start playing automatically after it is fully loaded. This may increase the reliability of the fscommand interface, but note that the safest way to increase reliability is to defer any serious scripting to after frame 1 in your movie, because the Flash player may not be entirely stable while it plays frame 1. |
false |
|
g_SCO_MasteryScore |
The mastery score value is normally given by the LMS, but, in case it is not, this is the default value to use to determine passed/failed, according to the score reported by the movie. Set this to null if the movie's ActionScript uses its own method to determine passed/fail, otherwise set this to a value from 0 to 1 inclusive (may be a floating point value, e.g."0.75"). Note that whatever you define here, the LMS decides in the end. Allowable values: 0.0..1.0, or null |
1.0 |
In addition, you may want to translate the following strings if g_bShowApiErrors is true and you need to localize the application:
g_strAPINotFound = "Management system interface not found.";
g_strAPITooDeep = "Cannot find API - too deeply nested.";
g_strAPIInitFailed = "Found API but LMSInitialize failed.";
g_strAPISetError = "Trying to set value but API not available.";
g_strFSAPIError = 'LMS API adapter returned error code: "%1"\nWhen FScommand called API.%2\nwith "%3"';
g_strDisableErrorMsgs = "Select cancel to disable future warnings.";
Tom King
Lenny Greenberg
Claude Ostyn