SCORM “Planets” Example Updated

Update 10/13/2011: I added more comments to the ActionScript code to help explain what each line of code does. I also added a Flash CS4 version of the FLA to the ZIP so more people can access the example.

My “Planets” example (How to Add Basic SCORM Code to a Flash Movie) has proven to be one of the most popular items on pipwerks.com. Unfortunately, it was designed as a quick example and had a bunch of flaws and shortcomings. It’s also about 3 years old and starting to show its age. Since people frequently contact me with questions — many of which were due to the flaws in the example — I decided to update the project.

The new Planets example has a bunch of fixes:

  • Full compliance with SCORM XSD requirements (it includes all those pesky XSD files that really don’t do anything but are required anyway).
  • Upgraded the pipwerks JavaScript wrapper to the latest version
  • Upgraded the pipwerks ActionScript 3 wrapper to the latest version
  • Upgraded SWFObject from 1.5 to 2.2
  • Changed the doctype and markup to HTML5
  • Added an unload handler to the JavaScript to ensure course progress is saved if the learner exits early
  • Added support for tracking progress across attempts using cmi.suspend_data
  • Completely rebuilt the FLA file to remove all timeline-based animation and scripts. Now uses a single ActionScript file, loaded on a single frame. All animations (fade transitions) are handled via ActionScript. This makes the file smaller and hopefully less confusing.
  • The SCORM code is clearly separated from the rest of the movie’s ActionScript; it’s in the same file, but not intermingled with other functions.

I haven’t decided if I’ll create a detailed tutorial to explain the updates; I’ve added a ton of comments to the ActionScript file, and hope it’s clear enough for others to follow.

Download the updated Planets example
The ZIP includes two FLA files: one in CS4 format, and the other in CS5.5. The code, movieclips, and graphic elements inside the FLAs are exactly the same.

Advertisements

Abstracting Your Course’s Tracking Code

An abstraction layer is a way of hiding complexities and maintaining cleanliness in your application. For example, if you want to save a file in your word processing application, you simply click “save”, while a whole host of actions is performed for you under-the-hood. In this example, you’re shielded from the complexity of your computer’s I/O operations by a graphical user interface.

When integrating tracking support (SCORM, AICC, etc,) into an an e-learning course, it’s a good idea to abstract as much of the tracking code as possible. For example, if you know your course is going to use SCORM 1.2, you might be tempted to write this:


//Assuming API is the SCORM API

//Display learner's name
var learner_name = API.LMSGetValue("cmi.core.student_name");

//Set course status to incomplete
API.LMSSetValue("cmi.core.lesson_status", "incomplete");

//Tell LMS to save whatever data we've sent
API.LMSCommit("");

This example hard-codes SCORM 1.2 into your course. If you ever decide to use SCORM 2004, you’d need to re-write whole chunks of your course. If you abstract the code by creating functions, you’re making it a little easier to update your code in the future:


//Assuming API is the SCORM API

function getLearnerName(){
   return API.LMSGetValue("cmi.core.student_name");
}

function setLessonIncomplete(){
   API.LMSSetValue("cmi.core.lesson_status", "incomplete");
}

function save(){
   API.LMSCommit("");
}

//Display learner's name
var learner_name = getLearnerName();

//Set course status to incomplete
setLessonIncomplete();

//Tell LMS to save whatever data we've sent
save();

Now that your tracking code is encapsulated in functions, it can be easily modified to include SCORM 2004 support:


//Assuming API is the SCORM API
//Checks for SCORM2004 mode, defaults to SCORM 1.2

function getLearnerName(){
   if(tracking_mode === "SCORM2004"){
      return API.GetValue("cmi.learner_name");
   }
   return API.LMSGetValue("cmi.core.student_name");
}

function setLessonIncomplete(){
   if(tracking_mode === "SCORM2004"){
      API.SetValue("cmi.completion_status", "incomplete");
   } else {
      API.LMSSetValue("cmi.core.lesson_status", "incomplete");
   }
}

function save(){
   if(tracking_mode === "SCORM2004"){
      API.Commit("");
   } else {
      API.LMSCommit("");
   }
}


//Set tracking mode
var tracking_mode = "SCORM2004";

//Display learner's name
var learner_name = getLearnerName();

//Set course status to incomplete
setLessonIncomplete();

//Tell LMS to save whatever data we've sent
save();

For e-learning courses, abstraction becomes even more powerful if you externalize your tracking-related functions. For example, you’d keep your tracking function invocations in your course code while placing the function definitions in a separate, easy-to-access file. This improves the separation of the tracking mechanism (SCORM, AICC, etc.) from the actual course logic.

Your course code:


//Set tracking mode
var tracking_mode = "SCORM2004";

//Display learner's name
var learner_name = getLearnerName();

//Set course status to incomplete
setLessonIncomplete();

//Tell LMS to save whatever data we've sent
save();

An external JavaScript file containing the function definitions:


//Assuming API is the SCORM API
//Checks for SCORM2004 mode, defaults to SCORM 1.2

function getLearnerName(){
   if(tracking_mode === "SCORM2004"){
      return API.GetValue("cmi.learner_name");
   }
   return API.LMSGetValue("cmi.core.student_name");
}

