Compatibility Check for Uploading New SCORM Versions

1 Summary

When uploading a new version of an existing SCORM learning module, ILIAS performs a semantic compatibility check instead of requiring an almost byte-identical imsmanifest.xml. Non-functional differences such as regenerated identifiers, XML formatting or a different order of resource declarations no longer prevent an update, while changes that could invalidate existing tracking data, SCO assignments, sequencing or navigation continue to be rejected. If an installed version proves to be defective, a previously working SCORM package can be uploaded again and installed as the next version.

2 Problem Statement

ILIAS allows a new package version to be uploaded to an existing SCORM learning module. This is necessary when content errors, media files, layouts or other parts of the learning content have been corrected without replacing the learning module itself.

Keeping the existing ILIAS object is important because it preserves:

The current compatibility check requires the new imsmanifest.xml to be effectively identical to the manifest of the existing package. Only a few technical variations, such as encoding conversion and one historic namespace replacement, are considered.

Many authoring tools generate a new manifest whenever a package is exported. This can happen even if only an image, a spelling error or another piece of content was changed.

Depending on the authoring tool, a new export may contain:

These differences can cause ILIAS to reject the package even though the structure relevant to launching and tracking the SCORM content has not changed.

Users are then left with problematic alternatives:

The previous (and very old) feature request Smart module upload with minor changes already described this problem. However, the meaning of “minor changes” was not defined precisely enough to provide a deterministic and testable implementation.

A further problem occurs if a new package passes the compatibility check but later proves to be defective. Manifest compatibility cannot guarantee that HTML, JavaScript, media files and the internal application logic of the SCOs function correctly.

In such a case, administrators need a defined recovery procedure that restores the previously working content without creating a new ILIAS object and without discarding all existing tracking data.

3 Concept

ILIAS replaces the current textual comparison of the manifests with a semantic compatibility check.

The purpose of the check is to determine whether the new package can use the existing SCORM object and its existing tracking assignments without changing the logical structure relevant to the runtime environment.

The check does not attempt to determine whether all content changes made inside the SCOs are safe. It verifies compatibility at package and manifest level.

3.1 General workflow

When a person uploads a new version of a SCORM package, ILIAS performs the following steps:

If the check or subsequent processing fails, the existing package and all existing tracking data remain unchanged.

3.2 Semantic comparison

The comparison must not be based on raw XML strings. It must resolve identifiers and references before comparing the manifests.

For example, a resource identifier may change from RES-123 to RES-987. This does not make the package incompatible if all references can still be resolved unambiguously to the same logical resource, launch file and position in the activity structure.

For comparison purposes, ILIAS creates a normalized representation containing at least:

Identifiers are resolved to their logical targets. Their literal values are considered only where an identifier itself has runtime relevance or where an unambiguous mapping cannot be established.

3.3 Compatible differences

The following differences do not by themselves prevent the upload:

A difference is accepted only if it does not change the effective activity structure, launch behaviour or tracking assignment.

3.4 Incompatible differences

The following changes cause the upload to be rejected:

The comparison service may identify further runtime-relevant differences for the supported SCORM versions.

3.5 Comparison result

The result has one of three states.

3.5.1 Equivalent

No semantic difference relevant to ILIAS was found. The new version can be installed directly.

3.5.2 Compatible

Differences were found, but the activity structure and existing tracking assignments remain compatible.

ILIAS displays a summary of the accepted differences before installation.

The person can then select:

The summary should use understandable descriptions, for example:

3.5.3 Incompatible

The upload is rejected. ILIAS lists the differences responsible for the rejection, for example:

The existing package is not modified.

No Force Upload option is provided. A manual override would bypass the protection of existing tracking and structural data and would reproduce the risks of manually replacing files.

3.6 Installation of a compatible version

A compatible package is extracted into a temporary directory.

ILIAS completes all validation and preparation steps before modifying the active package. Only after successful processing is the existing extracted package replaced.

The replacement must ensure that:

Where compatible descriptive properties such as activity titles are updated, ILIAS uses the verified item mapping. The internal identifiers used by existing tracking records are retained.

3.7 Recovery from a defective package version

A successful manifest compatibility check cannot guarantee that the content of every SCO works correctly. An updated package may contain functional errors that are not represented in the manifest, such as:

