SCORM launch data explained

What is SCORM launch data?

SCORM launch data is a short string the course author writes into the package manifest for one item, which the LMS hands to that SCO at runtime as cmi.launch_data. It lets a single SCO behave differently depending on where it sits in a course, without the content being rebuilt for each position.

The mechanism is simple. The manifest carries the string. The LMS stores it with the item at import, and when a learner launches that item it makes the string available through the runtime API. The content reads it once and decides what to do with it. SCORM says nothing about what the string contains or how it is structured; that is between the author and the content.

It is the only channel SCORM gives an author to pass configuration from the manifest into a SCO. Everything else the content reads at launch — learner name, previous score, suspend data — is about the learner or the attempt. Launch data is about the item, and it is the same for every learner who opens it.

Setting it in the manifest

The string goes on the <item> that launches the SCO, not on the <resource>. That placement is the whole point: one resource can be referenced by several items, and each item can carry different launch data. The general layout of the file is covered in imsmanifest.xml explained; here is the one element that matters.

In SCORM 1.2 the element name is all lower case:

<item identifier="item_1" identifierref="res_player">
  <title>Module 1: Fire safety</title>
  <adlcp:datafromlms>module=fire-safety&amp;mode=assess</adlcp:datafromlms>
</item>

In SCORM 2004 the same element is camel case:

<item identifier="item_1" identifierref="res_player">
  <title>Module 1: Fire safety</title>
  <adlcp:dataFromLMS>module=fire-safety&amp;mode=assess</adlcp:dataFromLMS>
</item>

Three things go wrong here most often:

• Case. XML element names are case-sensitive. adlcp:dataFromLMS in a SCORM 1.2 manifest, or adlcp:datafromlms in a SCORM 2004 one, is an unknown element. Some LMSs reject the import; others ignore it and the SCO receives an empty string.
• Escaping. The string is XML text, so & must be written as & and < as <. A raw ampersand in a query-style string makes the manifest malformed, and a malformed manifest fails at import before launch data is ever a question.
• Order. Both versions define a fixed order for an item's child elements, with launch data coming after the title, any child items and the metadata. Strict validators reject an item that puts it first.

Keep it short. SCORM 2004 sets the smallest maximum an LMS must support at 4,000 characters, and the SCORM 1.2 manifest element is defined with a smaller 255-character minimum. An LMS is only obliged to preserve that much, so a long block of configuration belongs in a file the content loads itself, with launch data carrying only the key that selects it.

Reading cmi.launch_data at runtime

Once the session is open, the content reads the value with a single call. In SCORM 2004 that is GetValue; in SCORM 1.2 it is LMSGetValue. The element name is cmi.launch_data in both versions, which is unusual — most of the data model was renamed between them. The calls themselves are described in the SCORM API explained.

Initialize("")                        → "true"
GetValue("cmi.launch_data")           → "module=fire-safety&mode=assess"
GetValue("cmi.entry")                 → "ab-initio"

It is read-only. The content cannot change its own launch data. A SetValue on cmi.launch_data fails — error 404 in SCORM 2004, error 403 in SCORM 1.2 — and the stored value is untouched. If a SCO needs to remember a choice the learner made, that is what cmi.suspend_data is for. Launch data is configuration going in; suspend data is state coming back.

It has no defined format. The specification types it as a plain string and stops there. The content decides how to parse it, which means the content also has to decide what to do when parsing fails. Three conventions cover almost every real package:

Whichever convention a package uses, the content should read the value straight after Initialize, parse it defensively, and fall back to a default when the string is empty or does not parse. An empty string is the normal answer when the manifest defines nothing, and in SCORM 2004 it comes back without an error, so the error code cannot tell "not set" from "set to nothing".

What can you use it for?

The common thread is one piece of content that needs to know which of several jobs it has been given. Without launch data the usual answer is to duplicate the SCO once per job, which multiplies package size and means every fix is applied several times. With it, one resource serves every item.

Selecting a module. A course of eight modules can ship one player and eight items, each pointing at the same resource with a different launch string. The player reads the string, loads the matching module, and reports completion for the item that launched it. The organisation in the manifest still shows eight entries, so the LMS tracks eight statuses, as it would for eight separate SCOs. How an item and a SCO relate is covered in what is a SCO.

Setting a mode. The same assessment can run as practice in one item and as a scored test in another. The launch string tells the content whether to show feedback after each question, whether to write a score, and what pass mark to apply. The questions and the player are built once.

Configuring a shared player. Organisations that publish many courses through one in-house player often pass it a content identifier, a language, or a feature switch this way, so the player is never edited to add a course.

There are also things it is not good for. It is not secret: the string is in the manifest and visible in the browser's developer tools at runtime. It is not per-learner: every learner who launches the item gets the same string, and it cannot be varied from the LMS side without re-importing. And it is not sequencing: launch data tells a SCO how to behave, not when the LMS should launch it.

Checking that your LMS passes it

Everything above assumes the LMS reads the element at import and returns it at runtime. The specification requires both, but support in practice varies. Some platforms read it from a SCORM 2004 manifest but not a SCORM 1.2 one, or the other way round. Some trim whitespace, some apply their own length cap, and a few ignore the element and always return an empty string. A package that depends on launch data has to be tested in the platform it is going to, because a fallback that silently picks the default module looks like a working course until someone notices that every item shows module one.

The test is quick:

1. Import the package and launch an item whose manifest entry carries launch data.
2. Open the browser console or the LMS's SCORM debug log and find the GetValue("cmi.launch_data") call, or make the call yourself from the console against the API object the content found.
3. Compare the returned string with the manifest, character for character. Watch for a stripped ampersand, collapsed whitespace, or a truncated tail.
4. Launch a second item that references the same resource with different launch data, and confirm the returned string changes. This is the case that catches an LMS which stores launch data per resource rather than per item.
5. If the LMS returned an empty string, check the import first. Look for the element in the uploaded manifest and for any import warning about unknown elements before assuming the runtime is at fault.

Do this once per target platform and per SCORM version, and keep the result with the package. If a platform does not pass launch data through, the fix is on the content side: give the SCO a second way to learn its job, such as a per-item launch file that sets a variable before loading the shared player. Launch data is the cleanest route, but it is only as reliable as the LMS between the manifest and the SCO.

Where SCORM Central fits

SCORM Central turns PowerPoint, PDF, and video files into SCORM 1.2 or SCORM 2004 4th Edition packages you can edit in its course builder, and its free tester shows the manifest checks and every runtime call a package makes before an LMS sees it. See how it works, or test a package free.