function setLessonIncomplete(){
   if(tracking_mode === "SCORM2004"){
      API.SetValue("cmi.completion_status", "incomplete");
   } else {
      API.LMSSetValue("cmi.core.lesson_status", "incomplete");
   }
}

function save(){
   if(tracking_mode === "SCORM2004"){
      API.Commit("");
   } else {
      API.LMSCommit("");
   }
}

Looking good, except for one thing… do you spot the big problem with this example? The tracking_mode variable is hard-coded in the course. A quick resolution is to dynamically set this variable via a querystring parameter when you load the course:


//Set tracking mode
//This is a quick and dirty example;
//there are better ways to handle querystrings
//Example: mycourse.html?tracking=SCORM2004
var tracking_mode = window.location.href.split("?tracking=")[1];

//Display learner's name
var learner_name = getLearnerName();

//Set course status to incomplete
setLessonIncomplete();

//Tell LMS to save whatever data we've sent
save();

At this point, your course code is abstracted enough that it would be (relatively) trivial to add AICC support by modifying your tracking functions.

As you can see, the further we abstract, the cleaner your course’s code becomes. If you’re a Flash developer, use an additional level of abstraction — place your tracking functions in JavaScript and invoke them via ExternalInterface. While it may add a little up-front work, it will enable you to easily update your tracking code without needing to republish your FLAs.

Your course’s JavaScript:


//Assuming API is the SCORM API
//Checks for SCORM2004 mode, defaults to SCORM 1.2

//Set tracking mode
//This is a quick and dirty example;
//there are better ways to handle querystrings
//Example: mycourse.html?tracking=SCORM2004
var tracking_mode = window.location.href.split("?tracking=")[1];

function getLearnerName(){
   if(tracking_mode === "SCORM2004"){
      return API.GetValue("cmi.learner_name");
   }
   return API.LMSGetValue("cmi.core.student_name");
}

function setLessonIncomplete(){
   if(tracking_mode === "SCORM2004"){
      API.SetValue("cmi.completion_status", "incomplete");
   } else {
      API.LMSSetValue("cmi.core.lesson_status", "incomplete");
   }
}

function save(){
   if(tracking_mode === "SCORM2004"){
      API.Commit("");
   } else {
      API.LMSCommit("");
   }
}

Your course’s FLA:


//Display learner's name
var learner_name:String = getLearnerName();

//Set course status to incomplete
setLessonIncomplete();

//Tell LMS to save whatever data we've sent
save();

And here’s the glue: an abstraction layer meant to bridge the course FLA and the JavaScript tracking. Save as an external AS file (or a class/package if you’re feeling adventurous).


import flash.external.*;

function getLearnerName():String {
   return ExternalInterface.call("getLearnerName");
}

function setLessonIncomplete():void {
   ExternalInterface.call("setLessonIncomplete");
}

function save(){
   ExternalInterface.call("save");
}

In this example the tracking mode is set via JavaScript, and all of the tracking functionality is handled via JavaScript. If you ever needed to change from SCORM 1.2 to SCORM 2004 or AICC, you could handle it all via your JavaScript file and leave your Flash untouched. Easy breezy.

These are very simple examples, but hopefully they show the power of abstraction. Notice the last two examples have zero mention of SCORM in the course code itself. Sweet!

Of course, there is a downside to everything. As I mentioned in a thread on the E-Learning Technology and Development Google Group, abstracting like this takes time and can add quite a bit of work to your course development plan. If you know your course is a one-off that will only ever use one tracking method (such as SCORM 1.2), abstraction layers may be more effort than they’re worth. But if you’re not in a hurry, or know that your course will be around for a long time and will run on multiple LMSs, abstraction is a very good idea.

Abstraction and the pipwerks SCORM API Wrappers

What about the pipwerks SCORM API Wrappers? Well, they use some abstraction, but are not as abstracted as these examples. They can certainly help you on your way, but would need a bit of tweaking to reach this level of abstraction. I’m currently working on new SCORM wrappers that aim to support this level of abstraction. Stay tuned.

pipwerks SCORM Wrappers now available on GitHub

I’ve been considering adding my pipwerks SCORM wrappers to GitHub for a very long time, but my n00bness and general lack of free time were major obstacles. However, the time has finally come to buckle down and get these puppies OUT! So without further ado, I present:

https://github.com/pipwerks/scorm-api-wrapper

I should note that these are my original SCORM wrappers (JavaScript, ActionScript 2 and ActionScript 3); I’ve been (very slowly) working on a completely new SCORM support codebase that I plan to release separately. However, these oldies are still running like a champ, so don’t be afraid to use them.

Many people have contacted me over the last few years with suggestions for improvements, but due to my general busy-ness I haven’t really made any modifications for a long time; I recently made a few small tweaks, including updating the StringToBoolean function that caused problems in Plateau, but the bulk of the code remains largely the same.

If you’re one of those die-hards eager to tweak the source code, you’re in luck! This is a public repository, which means anyone and everyone is now free to fork and edit the code as they see fit. If you have any suggestions or ideas, please go to GitHub and show us what ya got!

And for the curious, I’m using Tower to handle my Git commits — command lines are not my cup of tea. Tower is a very nice Git GUI that integrates seamlessly with GitHub. I’m new to Tower, but so far I like it very much.

SCORM Tip: Use an onunload handler

