Easy SCO Adapter for SCORM 1.2 to 2004
Run SCORM 1.2 SCOs in a SCORM 2004 LMS

Claude Ostyn, Ostyn Consulting
Version 1.0

Overview

In short

The Easy SCO Adapter for SCORM 1.2 to 2004 allows you to run any unmodified SCORM 1.2 conformant SCOs in a SCORM 2004 conformant LMS. It also allows you to integrate unmodified SCORM 1.2 SCOs into a SCORM 2004 manifest.

Why it is useful

It is most useful in situations where modifying or recreating SCOs is not economically feasible. When you use the adapter, the SCO believes that it is running in a SCORM 1.2 runtime environment, and the runtime environment believes that it is running a SCORM 2004 SCO. This is totally invisible to the user.

No special tool or knowledge of scripting is required to use this adapter. The adapter is a "black box" and it is invisible to the user. It does not require that the SCO be coded or constructed in any particular way. It does not require or assume that the SCO uses any particular script or technology. As long as the SCO is SCORM 1.2 conformant, the adapter will handle it automatically.

This adapter solves the major technical problem in upgrading content from SCORM 1.2 to SCORM 2004. The other problems are relatively inexpensive to solve, but they are beyond the scope of what this adapter can do; they involve updating the imsmanifest.xml file and metadata to conform to the schemas required by SCORM 2004, and inclusion of the new provided XSD files in the package. This process is well documented on the ADL web site. Modifying the manifest is usually much simpler than modifying even one single SCO.

How it works

The Easy SCO Adapter for SCORM 1.2 to 2004 is actually a SCO, although it is invisible to the user. When the SCORM runtime environment launches the adapter with a URL parameter that specifies another SCO, the following happens:

1. The adapter is launched as a SCO and initiates a communication session with the IEEE API instance provided by the SCORM 2004 RTE.
2. The adapter instantiates an API object and a stage frame that fits exactly within the stage frame provided by the RTE. The only sign of the presence of the adapter is a one pixel tall edge at the bottom of the browser window.
3. The adapter reads its URL parameters and gets the URL of the SCORM 1.2 SCO to launch
4. The adapter launches the SCORM 1.2 SCO in its own stage frame.
5. The SCORM 1.2 SCO finds the adapter´s API object and starts to communicate with it.
6. The adapter translates the SCORM 1.2 communication function calls to SCORM 2004 communication function calls, and reformats or synthesizes data as needed in the process.

How to use the adapter

Modifying the SCORM package

To use the adapter, you need to modify the manifest and add the adapter file to your package. If your package is "flat" and does not use nested folders, you can simply add the file to the other files in the package. If you use nested folders, use the modified manifest as a guide to determine where you need to put the adapter file in the folder structure of your package.

Modifying the manifest to use the adapter

In the imsmanifest.xml file for the SCORM package, each SCO is represented by a <resource> element, with a href attribute that specifies the URL to launch the SCO. The <resource> element also contains a list of files and other resources used to run the SCO. Each <resource> that describes a SCORM 1.2 SCO must be modified to launch the adapter instead of the SCO; this turns the resource into a SCORM 2004 SCO.

1. Modify the value of the href attribute by prepending the URL of the adapter and a sco parameter for which the value is the original URL. Refer to the example in Figure 2.
2. Add the adapter file to the inventory of files listed in the <resource> element. Refer to the example in Figure 2.

URL parameters

If the original url in the href attribute of the <resource> included parameters, just add them to the list of parameters in the new URL, as in the example in Figure 3. The entire query string to the right of "sco=" will be treated as the URL to launch the SCO. If there is a name conflict with an existing parameter, a preset string in the script of the adapter can be modified to specify a different parameter name than "sco".

Note how the & character used as separator between name=value pairs in the query string must be escaped as &amp; in the manifest file to respect XML syntax.

URL with anchor