It must therefore be possible to restore the content of a previously working package without creating a new ILIAS repository object.

The previously working SCORM ZIP package can be uploaded again using the regular Import New Version of SCORM Package workflow. It is checked against the currently installed package using the same compatibility rules and, if compatible, installed as the next package version.

This is a forward recovery and not a rollback of the version number.

Example:

The SCORM learning module, repository references, permissions and tracking data remain assigned to the same ILIAS object.

A package that has previously been accepted and replaced by a compatible package should normally also be accepted when uploaded again. The semantic compatibility comparison must therefore behave consistently in both directions.

Re-uploading a previously installed package is subject to the same validation, version detection, security and compatibility checks as every other upload. Previous successful installation does not bypass these checks.

This recovery procedure assumes that the person responsible for the module still has access to the previously working SCORM ZIP package. A dedicated package-version management interface is not introduced by this feature.

3.8 Effect on tracking data during recovery

Recovery restores the package content but does not restore an earlier state of the tracking data.

Tracking data created while the defective package was active remains stored. This may include:

ILIAS cannot generally determine whether this data remains valid after the previous package has been restored.

Where necessary, authorised persons must inspect or reset affected tracking data using the existing SCORM tracking functions.

The recovery procedure therefore provides a way back to the previously working package content, but it is not a complete rollback of all effects caused by the defective version.

3.9 Limitations

The compatibility check covers the package manifest and the structures known to ILIAS.

ILIAS cannot reliably determine whether changes inside an HTML or JavaScript SCO are compatible with existing runtime data. In particular, ILIAS cannot guarantee compatibility when an authoring tool changes:

The upload view therefore continues to inform users that the updated package should be tested with representative existing learner data before being deployed in a productive environment.

A successful compatibility check means that ILIAS has not detected an incompatible manifest-level change. It is not a guarantee that every internal state created by the authoring content remains valid.

3.10 Existing learning modules

Existing SCORM learning modules and their tracking data are not migrated.

The feature affects only the upload of a new package version. Packages with manifests that are already identical continue to be accepted.

The feature does not allow conversion between SCORM 1.2 and SCORM 2004. The version of the uploaded package must match the version of the existing learning module.

4 User Interface Modifications

4.1 List of Affected Views

The variable elements depend on the location and title of the learning module.

4.2 User Interface Details

4.2.1 Import New Version of SCORM Package

The existing upload form remains available.

It contains:

The explanatory text is updated. It no longer requires all manifest identifiers to remain unchanged.

Proposed explanatory text:

ILIAS checks whether the manifest structure of the uploaded package is compatible with the existing learning module. Technical differences such as regenerated identifiers may be accepted if activities, launch resources and tracking assignments can still be mapped unambiguously. Changes inside the SCOs cannot be evaluated completely. Test the new package with representative existing learner data before using it in a productive environment. 

If an installed package version proves to be defective, you can upload the previously working SCORM ZIP package again. ILIAS installs it as a new version while retaining the SCORM object and its tracking data. Tracking data created while the defective version was active is not automatically reverted.

4.2.2 SCORM Package Compatibility Check

This view is displayed if compatible differences were detected.

It contains:

If the package is incompatible, the same view displays:

No installation button is offered for an incompatible package.

4.2.3 Successful installation

After successful installation, ILIAS displays:

The new SCORM package version has been installed. The compatibility check found no changes that require existing tracking data to be reassigned.

The same confirmation is used when a previously working package has been uploaded again. The newly installed package receives the next consecutive version number.

4.2.4 Failed installation

If processing or installation fails, ILIAS displays:

The new SCORM package version could not be installed. The previously installed version remains active and has not been modified.

4.3 New User Interface Concepts

No fundamentally new UI concept is introduced.

Existing ILIAS components should be used for:

The compatibility status must not be communicated by colour alone. Each result is additionally presented as text.

A dedicated action for selecting and restoring an earlier package version is not part of this feature. Recovery is performed by uploading the previously working ZIP package again.

4.4 Technical Aspects

A dedicated manifest comparison service should be introduced in the SCORM components.

The service must:

XML Canonicalization alone is insufficient. It can normalize formatting and attribute order, but it cannot determine whether regenerated identifiers and their references describe the same logical SCORM structure.