SCORM courses use JavaScript to send data to the LMS. This data then sits in the browser until the LMS writes it to the database (usually via AJAX or form posts). As previously discussed, invoking commit (save) will ensure the LMS actually writes this data to a database.

But what happens if the browser window containing your course is closed by the learner before the course finishes sending data to the LMS? If you’re not careful about how you’ve coded your course, you can lose some of the data. For example, if a learner completes the course and then immediately closes the window, the course might not have had enough time to tell the LMS about the completion, preventing the completion from appearing in the learner’s record.

It’s best to be proactive about this by setting up an event handler for the browser’s unload and onbeforeunload events. Whatever code you place in these events will execute when the browser is closed. In a SCORM course, you should place a commit (save) and terminate (quit) command in these events to ensure the SCORM data is properly persisted in the database and the session is properly terminated.

The code is pretty straightforward (this example uses SCORM 2004):


//Assuming API refers to your SCORM API
//and API_isActive returns a boolean indicating
//whether your API has already been terminated

var unloaded = false;
function unloadHandler(){
   if(!unloaded && API_isActive){
      API.SetValue("cmi.exit", "suspend"); //Set exit to whatever is needed
      API.Commit(""); //save all data that has already been sent
      API.Terminate(""); //close the SCORM API connection properly
      unloaded = true;
   }
}
window.onbeforeunload = unloadHandler;
window.onunload = unloadHandler;

Since some browsers support onbeforeunload and others don’t, we use the unloadHandler on both onbeforeunload and onunload, just to be safe. If a browser supports both of these events, the unloaded boolean ensures the scorm.quit function is not executed more than once.

If you’re using the pipwerks SCORM wrapper, your code will be even simpler, because the pipwerks wrapper automatically checks the API’s availability before performing any action. The wrapper also sets the cmi.exit/cmi.core.exit parameter for you.


var unloaded = false;
function unloadHandler(){
   if(!unloaded){
      scorm.save(); //save all data that has already been sent
      scorm.quit(); //close the SCORM API connection properly
      unloaded = true;
   }
}
window.onbeforeunload = unloadHandler;
window.onunload = unloadHandler;

SCORM Tip: Don’t forget to commit!

A number of people have recently asked me about the scorm.save() function in the pipwerks SCORM wrappers. What is it, and when should it be used?

The pipwerks scorm.save() function is a shortcut for SCORM’s Commit (SCORM 2004) and LMSCommit (SCORM 1.2) methods. Invoking commit in SCORM means you are explicitly instructing the LMS to persist the data you’ve sent. In other words, you’re telling the LMS to save your stuff!

When sending data from your course to the LMS, the data is traveling from the course window to the LMS via JavaScript and is stored in the browser. The SCORM spec gives LMSs the flexibility to decide when to transfer this data to the database. Some LMSs will not immediately write the data to the database because it can clog up the system; they prefer to queue up the data and send it in bunches. This explains why some courses will be successful in sending the data from the course to the LMS, but the LMS doesn’t seem to save the data. You didn’t tell it to! I know, I know, it seems daft, but it happens. So, to be safe, ensure your data gets saved by instructing the LMS to save the data.

Note that some LMSs will automatically commit at the end of a session, usually by detecting if the course window was closed (window.onunload) or if a certain CMI call was invoked, such as setting the completion status. However, you should never take your chances, and should design your SCO to commit regularly. Just be careful not to overdo it.

The rule of thumb is to invoke a commit (save()) if you use the pipwerks wrapper) after a significant chunk of data has been sent to the LMS, but not after each and every call:

NO (committing too frequently):


scorm.set("cmi.location", "some string indicating location");
scorm.save();
scorm.set("cmi.suspend_data", "your custom suspend_data string");
scorm.save();
scorm.set("cmi.score.raw", 80);
scorm.save();

NO (not committing enough):


scorm.set("cmi.location", "some string indicating location");
scorm.set("cmi.suspend_data", "your custom suspend_data string");
scorm.set("cmi.score.raw", 80);

YES (one commit after a short series of ‘set’ calls):


scorm.set("cmi.location", "some string indicating location");
scorm.set("cmi.suspend_data", "your custom suspend_data string");
scorm.set("cmi.score.raw", 80);
scorm.save();

Ideas wanted for new SCORM wrappers

As you may have read in previous posts or tweets, I’m working on a new SCORM 2004 wrapper for both JavaScript and ActionScript that will contain advanced functionality and improved shortcuts.

For instance, I’m trying to write an easier way to work with the cmi.interactions model, and also trying to add more error-checking that will look for gotchas such as exceeding the length limit of suspend_data.

I’m looking for good ideas. How do you handle your cmi.interactions? What kind of code shortcuts would you like to see? How can working with SCORM be made easier? I’d love to hear your ideas, just post them as comments below or send them to me on twitter.

This project — just like my previous wrappers — will be freeware, either MIT license or GNU license, so no worries about me running off and selling your ideas!

(FYI: for now I’m focusing on SCORM 2004 — SCORM 1.2 should be retired — but depending on how things work out I might add backwards-compatibility for SCORM 1.2.)

SCORM resources

