LMS Integration

Building a robust integration with SCORM Cloud as an LMS provider can be a daunting task at first. This document is a guide in accomplishing it.

We recommend at least skimming Concepts and API Quick Start before diving into this document.

IDs Are Yours

In SCORM Cloud, importing a course requires providing a course ID. Creating a registration requires providing a registration ID and a learner ID.

It’s your system’s job to create and manage these IDs. In SCORM Cloud, they’re stored as strings up to 255 characters long. Feel free to use integers or GUIDs or any other format you’d like. Many customers use their own database primary keys as the IDs in SCORM Cloud.

The course IDs and registration IDs are used in other API calls to affect those resources, so keeping track of them is important.

The learner ID tied to a registration is mostly opaque to SCORM Cloud, but it is used in some contexts in SCORM itself, so it’s important that it’s unique to a learner. The learner first name and last name are similarly opaque, but are also exposed via the SCORM API: courses may use the learner’s name to generate certificates of completion, for example, so it also should be accurate if possible.

Keeping System State

We strongly recommend keeping records of your registrations and courses in your own database tables as well as in SCORM Cloud. This enables you to track and report on data in your own system instead of pulling data from SCORM Cloud every time it’s needed – which will make your system faster and more robust against system failures.

It also enables your system to potentially override registration state. For example, SCORM Cloud does not have any way to forcefully mark a registration as complete or passed or set its score. LMS administrators typically expect this functionality, however, so it can be implemented by manually overriding the registration state in your own reporting table(s).

Importing Courses

Courses can be imported via CreateFetchAndImportCourseJob or CreateUploadAndImportCourseJob. As above, your system is responsible for creating and tracking the course ID used in the calls.

Both of the above methods are asynchronous and will return a job ID. When an import is pending, your system should periodically call GetImportJobStatus using that ID and check the status property. As per the documentation, if the status element has error, then the course failed to import for some reason – perhaps a user uploaded a file that wasn’t a ZIP file (i.e. not a learning package) by accident, for example. Otherwise, if it is finished (not still running), then the course import completed successfully.

On a successful import, you can display the course’s title (extracted from the uploaded package) to the user, as it’s returned by GetImportJobStatus. GetImportJobStatus also returns a list of parser warnings, which might not be useful to show the user, depending on the audience; the parser warnings are mostly only interesting to content creators who are making their own packages.

Creating Registrations

For a learner to take a course, a registration must be created against that course for that learner. This is done via the CreateRegistration API call. As above, the registration ID is your system’s responsibility to generate, and the learner ID, first name, and last name are all opaque to Cloud – only used for reporting and debugging.

When creating a registration, if the registration creation fails, your system should take care to remove the record of that registration from your database. This can be accomplished using database transactions if your database supports them (and if that makes sense in your integration).

Registration Creation Time

When your system should create a registration in SCORM Cloud can vary.

If your system has a notion of “assigning” a course to a learner, then when the course is assigned, a registration could be created. This matches the mental model of registrations – the assignment of a course to a user.

Alternatively, some customers have written their integration such that registrations are not created in SCORM Cloud until the learner actually launches the course. Their workflow goes something like:

if we have an existing registration for that user:
    launch that registration
else:
    create a registration in SCORM Cloud
    launch that registration

This has the advantage of possibly costing a little less if the learner never launches the registration.

Either way is fine.

Launching Registrations

Once courses are imported and your system has a way to store registration results, it’s time to launch those registrations.

The BuildRegistrationLaunchLink method returns a link that will take the user to the course content. Be aware of the expiry of the created links, if a link isn’t used within that time, it’ll become invalid.

Because the launch API call redirects the learner, it supports a redirectUrl parameter that tells SCORM Cloud where to redirect the learner back to when they’ve exited the registration. Therefore, your system should redirect the user to the launch API call URL with an appropriate redirectUrl. Once the user’s finished, depending on how they exit the course (more on this below), they will be sent to the redirectUrl, which points back at your website – maybe a page that displays their registration results. (This is a good place to call GetRegistrationProgress)

There is, however, one thing to be aware of:

Unreliable redirectUrl

The learner may never make it back to the redirectUrl specified in the launch request. As an example, once the learner is finished with their registration, they might just… close their browser. In this case, our content player will use its onbeforeunload handler to fire off a final state save, but the browser closing means that the learner won’t ever hit the redirectUrl.

As a result, your integration cannot rely on learners making it back to the redirectUrl page. This limitation is the primary reason that we stress using the registration postback feature, which is discussed below.

Getting Registration Results

As discussed in Keeping System State, your system should store its own version of the registration state to display to the user (and possibly to modify on its own if necessary). The question is then: how does one synchronize the registration state in SCORM Cloud with an application?

We recommend implementing a way to store the results of GetRegistrationProgress in your system for a given registration.

An ideal, robust integration uses this mechanism of storing the registration state in two different situations.

First, we very strongly recommend implementing an endpoint to receive registration postback (web hook) data from our system. When configured, SCORM Cloud will send the exact same data as GetRegistrationProgress whenever SCORM Cloud gets an update to that registration. In this way, your system receives updates about the registration state in near real-time. This creates a very robust implementation, since the registration state in SCORM Cloud is always POSTed directly to your system.

A detailed postback guide can be found at Registration Postbacks.

Postback requests are placed into a work queue before being sent to your endpoint. While rare, this can occasionally lead to postback delays if there is an exceptional amount of traffic in the queue. For this reason, we recommend incorporating a call to GetRegistrationProgress into your integration when up-to-date registration state is absolutely essential. The major use case here is when a learner is viewing the status of a course they just completed. When that page of your LMS is visited, a call to GetRegistrationProgress is appropriate. This also adds resiliency in the unlikely event that a postback outage occurs.