For regenerated identifiers, matching should use stable semantic properties such as:

A mapping is accepted only if it is unique. Ambiguous mappings result in an incompatible classification.

The same comparison service should support SCORM 1.2 and SCORM 2004 while applying version-specific comparison rules.

If the feature “Automatic Determination of SCORM Version” is implemented, its version detection service should be reused. The uploaded version must match the existing object subtype before further comparison is performed.

Package validation and comparison must occur in a temporary area. Replacement of the active extracted content should happen only after all operations have completed successfully.

The active package directory must not be modified incrementally while the uploaded archive is being extracted. Otherwise, a failure could leave a mixture of old and new package files.

The implementation should prepare the complete new package separately and replace the active package only after successful validation. If replacement fails, the previous package must remain or be restored automatically.

The feature must not require changes to existing tracking records. A compatibility result that would require remapping tracking records must be classified as incompatible.

4.4.1 Symmetric compatibility

The compatibility relation should be symmetric for package structures classified as compatible.

If package A can be replaced by package B without changing the activity and tracking assignments, package B should normally also be replaceable by package A.

This property is required for the recovery procedure in which a previously working package is uploaded after a defective update.

Differences that are accepted only in one direction must be documented explicitly and must not prevent restoration of a previously installed package without a technically necessary reason.

4.4.2 Package archives and version numbers

Every successful upload receives the next consecutive module version number. Re-uploading an older package does not reset or reuse an earlier version number.

Previously uploaded source ZIP packages must not be overwritten by newer uploads using the same file name.

The implementation must assign each uploaded archive unambiguously to its module version. Existing package storage and versioning mechanisms should be used where possible.

The recovery procedure does not require an automatic selection of a previous archive from within ILIAS. The responsible person uploads the previous package through the regular upload form.

No new external service is required. The implementation should use the existing ZIP and XML facilities of ILIAS.

5 Non-Functional Implications

5.1 Security

The feature does not introduce a new endpoint or permission.

Uploaded ZIP archives and XML manifests remain untrusted input. Existing restrictions concerning upload size, archive paths and executable files must continue to apply.

XML parsing must not load external entities or access remote schemas. ZIP entries must be validated against path traversal and other unsafe paths.

The new package must be processed in a temporary directory. No file from the active package may be replaced before validation and compatibility checking have completed successfully.

An installation failure must not leave a mixture of files from the old and new package versions.

The compatibility report must escape all titles, paths, identifiers and other values obtained from the uploaded manifest before displaying them.

Re-uploading a previously installed package does not bypass any security validation. The archive is treated as untrusted input and checked again.

5.2 Privacy

The feature does not require additional personal data.

The comparison processes technical package and manifest data only. Existing personal tracking data is neither exported nor included in the compatibility report.

Existing tracking records are retained after a compatible package update or the restoration of a previous package. They are not reassigned or modified by the comparison itself.

Tracking data generated while a defective package was active is not automatically deleted or reverted.

Technical information about the comparison result may be written to the ILIAS log. It does not need to contain personal data.

5.3 Accessibility Implications

No specific accessibility problem is introduced.

The compatibility result and every identified difference must be available as text. Compatible and incompatible states must not be indicated through colour or icons alone.

Status messages, difference lists, warnings and action buttons must use existing accessible ILIAS UI components.

After an unsuccessful upload, keyboard focus should be moved to the failure message or compatibility result.

The information concerning recovery and the continued existence of tracking data must be presented as accessible text and must not depend on visual emphasis alone.

6 Process Information

6.1 Involved Authorities

6.2 Contact

Person to be contacted in case of questions about the feature or for funding offers:  {Please add related profile link of this person}

6.3 Funding

Funding status and funding parties are listed in the block 'Status of Feature' in the right column of this page.

If you are interested to give funding for this feature, please get into contact with the person mentioned above as 'Contact'.

7 Discussion

8 Implementation

Feature has been implemented by {Please add related profile link of this person}

8.1 Description and Screenshots

8.2 Test Cases

Test cases completed at {date} by {user}

8.3 Privacy

Information in privacy.md of component: updated at {date} by {user} | no change required

8.4 Approval

Approved at {date} by {user}.