I recently emailed a shortlist of good SCORM development resources to a colleague, and figured I should probably post a list here, too. This is a quickie list, and I’m sure I’m leaving someone out. If you know of any resources I’ve missed, please add a link in the comments. This list is presented in no particular order.

  • Claude Ostyn’s site. He passed away in 2007, so there haven’t been any updates since then. His materials present a nice overview including lots of examples.
  • The ADL website. Their SCORM Documentation Suite is the official documentation. Must-have for any SCORM developer.
  • Redbird DevNet [link no longer available]. They have a nice tutorial/walk-through of SCORM 2004 architecture.
  • Rustici Software. A for-profit business that works almost exclusively with SCORM. They’ve posted some helpful resources on their site.
  • Aaron Silvers has been writing about SCORM (especially with regards to Flash) for a long time.
  • adlCommunity. A site dedicated to advancing ADL’s technologies. There are some good resources for SCORM developers, including an overview of SCORM written by the late Philip Dodds, one of the chief architects of SCORM.
  • Academic ADL Co-Lab. An offshoot of the ADL that offers SCORM resources and training for would-be SCORM developers. Also hosts Joe Nelson’s custom SCORM JavaScript framework LibSCORM (“a boilerplate template that implements common SCO Tracking and Communication functionality”), which some may find useful.

Of course, I also have a few SCORM odds and ends on my site you may find useful:

For those of you who don’t know, SCORM 2.0 is in the works, and is being handled by Learning Education Training Systems Interoperability (LETSI). SCORM 2.0 is still in the formative stages and won’t be ready for a few years (minimum), but you can certainly join the conversation and help mold SCORM 2.0 by visiting the LETSI site.

Update: LETSI is no longer tasked with SCORM 2.0, which will remain with the ADL. LETSI will continue to work on e-learning technology standards, including a potential replacement for SCORM.

What do you want *your* SCORM to do?

Most e-learning developers don’t care about SCORM and only (begrudingly) learn enough to get the job done. I don’t blame them. The other day I was reading some old Drupal community posts (circa 2005) about adding SCORM functionality to Drupal. One comment stood out:

SCORM was the big buzz in 1999 and 2000 when I was at Oracle Denmark working on “object oriented” e-learning […] but it is no surprise that it is not so much a real world success, as it is more pleasing to the theorist, than to the producer.

More pleasing to the theorist than to the producer.” I’m not sure if the author was referring to his own work or SCORM, but I think the phrase certainly applies to SCORM. This crystalizes what I’ve been trying to do with my SCORM wrapper and ActionScript classes: simplify SCORM so the average web developer can get their courseware to work in SCORM-conformant LMSs without having to become a SCORM expert.

This brings up the never-ending question when it comes to using SCORM in courseware: What are you really trying to do with SCORM?

What was SCORM designed to do?

SCORM stands for Shareable Content Object Reference Model. What does this mean? According to the ADL website, “SCORM is a collection of standards and specifications adapted from multiple sources to provide a comprehensive suite of e-learning capabilities that enable interoperability, accessibility and reusability of Web-based learning content.”

The general idea is that a course developer can re-use elements from course to course, be it a small piece of content such as an image or an entire course lesson. A common example is from the military: if the Army has created a course that contains a lesson in how to safely use a fire extinguisher, any other branch of the military should be able to import that exact content into their course without having to re-write or re-develop any of it. This avoids duplication of effort, which (theoretically) saves the government a ton of money.

SCORM also serves as a communication standard for courseware, which allows a developer to create a course that can be used in any SCORM-conformant LMS. Before SCORM (and AICC), many LMSs only supported their own proprietary course-to-LMS communication systems. This meant that if a course developer or vendor wanted to make their course work on more than one LMS, they had to re-code the course to use each LMSs’ proprietary system. Even worse, not all LMSs had the same feature support, such as quiz scoring and bookmarking. When the US Military required SCORM to be supported by LMS vendors, it was basically ensuring its courses wouldn’t need to be re-developed or re-coded for each LMS, and established a baseline of feature support that would be expected from all LMS vendors.

That’s nice, but…

As I explained, the SCORM developers devised a complex system of cataloging course content (the metadata you find in the imsmanifest file), as well as a sequencing and navigation schema which should allow a developer to simply insert a link to content (or another SCO) in the manifest, and let SCORM handle the rest. Sounds great, but guess what? Full-blown SCORM is impractical and unreliable.

The theorists who devised SCORM will say that you should be building courses using an intricately woven set of reusable SCOs, bound together by an imsmanifest XML file bursting with links to course content files and related metadata. They have attempted to provide a sequencing and navigation system that can be used to navigate within and between SCOs. These are noble efforts, but they don’t really help most e-learning developers.

Why? Two reasons: Shareable content is problematic to implement, making it useful to only a small percentage of developers, and SCORM is usually not the starting point for a SCO’s internal navigation mechanisms.

Shareable content is problematic to implement

The whole theory behind SCORM’s content and SCO interoperability is really nothing more than theory. It’s not useful for most e-learning developers. In their attempt to maximize flexibility and practicality, the SCORM guys actually made SCORM a less practical option, and more of a headache to use.

Shareable content (including SCOs) implies that the content is generic enough to be reused in different organizations and with different course styling/visualization. This a long shot, and doesn’t take into account the myriad visual design styles developers may choose to use. The only way around this issue is to use a strict formatting approach, which might work in a tightly controlled organization, but not in a general community sense. But for argument’s sake, let’s say everyone agrees to use the same color schemes and fonts in their files. There’s an even bigger issue to deal with: the technology itself, namely file formats.

