Getting to grips with SCORM API

This fourth part of our series explores the nitty-gritty details of SCORM, by focusing on the API itself. On day three, we learned how to import a SCORM course into your LMS. We're now ready to discuss the magic of the SCORM API. As we moved through the series, we've discussed some of the “sections” a SCORM can be broken into - namely, the package and runtime environment. On day three, we learned that the packaging aspect, or Content Aggregation Model (CAM), defines how an authoring tool or eLearning developer should package their course into a zip file.

Key runtime environment specs

But the runtime environment (RTE) is what we’re interested in today. RTE covers the point from which a course is launched and determines how information, including scores, answers or bookmarks, are tracked back to an LMS. The RTE specification is large and, at first glance, quite daunting! However, I’ll break the flow into basic sections and rules to make the specification easier to digest. Let’s jump straight in! When a learner launches a SCORM course in an LMS, the following “actions” kick into play:

  1. "FindAPI": Let's presume that a learner has clicked a button on the LMS UI to launch a course. A SCORM will first attempt to find the API provided by an LMS in order to track data. Say what?! Yep, that’s right. An LMS provides an API for the SCORM to use. That might sound complicated but it's not really. The API is essentially a simple JavaScript object that presents all SCORM RTE functions for use. For example, a SCORM course will search for the API object, after which it will be able to call “save”, “get”, “start” and “exit” type commands. So the API object is a piece of JavaScript that manages communications between the SCORM and the LMS. But more on that later! The object, however, doesn't have to be JavaScript-based. It could easily be created using another language, like Java or Flash. But given the scrutiny, both technologies are under, and their love/hate relationship with firewalls, JavaScript APIs represent a sensible approach.
  2. LMSInitialise: This piece of SCORM fancy talk allows the course to say: “Hey, a learner started the course, or learners launched the course, so you, LMS, do stuff!” As in step one, the API object was found and now the SCORM is calling its LMSInitialise function. That tells the LMS that the SCORM is starting up and it should prepare course data for use.
  3. LMSGetValue & LMSSetValue: If the initialization succeeded (and more on that below), the SCORM may now call some methods on the API to get or set data. For example, the SCORM might “get” information about the last bookmark a learner accessed from the LMS. When a command like that is received, the LMS responds by sending bookmark data for the course to SCORM, so the course can commence where the learner last exited. The set describes the opposite scenario, funnily enough. Set can be used to tell the LMS which bookmarks it should store for the learner. In other words, set says: “Hey you, LMS, the learner is on page three now, store that!” The LMS obeys and returns a "success" message to the SCORM course. The SCORM now knows that the bookmark was saved and it doesn’t need to get angry about the potential for lost data. Ultimately, get and set are used to retrieve and save data, not only for bookmarking, but also statuses, scores, and so forth.
  4. LMSFinish: The opposite to LMSInitialise, LMSFinish is called when a learner exits a SCORM course. It doesn't tell the LMS that a learner has completed the course, just that they've exited. There are many different steps that can occur at this point. If, for example, the learner has actually completed a course or passed an exam module, the LMS will need to act on that - we’ll cover some of those details below. For now, it’s important to understand that, as far as the process of a learner launching, viewing or completing a course is concerned, the SCORM protocol and specification can be boiled down to the four steps outlined in this section.

Key SCORM API attributes

