Troubleshooting Steps

This is the recommended order to troubleshoot broken Scorm courses:

1. Check the Scorm version (see Troubleshooting SCORM Courses#SCORMVersion)
2. Check that the course link is published (see Troubleshooting SCORM Courses#CourseIsNotViewableByStudents) (only applies to 4.2.x)
3. Check the SCOId and Resource Id for invalid characters (see No Error (infinite loading) or "No Links Specified" in the LMS, fixed in 4.3.0)
   1. v4.5 only: verify the custom ScoId does not contain any periods or spaces (see )
4. Check the SCOManifest.js and ensure a SCOId is mapped (see Troubleshooting SCORM Courses#OldManifestMapping)
5. Check the browser's Console for errors and Network tab for external calls and or errors (including 3rd party cookies and if the course is using Flash).
   1. Note: Often, Scorm courses will cancel a web request for their entry point and then re-request it.  This is very common, and hasn't been known to cause any issues (and can be reasonably ignored as the problem):
      
6. Check the Scorm calls by debugging the Scorm course via the browser's Sources tab and setting break points in API.LMSGetValue and API.LMSSetValue in MarineLMS-SCORM-API.js (see Troubleshooting SCORM Courses#DebuggingAPICalls)
7. Try and import the Scorm course locally, and debug the extraction process to ensure the course contains activities and has a valid manifest (see Troubleshooting SCORM Courses#DebugtheScormExtraction(ImportScormcommand))
8. Check the package works outside the LMS by verifying the package on the Scorm Cloud (see Troubleshooting SCORM Courses#TestingthePackageExternally)

If all those steps fail, the issue will need to be escalated, and bounced back to the client/vendor; or new troubleshooting steps will be required.

Potential Pitfalls

Compression

The zip package must be compressed with the following options:

• 'compression method: deflate'
• 'dictionary size: 32KB'

Or you may get an error during LMS import.  The Microsoft library used by the LMS, that extracts the zip file, seems to only work with 32 bit compressed files.

SCORM Version

As mentioned on the Import SCORM Courses the only version support by our LMS is version 1.2.  This can be checked by opening the imsmanifest.xml in the root of the zipped SCORM package.

In the <metadata> tag there will be a <schemaversion> which should be 1.2.  If the version is incorrect, the client/vendor must re-package the course using the correct version:

Debugging API Calls

There have been instances where although a Scorm package version is seen as correct (with <schemaversion> 1.2) the package still uses other version standards.  They must be checked against https://scorm.com/scorm-explained/technical-scorm/run-time/run-time-reference/#section-2

Check the Scorm calls by debugging the course via the browser's Sources tab and setting break points in API.LMSGetValue and API.LMSSetValue:

The cmiElementName must match one of the switch cases.  For example, the Scorm 1.2 standard is cmi.core.lesson_status but the cmiElementName shows as cmi.success_status (the Scorm 2004 standard).  This means the package was generated/compiled incorrectly, and must be bounced back to the client/vendor.

Additionally, ensure the API is reachable/able to initialize. If it is missing, it will manifest as an error when loading the Scorm course:

 --> 

This can be quickly checked as the console will output an API Not found error. With the Scope set to top in the Console, type API to view the object and check for values:

If the mapping is null, check the SCOManifest.js (see next section).

Old Manifest Mapping

When the SCORM course is imported into the LMS, a number of files get generated including a manifest (SCOManifest.js).  This file is used to map the SCO Id, and other information desired (Currently supports: mastery score, time limit, and launch data.  See: SCORM Data Model).

There are 3 keys that could be used by the SCORM course, depending on how the vendor created/set it up (Note: These entry point names, e.g. index_lms.html, can also vary depending on the vendor. The entry points are mapped as the href in the <resource identifier> tag in the imsmanifest.xml in the root of the package zip):

• index_lms.html
• index_lms_html5.html  
• index_lms_flash.html - NO LONGER SUPPORTED AS OF DECEMBER 2020

It is possible that the packaged course either forces use of one of these, or uses browser detection to deliver the content in the respective type.  However, at the moment, the SCOManifest.js specifically sets 'index_lms.html' (see ExtractScormPackage() in CoreClient.cs), the consequence of this is that if the course is html5 or flash, the CurrentSCO and CurrentSCOId properties will not usually be set correctly.  This can lead to unforeseen consequences and other bugs.

To resolve this, after the course has been imported, navigate to the file collection, then the course.  Edit the SCOManifest.js, and change the 'SCOIDMapping' and 'SCOManifestMapping' to the appropriate key:

Note this does support multiple entries for backwards compatibility.  E.g.:

var myAPI = getAPIHandle();
if (!myAPI) { console.log("Mapping: Could not find API"); }
else{ console.log("APIFOUND");
myAPI.SCOIDMapping = {};
myAPI.SCOManifestMapping = {};
myAPI.SCOIDMapping["index_lms.html"] = "__6LMdt51ovdV_course_id_RES";
myAPI.SCOManifestMapping["index_lms.html"] = {"id":"__6LMdt51ovdV_course_id_RES","timelimitaction":"ContinueNoMessage"};
myAPI.SCOIDMapping["index_lms_html5.html"] = "__6LMdt51ovdV_course_id_RES";
myAPI.SCOManifestMapping["index_lms_html5.html"] = {"id":"__6LMdt51ovdV_course_id_RES","timelimitaction":"ContinueNoMessage"};
}

New Manifest Mapping

As of version 4.0.x a new manifest mapping has been created and is used on any importScorm commands after 4.0.  This is to prevent manual mapping of the multiple entry points (e.g. index_lms_html5.html) in the SCOManifest.js after import.  The new SCOManifest.js should still have a value mapped after import (lines 6 and 7):

var myAPI = getAPIHandle();
if (!myAPI) { console.log("Mapping: Could not find API"); }
else{ console.log("APIFOUND");
myAPI.SCOIdFromManifest = {};
myAPI.SCODataFromManifest = {};
myAPI.SCOIdFromManifest = '__6g7FD8imvYA_course_id_RES';
myAPI.SCODataFromManifest = {"id":"__6g7FD8imvYA_course_id_RES","timelimitaction":"ContinueNoMessage"};
}

Common Errors

Illegal Characters in Path

As of 4.4.0 a new command has been added to check the file names for illegal characters. Example:

Executed Command:
CheckScormPackageForIllegalFileNames  G:\temp\Restaurant College Module 3\imsmanifest.xml

Potentially problematic file names:
scormcontent/assets/SmmU578JI3PILR8g_transcoded-P77p2VQ6Zr8Yh-Uf-Saute%C3%A9d%20Beans.mp3

Before 4.4.0 this manifests as:

Executed Command:
importScorm  G:\temp\Restaurant College Module 3.zip /Root/Carnival/CCL/test Test C0902

Read Zipped Package: 'G:\temp\Restaurant College Module 3.zip'
Read Scorm manifest settings.
Unexpected exception in ImportScorm: This package could not be opened. More information:

Run the command locally against the imsmanifest.xml to find problematic files.  Once found, rename the asset on disk, and update the imsmanifest.xml reference with the updated file name (with the offending character removed).  Re-zip and importScorm again.

File Reference Not Found During Search:

In some cases, SCORM courses built with different course creation tools may encode file names as Base64 strings. As a result, searching by file name might not return results.

Resolution: 

1. Get the base 64 string it is usually located here "scormcontent\locales\und.js"
   
   
   
   This file contains base 64 string which looks like this: __resolveJsonp("course:und","SBase64String")
2. Decode the Base64 string using an online tool (e.g., https://www.base64decode.org).
3. Update the file name to include only valid characters.
4. Re-encode the file name as Base64 and update it in the course files.

Invisible Invalid Characters in File Names:

At times, the file name might appear valid at first glance, but SCORM validation commands can flag hidden invalid characters.

For example, the sequence %E2%80%8B represents a zero-width space (Unicode character U+200B), which can cause issues. Following file contains invisible illegal character.

Resolution:

1. Rename the file to remove the invalid characters.
2. Update all references to the renamed file within the SCORM package.
3. Use the CheckScormPackageForIllegalFileNames command to identify and address such issues.

No Error (infinite loading) or "No Links Specified" in the LMS

We have seen an error where invalid characters in the SCO Resource Id have caused our 3rd party extractor to silently ignore the resource/course and not give any error (This is fixed as in 4.3.0 COREDEV-4797 - Getting issue details... STATUS ).  Ensure that no special characters are being used for the SCO Id in the imsmanifest.xml:

Note: Reserved html characters should be viewed with suspicion.  To fix this issue, remove the offending characters, and re-zip the packaged files with a new name, and re-import the course to the LMS.

No Error (infinite loading) alternative

We have also seen rare instances (e.g. NCLH) of Scorm course making external calls.  Normally this is not supported, but we have made exceptions (specifically for NCLH).  This can be seen in the Network trace in the developer window. It will manifest as 403 or 404 errors, and in rare cases, a Content-Security-Policy exception:

Note this has been fixed on NCLH by changing the CSP to use frame-src instead of script-src and whitelisting cloud.scorm.com. Additionally, this must be tested with https as external sites (e.g. cloud.scorm.com) will reject an unsecured http request. Use hotbackup for testing.

v4.5 Only: Custom ScoId is missing characters (period or space)

There is an issue with v4.5 removing periods or spaces from the custom ScoId stored in the LinkAttribute value.  If a period or space is desired as part of the custom ScoId, import the course as normal with the desired custom ScoId, then follow these steps:

• Go to the actual Scorm course
• Open DevTools, and click the Console tab
• paste this in chrome's dev console (with the scope set to 'Top')
  $('.navbar.navbar-fixed-bottom').attr('style','display:block !important');
• The admin bar should now be visible.  Click on Edit > Links.  
• Right click the link and select Edit > Attributes
• Manually add the period (or space) to the value of the mls_sco_id attribute and hit save.
• 

Course Is Not Viewable By Students

There is currently an issue on 4.2.x with the importScorm command, caused by  COREDEV-4936 - Getting issue details... STATUS .  To fix this: 

• After running importScorm, navigate to the course itself (final link).
• Before changing the template to the SCORM course template as you normally do, you need to Edit > Links > Publish the link.
  
• Then you can change the template to the proper SCORM template. (Edit > Page > Change Template)

Currently the SCORM templates (at least SCORM.Course.Simple.cshtml) don't seem to be aware of this and so no error is shown anywhere in the console or network trace.

Debug the Scorm Extraction (ImportScorm command)

When debugging the ImportScorm command the first break point should be set in CoreClient.Scorm.cs on line 183 (CreateManifestJSFile()). If the sco_resources count is 0, the course either has multiple child activities (which isn't supported until 4.2.x COREDEV-4876 - Getting issue details... STATUS ), or the manifest is incorrectly made/formatted.  If this method is unable to find any sco resources, the package is improperly made, and must be checked on Scorm Cloud (see next section) and/or bounced back to the client/vendor.

Known Issues with Extraction

Recently we have seen an issue were the identifier for the <item> within an <organization> used a Guid which was too long and therefore would fail trying to find the Activity.  Adjust the identifer to something smaller and re-zip the package.  E.g.:

Scorm 2004 Standards

Sometimes, when a course is repackaged for Scorm version 1.2, it may still contain Scorm 2004 pieces, almost always as xml tags in the imanifest.xml at the root of the scorm package. Example:

<?xml version="1.0" ?>
<manifest identifier="com.scorm.manifesttemplates.scorm12" version="1"
       xmlns="http://www.imsproject.org/xsd/imscp_rootv1p1p2"
       xmlns:adlcp="http://www.adlnet.org/xsd/adlcp_rootv1p2"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.imsproject.org/xsd/imscp_rootv1p1p2 imscp_rootv1p1p2.xsd
                           http://www.imsglobal.org/xsd/imsmd_rootv1p2p1 imsmd_rootv1p2p1.xsd
                           http://www.adlnet.org/xsd/adlcp_rootv1p2 adlcp_rootv1p2.xsd">

	<metadata>
		<schema>ADL SCORM</schema>
		<schemaversion>1.2</schemaversion>
		<imsmd:lom>
      		<imsmd:general>
         		<imsmd:title>
             		<imsmd:langstring xml:lang="en-US">Inlingua Language Test English</imsmd:langstring>
         		</imsmd:title>
         		<imsmd:description>
         			<imsmd:langstring xml:lang="en-US">Language placement to test your language level according to the Common European Framework (CEF) of the Council of Europe.</imsmd:langstring>
         		</imsmd:description>
         		<imsmd:keyword>
         			<imsmd:langstring xml:lang="en-US">Englisch, English, language, placement, test</imsmd:langstring>
         		</imsmd:keyword>
      		</imsmd:general>
  		</imsmd:lom>
	</metadata>

	<organizations default="Inlingua Rostock">
		<organization identifier="Inlingua Rostock">
			<title>Inlingua Rostock</title>
			<item identifier="language test" identifierref="InlinguaSCO">
				<title>Language Test English</title>
			</item>
		</organization>
	</organizations>

	<resources>
		<resource identifier="InlinguaSCO" type="webcontent" adlcp:scormtype="sco" href="InlinguaSCO/index.html">
			<file href="InlinguaSCO/index.html"/>
		</resource>
	</resources>

</manifest>

The above will fail to be imported and the exception thrown from importScorm should indicate the position of the invalid tag:

Invalid package: The package contains a manifest that contains badly formed XML.  Inner Exception: System.Xml.XmlException: 'imsmd' is an undeclared prefix. Line 13, position 4.

See: https://scorm.com/scorm-explained/technical-scorm/content-packaging/manifest-structure

cmi.core.score.min is not implmented/supported

We have no place to store “min” in our model. Our SRA modal has no notion of a “min” value.

We could implement the entry point as a no-op, which would sort of be a lie, and the course might still fail later if it tried to retrieve the min value (because we would not be able to return the same value as was passed in to the ‘set’ call).

Talk the course vendor and say that we don’t support ‘min’ and see if they can make it optional in the course.

Testing the Package Externally

Sometimes, normal troubleshooting in the LMS may not yield any explicit errors, and the package must be verified outside of the LMS. This can be tested on the Scorm Cloud.

Create a SCORM Cloud account

You can sign up for a free trial anytime, keeping in mind though that once you cross the storage limit of 100 MB, you will be charged for consequent usage. 

SCORM Cloud is a tool that can be used to evaluate the behavior of a SCORM package. You can use it to test if your SCORM content can be uploaded and launched successfully, you can view the SCORM content, and you can test to see what sort of completion data the SCORM content reports.

1. Go to SCORM Cloud.
2. Click Try it free.
3. Complete the sign-up form.

Note: if using the free version, and your package is greater than 100MB it's likely there are big asset file (e.g. videos) in the package.  Delete/remove those videos to get the package below the 100MB trial threshold.  The course can still be tested; the SCORM Cloud may hang for a second or two looking for the missing asset, but you will be able to continue as normal.

Reviewing your SCORM content in SCORM Cloud

You will need to locate the original zipped file of your SCORM content before completing this step.

• Importing your content

1. Log in to your SCORM Cloud account, if necessary.
2. Click Add Content in the top right.
1. Select Import a SCORM, AICC, xAPI or cmi5 package.
3. Change the Import to a specific App menu to Initial Application for [your name]’s Realm.
4. Click Choose File and navigate to your copy of the ZIPPED SCORM package.
5. Click Import Course. 
   
   You will see a progress window while your content loads.
6. Verify your content uploaded successfully.
1. Scroll down to the Course Assets section and verify you can see the "Congratulations, your manifest looks great!"
   
2. If you do not get this confirmation, you will probably need to re-package your original SCORM content.

Viewing your SCORM content

1. Click Launch (you may need to scroll back up) and review your training.

Testing SCORM package for completion

1. Review your SCORM content completely.
   1. Complete all activities correctly so you can test that successful progress through the content will be reported as successful progress.
   2. Close the SCORM window when you are done, if necessary.
   3. SCORM Cloud reloads and presents you with the results.
2. Review your results:
   1. You should see Complete in the Completion area. If there is any quizzing an appropriate percentage would be viewed under Score or both.
      
      

Testing SCORM package for non-completion

1. Click Reset Progress.
   
   
2. Review your SCORM content incorrectly. You may wish to try this multiple times, in a variety of ways.
   1. Try leaving the SCORM content after going through just a few slides.
   2. If the SCORM has quizzes, try answering incorrectly.
   3. After each failed attempt, close the SCORM window when you are done.
   4. SCORM Cloud reloads and presents you with the results.
3. Review your results:
   1. You should see Incomplete under Completion if you have not gone through the entire SCORM content.
      
      

You should see the appropriate percentage under Score for whatever quiz answers you provided.