What if one developer only works in Flash, while the other only knows HTML? What if one Flash developer only uses ActionScript 2 while the other Flash developer only uses ActionScript 3 (the two are completely incompatible)? What if one developer uses XML with Flex while another only uses rapid e-learning tools such as Captivate and Articulate Presenter? For that matter, how can SCORM support the growing online synchronous e-learning market or the booming mobile learning market?

When you stop and look at SCORM’s reusability/shared content model, it simply can’t support today’s rapidly evolving web-based technology. And for the few organizations that manage to use SCORM for this purpose, it’s an extremely difficult task to manage. So what about the developers who don’t use SCORM for shareable content, but choose to simply use SCORM as an LMS communication protocol? SCORM becomes overkill, most notably with the sequencing and navigation feature.

SCORM is usually not the starting point for course navigation.

Using SCORM for sequencing and navigation is NOT the norm and never will be. Personally, when I create a course system, I begin by making it work in what I call standalone mode: no reliance on any server-side process. This allows the course to be used in non-tracking environments, such as from a CD-Rom, a USB ‘thumb’ drive, or a plain vanilla website. Standalone mode usually means an HTML-based course using cookies and JavaScript, or a Flash-based course using a Shared Object. Once I get the system up and running and behaving as I planned, including navigation and determining the course’s completion status, I fork my code to include a SCORM option. This approach also provides the flexibility to add a third fork for any other tracking system I may need to support, such as AICC or (gasp!) proprietary LMS code.

Third-party rapid e-learning tools use the same approach: get the course to work on its own, then when publishing, go ahead and add the required tracking code, be it AICC, SCORM, or the numerous other formats that have popped up over the years. Thus, navigation is almost always handled internally and not via SCORM.

Continuing with this train of thought, my interaction with the e-learning community has led me to believe that many e-learning developers are either SMEs using rapid e-learning tools, or are traditional web developers doing some freelance Flash or HTML work. In the case of the web developers, they build the course to do what they want, with the minimal functions they need for their client. When it comes time to load the course in the LMS, they suddenly realize they need to add SCORM support; SCORM was never considered an integral part of the course, and is considered something of an inconvenience that must be tolerated for the sake of making the course work in the LMS and keeping the client satisfied. The SMEs using rapid e-learning tools are lucky because they can just change the publishing preferences; the web developers have to go in and augment their code by hand. In either case, the course developer did not start the project thinking “I’m going to use SCORM to handle my navigation!”

What do you want SCORM to do, then?

SCORM is not perfect, but we must concede that it’s still the strongest available technical standard for elearning. There are others (AICC, Common Cartidge Alliance, etc.), but SCORM is by far the most widely supported standard. The exciting news about SCORM is that it is being handed off to a new organization, LETSI, which will hopefully breathe new life into the standard. Matter-of-fact, LETSI has solicited white papers and suggestions for improving SCORM from the general public. Knowing this, we should stop and seriously consider: What do we really want SCORM to do? What should it handle, and what should it keep its sticky fingers off of?

Here are my thoughts. Please add your own in the comments section!

1. SCORM should be broken into separate and clearly differentiated APIs or functionality. The first — and only mandatory — API should be simple course-to-LMS communication. The second should be a reusability/shareable content mechanism that can be used if desired. The third should be an optional navigation API that can be used regardless of whether shared assets are in play. A fourth potential API could be a quiz/exam API that provides an easy-to-use framework for handling quiz data and results. (And NO, the IMS’ QTI specification is NOT easy to use by any stretch of the imagination! Let’s not pretend it’s the best solution, because it isn’t.)

2. SCORM’s course-to-LMS communication protocol should be simplified and strengthened. As-is, SCORM already does a decent job at this task, but there are a number of ways it can be improved.

  • Simplify (or eliminate!) the imsmanifest file. For courses that don’t use shared resources and don’t use SCORM for navigation or sequencing, the imsmanifest is an extremely bloated and annoying document. It is by far my least favorite part of the SCORM spec., and I know I’m not alone in that sentiment. When talented developers who write code in their sleep have a hard time writing what should be some simple XML, and wind up relying on plugins and third-party applications to auto-generate their manifests, you know there’s a problem somewhere. There must be a way to simplify the manifest if SCORM is only being used as an LMS communication protocol.
  • Use proper data types. For instance, don’t return a ‘stringified’ boolean, return a real boolean.
  • Simplify syntax. This means creating an easy-to-use set of base commands such as API.init(), API.quit(), API.set(prop, value), and API.get(prop) instead of the more verbose (and boring) API.Initialize(), API.Terminate(), API.SetValue() and API.GetValue(). (On a related note, API.Initialize and API.Terminate should NOT be required to pass an empty string (“”); the empty string serves no purpose and only creates the potential for more unnecessary errors.)
  • Create a standardized JavaScript wrapper. This wrapper should use a single global object to contain all variables (properties) and functions (methods). The pipwerks SCORM API wrapper was created to fill this void, but I’m sure it can be improved upon. A standardized wrapper would facilitate interoperability between SCORM-conformant content produced by off-the-shelf products and home-brewed projects.Consider this scenario: Joe Developer has created a full HTML-based course, which is considered a single SCO. Joe wants to drop in a couple of Flash-based interactions created in Adobe Captivate or Articulate Engage; the results of these interactions need to be tracked within the framework of Joe’s course. This is currently not possible (or at least not very easy); if the Flash interactions are published with SCORM enabled, they will try and call LMS Initialize, and they will try to use custom functions contained in the wrappers provided by their respective companies. If there were a single, standardized wrapper, the Flash files output by these products would use the same syntax and functions as the home-brewed course, enabling Joe to easily integrate their code with his own. This might include a check for an active LMS API, which would eliminate the troublesome call for LMS Initialize in the Flash files.Granted, The Flash files might also use a variety of browser communication methods that could cause problems, from LocalConnection to FSCommand to ExternalInterface, but using a standardized wrapper would go a long way towards bridging the gap.