As we've discussed, the LMSGet/SetValue commands are essential for a SCORM to track data back to an LMS. This article would be too long and sleep-inducing if we had to cover all of the possible attributes. But there are some key concepts that are worth summarizing so that you're armed with enough knowledge to feel comfortable with common SCORM lingo. SCORM RTE defines some attributes or fields that are specific to the SCORM data realm. For example, an attribute for storing scores is defined as score_raw and is a form of numerical field. Here, we'll discuss the most common attributes and uses:

  1. Read/Write and sizes/types: The SCORM API includes many attributes that can be updated and read from. For example, there are attributes for scores, statuses, bookmarks, quiz answers (which are called interactions), and more. Each attribute has its own type (be they numbers or boolean true/false, etc.). They also have a definition that states whether or not the attribute is read-only or read/write. A good example of this occurs when a SCORM calls an LMSGetValue to retrieve a learner's name (which is read-only because a SCORM can't change names in an LMS). The flipside is that if the SCORM tried to call LMSSetValue for a learner's name, the LMS should give back an error. Indeed, if the value is a writable field, the LMS should be storing it for later use (probably in its own datastore).
  2. suspend_data or lesson_location: These attributes are typically used for bookmarking data and are examples of a read/write type field. For example, a SCORM might use lesson_location to set a number like 12, indicating that the learner is on page 12 of the course. That information is stored by the LMS to use when the learner launches the SCORM again. While suspend_data is similar, it also supports larger data volumes: 1024 characters, to be exact (which was extended to 64,000 in version SCORM 2004 3rd ed.). suspend_data makes it possible to store larger kinds of bookmarking data, like pages visited, but also answers submitted to questions, or bookmarks in quizzes and subsections of pages. As an example, suspend_data could look like: 1,3,4,5,10|answered_1,wrong|answered_2|wrong. The data here is “random”, in that it's not SCORM specific, but specific to the course or an authoring tool that set it.
  3. lesson_status: This describes the status of a learner's course. lesson_status will at first be “not attempted” and the SCORM will later set a status as appropriate. For example, if a learner exits halfway through a course, you’ll typically find the status set to “incomplete”. Similarly, if a learner completed their module or passed or failed the course, the SCORM will use lesson_status to tell the LMS that the learner's status is “completed”, “passed”, or “failed”. It's worth mentioning one pro-tip that confuses SCORM creators and causes tracking issues. If the SCORM doesn't set lesson_status (so if, from start to finish, no value was ever set), the LMS can assume that the learner completed the course on exit!
  4. session_time & total_time: These fields are extremely useful for eLearning reporting. They allow you to track the amount of time a learner takes to complete a module and how much time they spend on a course overall. Session time is a writable field that allows a course to tell an LMS how much time the learner spends viewing it during a given launch and exit session. The LMS will take the session_time value and tally it up into a total time tracked. That way, the LMS can track total time across multiple launches if necessary. The SCORM specification views total_time as a read-only field. That means the LMS, and not the SCORM, is responsible for managing the data.
  5. score_raw & mastery_score: I mention these together as they usually go hand in hand. score_raw is the value used to store a mark calculated for a course, for example, a learner might achieve 85% or 33.22%. The mastery_score, as we learned previously, is the score needed to pass a module. That’s very important to the LMS, for one reason. The LMS can determine if the learner passes or fails (i.e. can change a completed status to passed or failed) when the following holds true:

  1. If these three steps hold true, the LMS can compare a learner’s score to the mastery_score for the course and determine a pass/fail status. If the learner’s score is greater than or equal to the mastery_score, the learner will be deemed to have passed and the LMS will set that status. And if the learner didn't achieve the necessary score, a fail would be recorded. In this scenario, the LMS can’t change the status itself. It must listen to and obey the data the SCORM shares without altering it. Otherwise, an LMS would be said to overwrite history, which is prohibited by the SCORM standard, and rightly so.
  2. Interactions/Objectives: SCORM defines attributes for tracking user objectives and interactions within a given module. You can think of objectives as key goals a learner must reach, and interactions as the answers a learner submits during a quiz or survey in the SCORM. It’s particularly important that the specification defines useful elements the SCORM can query the LMS for, such as how many interactions were saved. The SCORM can also store, not only answers submitted, but the amount of time taken to submit an answer, the correctness of the answer, and scores achieved. That data can be very useful for creating reports in your LMS. While knowing which answers were submitted during an exam is great, knowing the length of time taken between answers allows you to analyze some pretty neat metrics later.

These are only a subsection of the SCORM fields that will often be available to you. There are many others, like max_score, min_score (the maximum or minimum scores a learner can achieve), and so forth. If your thirst for SCORM knowledge has not been quenched by the fields described here, you can review the full RTE specification in this great article on all things SCORM, which also includes sample courses you can download!

Mandatory vs. non-mandatory

It's worth mentioning that SCORM defines a set of mandatory fields that an LMS must implement in order to be compliant. The RTE specification can be broken down into mandatory and non-mandatory fields. It's important to ask an LMS vendor you're considering if they support all, or just a subset, of the SCORM specification. For example, because quiz interactions are not mandatory, you might find that your quiz won’t track answers submitted by learners in your LMS, leaving a serious gap in your reporting capabilities.

Cross-domain issues

It wouldn't be right to finish without mentioning cross-domain issues and SCORM! As I mentioned earlier, SCORMs typically track using a JavaScript API object exposed by an LMS. The LMS is required to call this object “API” and it must reside on the window of the LMS launching the SCORM. Now the fun really starts if the LMS is on one domain and the SCORM that’s being launched is on another - your LMS may be hosted on and your course hosted on By definition, JavaScript can't communicate easily across domains. While it’s possible with the help of some JavaScript trickery, most authoring tools don't provide SCORMs that are cross-domain capable. Once again, it's important to ask an LMS provider if they've gone the extra mile to support cross-domain tracking with SCORM. It's particularly important if your SCORMs are media rich and require a Content Delivery Network (CDN, such as CloudFront) to deploy courses. At LearnUpon, we've taken that approach. It delivers a better experience to learners viewing courses that contain rich-media content delivered via the server closest to them, rather than relying on the server that hosts your LMS (which could be far-flung!). Tomorrow  Phew, that took some effort! We're now approaching day five of our series. I promise that the final post will be packed with useful information about the future of SCORM and some other interesting movements in the industry. With any luck, you're now moving towards SCORM hero status and have a good grasp of key concepts. Read the final post in our series for thoughts on AICC, Tin Can (xAPI), cmi5, Common Cartridge, LTI and more! Yesterday  Missed yesterday's post? Learn how to get SCORM content into your LMS




thank you image

Thank you!

Your comment is waiting for approval.