If the original url in the href attribute of the <resource> includes a fragment or anchor identifier, the anchor separator (#) must be URL encoded as %23 because it is an unsafe character.

Relative paths

By default, the adapter uses its own path to create the URL to launch the SCO, unless the URL for the SCO is a fully qualified URL or the URL includes a relative path. If the URL includes a relative path, the adapter will treat it as relative to its own path. If your manifest is built with a nested directory structure, this may cause some difficulty. The easiest way to handle this is to just put the adapter in the same directory as the SCO itself. This may be less than optimal if you need to drop multiples copies of the adapter in multiple directories. However, depending on your situation, it may be easier than figuring out the proper relative path magic.

Platforms

The current release of the adapter has been tested in Microsoft Internet Explorer 6.0 and Firefox 1.5. If you intend to use it on other platforms you should test it carefully. The author welcomes test reports.

Known issues

The current release of the adapter has known issues, including:

• SCORM 2004 may preset objectives in the objective array if objective mapping is defined for the activity that uses the SCO. This may cause a problem with some SCOs that assume that they "own" the objective array and that the objective array will always be empty when launching a SCO. The adapter hides the issue from SCORM 1.2 SCOs by remapping the objective index as needed. However this may not work as expected if a SCO changes the identifier of an existing objective.
• The rarely used audio and speed data element values need to be translated from a linear to a logarithmic scale and vice-versa, but the current translation uses only a very crude placeholder for the necessary functions.
• The internal debug flag is only partially implemented. It is defined mostly to support custom modifications.
• When the adapter is launched, it contains an empty stage frame into which the SCO is to be launched. This frame´s background color is whatever the browser uses for an empty window. It is the same as when you go to the URL "about:blank".
• Because of a bug in Firefox, it is necessary to delay the launch of the SCO by ¼ second. The stage frame remains empty during this forced delay. The delay is not necessary in Internet Explorer.

Irresolvable specification issues

• There is no direct translation in the IEEE data model for the old cmi.core.lesson_status value of "browsed". If the SCO sets this value, it is currently ignored, leaving any existing value alone but returning "true" to the SCO.
• The SPM for cmi.suspend_data in SCORM 2004 is 4000, whereas it was 4000 in SCORM 1.2. If a SCO attempts to set cmi.suspend_data to a string longer than 4000 characters, this will typically fail in the SCORM 2004 environment.
  Note that SCORM 2004 - 3rd Edition is relaxing the SPM to a much larger value. This issue will not arise in a LMS that implements that larger SPM.

Differences between this adapter and the ADL wrapper

On the ADL web site at www.adlnet.org, you can download another adapter developed by the ADL technical team, the SCORM Version 1.2 to SCORM 2004 Conversion API Wrapper Version 1.1.

Like this adapter, the ADL Conversion API Wrapper "wraps" the SCO in a fake runtime environment that provides a logical translation layer. The main differences between the adapter described by this document and the ADL wrapper are:

• Less restrictive license than the ADL wrapper. The ADL license does not allow commercial use.
• In this adapter, the "wrapped" SCO is played in the same window or frame as any native SCORM 2004 SCO, whereas the ADL wrapper opens an extra window.
  Note: If the SCO is misbehaving you can try to use the ADL wrapper if this adapter does not work. A misbehaving SCO may attempts to manipulate the top window or it searches for the API in the wrong order. Such a SCO might work in the ADL wrapper because it uses a separate top level window.
• This adapter uses only a single file, whereas the ADL wrapper requires 3 files, which complicated deployment.
• The ADL wrapper has the benefit of government funded quality assurance resources. This is a private effort.

Download

Right-click here to download the esas2004.htm file (63KB). No other file is required to use this adapter with your SCOs.

Right-click here to download esas2004.zip (esas2004.htm file compressed in a 18KB zip file).

License

This document and the software described in this document are copyrighted but they may be used, distributed and modified freely under the terms of the LGPL (Lesser General Public License, http://www.gnu.org/copyleft/lesser.html). If you cannot live with the terms of the LGPL, please contact Ostyn Consulting at http://www.ostyn.com/contact.htm for special licensing terms.

Use at your own risk. The author and publisher of this document and of the described software shall not be responsible for any error, omission or any damage that may result from their use by you or anyone else. Publication of this document and of the described software does not imply a promise to update or maintain either of them in the future. By using this document or the software, you agree with these terms.

Customized versions of this wrapper can be ordered. You might need a customized version if you have SCORM 1.2 content that is not completely conformant, or if you need to adapt SCORM 1.1 or content that uses the AICC "API interface". A customized wrapper can sometimes fix those problems by judicious application of a little magic.