9 min reading time
Getting to grips with SCORM API
Get ready to explore the nitty-gritty details of SCORM, by focusing on the API itself. Before we jump in, you should know how to import a SCORM course into your LMS. Once you know how to do that, you’re ready to find out the magic that is the SCORM API.
SCORM can be broken into “sections” – namely, the package and runtime environment. The packaging aspect of SCORM, 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
Let’s take a look at the runtime environment (RTE). 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, confusing. But don’t worry, we’re going to break the flow into basic sections and rules, to make the specification easier to understand.
When a learner launches a SCORM course in an LMS, the following “actions” kick into play:
“FindAPI”:
Let’s presume that a learner has clicked a button on the LMS UI to launch a course. First, SCORM will attempt to find the API, provided by an LMS, in order to track data. In short, 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.
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.
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 your thing!” 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.
LMSGetValue & LMSSetValue:
If the initialization succeeded, 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 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 status, scores, and so forth.
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 you’re armed with enough knowledge to feel comfortable with common SCORM language.
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:
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 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).
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.
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!
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.
score_raw & mastery_score:
These 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 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:
- The learner has scored something, i.e. score_raw has a value.
- The SCORM has set lesson_status to “completed”. It’s important to note that completed is different to passed. You might complete reading a book but that doesn’t mean you passed or failed! It’s possible to just complete some courses and pass or fail others, so the difference is subtle but important.
- The SCORM has a mastery_score associated with it.
- 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.
- 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 course. 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 your LMS vendor 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. 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.
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 mylms.somewhere.com and your course hosted on mycourse.overthere.com. 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. This is much better than relying on the server that hosts your LMS.
Hopefully you now understand what the SCORM API is, and how it works. SCORM is just one of many eLearning content formats, with newer formats like xAPI (Tin Can) and cmi5 continuing to be developed. If you have any questions on the SCORM API, share your thoughts sin the comments below.