3. All CMI elements should be re-examined for usefulness. Personally, I never use over 2/3 of the existing elements, and find many of them confusing or hard to use. And this is after 3+ years of constant SCORM development! SCORM should be as streamlined as possible; additional functionality should be separated from the core, and usable on-demand as a plug-in module.

4. Provide more space in the database for developers to store custom data. “suspend_data” is constantly abused by developers who need some space to store their custom data; there’s no reason a new, larger space can’t be assigned for developers to use at their discretion.

What do you think?

I’m sure I left a lot of things off this list, and I’m sure many of you have ideas I’ve never thought of. Share your thoughts! There’s a good chance they’ll be read by others, and your idea may be a spark that helps revolutionize online education! Or not. 😉

If you have some free time, take a look at some of the ideas LETSI is toying with for SCORM 2.0 [link no longer available]. I think they’re on the right track, so long as they don’t let advanced functionality get in the way of the (hopefully) streamlined basics, which is probably what the vast majority of developers will use.

Extending the SCORM wrapper and ActionScript classes

I’ve had a number of people ask me about extending my SCORM helpers (the JavaScript-based SCORM API wrapper and the two ActionScript classes) in order to completely remove the need to know any of the “cmi” calls.

For instance, being able to do something like this:


scorm.bookmark = "page1";
scorm.status = "incomplete";

instead of


//SCORM 2004
scorm.set("cmi.lesson_location", "page1");
scorm.set("cmi.completion_status", "incomplete");

//SCORM 1.2
scorm.set("cmi.core.lesson_location", "page1");
scorm.set("cmi.core.lesson_status", "incomplete");

This level of abstraction is very attractive for a couple of reasons: it means the developer doesn’t need to know SCORM 2004 versus 1.2 syntax, and it uses more concise code (which is easier to type and generally means less typos).

So, understandably, people are asking me why I haven’t added this level of abstraction into the SCORM helpers.

I have three reasons: SCORM is not that simple, the functionality between SCORM versions is significantly different, and extending the helpers that far means writing a complete (non-standardized) replacement syntax for SCORM.

SCORM is not that simple

SCORM is very complex, and trying to abstract the cmi calls gets very sticky very quickly. The examples I gave a moment ago are very simple examples that lend themselves well to an abstraction layer. However, SCORM can do much, much more; when you start getting into objectives and sequencing, this abstraction model becomes very difficult to maintain.

For instance, the “interactions data model element” (section 4.2.9 of the SCORM 2004 RunTime Env documentation) uses elements such as “cmi.interactions.n.objectives.m.id” where n and m are variables. The abstraction layer would need to handle these somehow, which leads to code such as


scorm.interactions[n].objectives[m].id

To me, this isn’t much of an improvement in ease-of-use, but for argument’s sake, let’s say it’s do-able and move to the next point.

The functionality between SCORM versions is significantly different

Simply put, SCORM 2004 can do more than SCORM 1.2. They share a set of basic functionality (bookmarking, setting lesson status, saving suspend data, etc.), but SCORM 2004 includes sequencing and navigation features that aren’t available in SCORM 1.2.

If someone unfamiliar with SCORM functionality tries to use the SCORM helpers in a SCORM 1.2 environment, they might attempt to use SCORM 2004 features that aren’t available, resulting in errors.

It would also take a significant amount of work to abstract all of the dense sequencing and navigation elements. Considering 80% (my guess) of SCORM users consider the sequencing and navigation feature to be broken and unstable, is it even worth it? Probably not.

But assuming we decided to continue with the project, we’d come upon my third concern…

It becomes completely non-standardized syntax

The point of a standard like SCORM is to ensure everyone uses the same terminology. My SCORM helpers are designed to make a developer’s life a little easier while still adhering to the SCORM standard. When you ‘wrap’ the SCORM code in its entirety, you will wind up with some people using SCORM without understanding it at all.

If the goal is to make SCORM easier to use, that can be a good thing. But there needs to be a balance between ‘easy’ and standards-compliant. By making developers use the “cmi” elements in their get and set calls, I’m basically ensuring that they’re looking at SCORM documentation in some form, which hopefully means they should understand what SCORM can and can’t do.

Bridging the needs

I confess that when I wrote the wrapper and ActionScript files, I made an attempt at abstracting or wrapping the entire SCORM spec. As you can imagine, it wasn’t fun. After stepping back and evaluating the situation, I decided to stick to the ‘core’ functionality contained in the current pipwerks SCORM wrapper and ActionScript classes.

