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.
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).
Both of the above methods are asynchronous and will return a job ID.
When an import is pending, your system should periodically call
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.
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.
Getting Registration Results
As discussed above, 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 as soon as they’re made. 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.
Second, we recommend building a way to force your system to call GetRegistrationProgress to refresh a given registration’s state in your database. Although postbacks are designed to be highly reliable, this manual refresh process could be useful.
Once courses are imported and your system has a way to store registration results, it’s time to launch those registrations.
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
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
by the way, supplementing registration postbacks.)
There is, however, one thing to be aware of:
The learner may never make it back to the
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; there’s simply no other way to get (near-real-time) registration results reliably.