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)
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.

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 rejected an unsecured http request. Use hotbackup for testing.

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.

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.