Remember, the pipwerks SCORM helper files perform other dirty work, too: The primary purpose for the pipwerks SCORM API wrapper is to locate and connect to the SCORM API in the LMS, while maintaining a clean global space. The primary purpose for the pipwerks SCORM ActionScript classes is to handle Flash-to-LMS communication automatically, so you don’t need to get your hands dirty with ExternalInterface. (Anyone who’s had to use SCORM with FSCommand or GetURL knows what a pain Flash-to-LMS communication used to be!)

These functions were my primary goals; simplifying the syntax was almost an afterthought. However, as I mentioned at the beginning of this post, I’ve received a number of emails from people asking about extending the wrapper to include all SCORM syntax. I interpret this to mean that a lot of people are interested in using standards, but most of them don’t want to be bothered with the details or have to learn the whole standard. This means they view SCORM as an important standard, but also find it difficult and inconvenient to implement. I agree.

This kind of reminds me of the Macintosh. People wanted to have a computer and be able to do cool computer stuff (games, word processing), they just wanted it to be easier. They didn’t want to be bothered with details about the operating system or hardware specs; they just wanted it to work out-of-the-box, no muss, no fuss.

SCORM isn’t about ease-of-use. If it was, we wouldn’t have these crazy imsmanifest files that are total overkill for simple courses (I wish we could use JSON for a manifest!). SCORM 2004 has been around for four years, but SCORM 1.2 is still going strong. Why? SCORM 1.2 is easier to implement.

Soaking all this in, perhaps I should resume my work extending the SCORM wrapper (and maybe get some of you to pitch in a bit! ;)). One of the ideas I’ve been kicking around is leaving the wrapper and ActionScript files as-is but creating extensions for them. This way the extension is available if you want it, but if you don’t, you can just use the core functions.

What do you think? Please weigh in if you have an opinion.

How to add basic SCORM code to a Flash movie

Update 10/2011: The Planets example has been updated (almost completely rewritten) and no longer strictly adheres to the steps and screenshots in this tutorial. The general concepts are the same, but the project files have been substantially refined. To prevent confusion about which files to use, I have removed the original project files and replaced them with the updated version. Sorry for any inconvenience, and you’re welcome!

Here’s a quick tutorial for adding basic SCORM functionality to an existing Flash file. This tutorial aims to demonstrate just how easy it can be to add SCORM functionality to an existing Flash movie.

In this tutorial, we’re going to keep things very simple; our SCORM code will only check the LMS for a prior completion, and if no completion is found, will set the course to complete at the appropriate point in the movie.

Here are the work files (ZIP, approx 615KB) if you’d like to add the code yourself while reading the tutorial. The zip file also contains the completed product.

Important note: This tutorial uses ActionScript 3 and SCORM 1.2, but the same principles apply for ActionScript 2 and SCORM 2004

The steps:

  1. Add the SCORM wrapper to the head of the HTML file
  2. Import the SCORM class into the Flash file
  3. Add some variables and create a SCORM instance
  4. Initialize the SCORM connection and check for prior course completion
  5. Add the SCORM completion code
  6. Publish the FLA
  7. Modify the manifest

Step one: Add the SCORM wrapper to the head of the HTML file

Open the index.html file in your HTML editor of choice. Note that we’re NOT using the standard HTML file produced by Flash’s publishing feature. It’s my opinion that the HTML produced by Flash is ugly, bloated, and doesn’t support standards well enough. We’ll roll our own using stripped-down markup, external CSS file for simple styling, and SWFObject for embedding (feel free to use another embedding method if you prefer).

Once you’ve opened the HTML file, add a link to the SCORM wrapper script in the document’s <head>:

<script type="text/javascript" src="SCORM_API_wrapper.js"></script>

Your HTML file should look something like this:

Add a link to the wrapper JavaScript file in your HTML

Update: This screenshot is slightly out-of-date; the SCORM wrapper file no longer includes the version number in the filename, and should just be SCORM_API_wrapper.js

You may want to specify the targeted SCORM version using JavaScript (this can help avoid problems with some LMSs). To do so, simply add the following line of code to the head of the document after the SCORM_API_wrapper.js link:

<script type="text/javascript">pipwerks.SCORM.version = "1.2";</script>

Believe it or not, that’s the only change that needs to be made to the HTML file! Save and close the file.

Update: The JavaScript in the project files has been expanded to include a few other best practices, including using an onunload handler.

Step two: Import the SCORM class into the Flash file

Open the planets.fla file in Flash. Add the SCORM class to the Flash file using an import statement in Frame 1’s frame script:

import fl.controls.Button;
import flash.events.MouseEvent;
import com.pipwerks.SCORM;

The file should look something like this:

Add the import statement

Update: The latest version of the SCORM Wrapper for ActionScript uses a slightly different path than the one in the screenshot: com.pipwerks.SCORM instead of pipwerks.SCORM.

This is a good time to test the FLA to ensure you have the correct file path for the SCORM class (it should be in a folder named com, which is inside a folder named pipwerks; this pipwerks folder should be located in the same folder as the FLA file). To test the FLA, go to Control > Test Movie. If the movie plays without errors, your file paths are ok.

Step three: Add some variables and create a SCORM instance

Declare the following variables in the first frame of your Flash file, after the import statements:

import fl.controls.Button;
import flash.events.MouseEvent;
import com.pipwerks.SCORM;

var lessonStatus:String;
var lmsConnected:Boolean;
var success:Boolean;

Next, you’ll need to create a new SCORM instance using the pipwerks.SCORM class. You can create a new SCORM object using the following code:

import fl.controls.Button;
import flash.events.MouseEvent;
import com.pipwerks.SCORM;

var lessonStatus:String;
var lmsConnected:Boolean;
var success:Boolean;
var scorm:SCORM = new SCORM();

Update: The FLA’s ActionScript has been rewritten and has a slightly different structure than the code presented in the rest of this post, but the same principles apply.

Step four: Initialize the SCORM connection and check for prior course completion

Add a scorm.connect() call, which returns a boolean indicating whether it succeeded or not.

import fl.controls.Button;
import flash.events.MouseEvent;
import pipwerks.SCORM;

var lessonStatus:String;
var lmsConnected:Boolean;
var success:Boolean;
var scorm:SCORM = new SCORM();

lmsConnected = scorm.connect();

If the connection was successful, lmsConnected will evaluate to true. That means we can start requesting data from the LMS. Start by requesting the current completion status.

A few things to note: If the course status is “completed” or “passed”, we won’t need to keep the LMS connection active — we need to be careful not to overwrite the previous completion by accident. So, if the course has already been completed, we’ll just disconnect and call it a day.

If the completion status isn’t “completed” or “passed”, we’ll need to explicitly set the course to “incomplete”.

import fl.controls.Button;
import flash.events.MouseEvent;
import pipwerks.SCORM;

var lessonStatus:String;
var lmsConnected:Boolean;
var success:Boolean;
var scorm:SCORM = new SCORM();

lmsConnected = scorm.connect();

if(lmsConnected){

   lessonStatus = scorm.get("cmi.core.lesson_status");

   if(lessonStatus == "completed"){

      //Course has already been completed.
      scorm.disconnect();

   } else {

      //Must tell LMS course has not been completed yet.
      success = scorm.set("cmi.core.lesson_status", "incomplete");

   }

} else {

   trace("Could not connect to LMS.");

}

Step five: Add the SCORM completion code

Find the appropriate place in your movie to call the completion code. In this example, we’ll call the completion code when all four planets have been visited. There is already a ‘check’ for this condition in the function resetPlanets, so we can just add the code there.

function resetPlanets():void {

if(visitedMercury && visitedVenus && visitedEarth && visitedMars){

   success = scorm.set("cmi.core.lesson_status", "completed");
   scorm.disconnect();
   lmsConnected = false;

   gotoAndPlay("end");

} else {

[ ... ]

Step six: Publish the FLA

Publish the FLA. Be sure to turn OFF the “HTML” option since we’re using our own HTML file. You should also ensure the target Flash version is Flash 9, since the “Planets” movie uses ActionScript 3 and a few filters that are only supported by Flash 9+.

Save and close the FLA.

Step seven: Modify the manifest

All SCORM-based courses require a manifest file (imsmanifest.xml) that contains important metadata about the course. For our example, we’ll simply grab an existing imsmanifest.xml file and update it to match our course.

  1. Open the imsmanifest.xml file
  2. Change the identifier attribute of the manifest element (at the top of the file) to something suitable for this course (no spaces): identifier="MyPlanetsCourse"
  3. Find the organizations element (and organization child element) starting at line 15. Change the “default” and “identifier” attributes to something suitable for your organization. I’ll use “pipwerks”. Be sure to avoid spaces and illegal characters, such as punctuation (other than the underscore _)
  4. Find the two title elements, starting at line 17. Change both of them to something suitable for your course. For this example, I’ll change them both to “Planets!”
  5. You’ll need to list the files used by this course in the resource node. For this example, we need to make sure “href” is set to “index.html”, then we need to list the other files using file elements:
    
    <resource identifier="SCO_Resource_01" type="webcontent" adlcp:scormtype="sco" href="index.html">
       <file href="index.html"/>
       <file href="planets.swf"/>
       <file href="SCORM_API_wrapper.js"/>
       <file href="swfobject.js"/>
    </resource>
    
  6. Save and close the imsmanifest file

Wrap-up

That’s all there is to it! As you can see, adding simple SCORM code is much easier than many people realize. It may seem daunting at first, but in reality all we’ve done here is:

  • Added a little JavaScript to the HTML file
  • Added a few variables and functions to the ActionScript
  • Edited a few IDs and file links in the imsmanifest.xml file

In my opinion, SCORM only becomes difficult if you try and use it to handle a course’s sequencing and navigation, which even SCORM experts are hesitant to do (it’s considered a “broken” feature by many key figures in the industry).

The bottom line is that if your existing FLA is self-sufficient before SCORM comes into the picture — it’s already set up to handle its own navigation internally via ActionScript and already has a mechanism for determining whether the user has ‘finished’ the movie, be it completing an activity or simply reaching the last frame of the SWF — SCORM becomes more of drop-in item, almost an afterthought. It doesn’t need to be a nightmare that scares developers away.

It’s my hope that my SCORM wrapper and ActionScript classes encourage more people to embrace SCORM as a simple, easy way to ensure their course(s) use standards and work in almost any LMS.