Importing Courses into Engine

E-learning courses are usually distributed in a self-contained unit called a "package", typically in the form of a ZIP file. Although the structure of a package varies between the different learning standards, you usually don't have to know about these differences when working with Engine.

To launch a course in Engine, you first have to make Engine aware of your course by importing it. For most customers, importing a course into Engine is as simple as uploading the ZIP file package and letting Engine handle the rest.

However, Engine does support a variety of other ways to import your courses, such as providing the path to a course already extracted somewhere, or the URL to download the zip file. You can read about those import methods below, but for now, let's stick to the most common import behaviors.

Importing by ZIP

An important distinction to understand is that Engine does not host your course content files. When Engine imports a course, it will just unzip the course, parse and record its details according to the appropriate learning standard, and drop the course files onto your content server. Unless you want to use Engine's remote hosted player, you should ensure that your content server is on the same domain as Engine, or else Engine's player will be inhibited by browser same-origin policies.

Required Settings

There are a few settings that you'll need to configure for this type of import process to work correctly:

• FilePathToUploadedZippedPackage - This setting should be the directory that Engine can use as a place to temporarily store the ZIP files while they are being imported. They will be deleted after the import process is completed.

• FilePathToContentRoot - The directory to which Engine should extract the contents of your courses. Within this directory, a folder for each course will be created. The name of the course folder will be based on your course id, and a subfolder under that for the version (e.g., /mycourseid/0).

  Note: This directory should be hosted by a web server so that all of your course content is accessible to your learners in the browser.

• WebPathToContentRoot- Engine uses this value to calculate the web path to a course's content once it has been imported. This should be the URL where the directory you specified in FilePathToContentRoot is being hosted. This value is often a relative URL for the current domain (e.g. /courses/content/), but can also be a fully-qualified URL (e.g. http://example.org/courses/content/) if needed.

Posting the ZIP File Directly

Once you've set those values, you can import a course by sending a POST to the /courses/importJobs/upload resource, taking special note of the courseId query string parameter. This parameter should provide a unique identifier for the course being imported.

The body of the request will have the contents of your zip file, and the Content-Type of the request should be multipart/form-data.

Have Engine Download the ZIP File

If you don't want to POST the contents of your course directly to Engine, you can also have the import process fetch the ZIP file itself. To do this, you need to host the course on a web server that Engine can access or on the server's local file system. Once you've done that, you can POST a JSON object (as Content-Type application/json) to /courses/importJobs endpoint with a url pointing to the location of your zipped course file.

Checking Import Status

It's important to note that when you call the importJobs endpoint through one of the methods above, the course is not immediately ready for use. Since the processing of a course package may take a while, Engine will queue the import job to process it asynchronously and will return a job ID to you in the response.

You should verify that the import job completed successfully before trying to launch it. There are two main ways to do that:

• Using the job ID that was returned to you, check the status by querying the /courses/importJobs/{importJobId} resource in the API. You may have your UI wait while it periodically checks to see whether the job is finished before continuing.
• Alternatively, you could have Engine update your application directly when the import is finished. If you set the value of ApiImportResultsPostBackUrl to the URL of an endpoint in your application, then Engine will POST a JSON object describing the results of the course import whenever an import has been completed.

Updating Courses

If at any point you need to update something about your course, you can always upload a new version of the package. To do this, just import your course as normal while specifying the ID of the existing course that you want to update with the course query parameter. You must also specify a second parameter named mayCreateNewVersion with a value of true. That will tell the import process to use the uploaded package as the new version of the specified course.

New registrations against a course will use the latest course version. The behavior for existing registrations, however, is configurable. To configure when existing registrations will switch to using the new version of the course, you will need a setting named WhenToRestartRegistration.

By default, we only move registrations to a new version ifthe registration has already been marked as complete. Otherwise, it stays on its original course version.

If that behavior doesn't work for your application, you can review the other possible values for WhenToRestartRegistration below:

One word of caution: whenever Engine moves a registration to a newer version of the course, a new instance of that registration will be created. To a learner, this will effectively reset their progress in the course. Versioning works this way because it's possible that the structure of the new version may not be compatible with the saved data for the old version.

Advanced Import

Importing by Manifest

If your application is already handling the ZIP extraction and the course content is already hosted on a web server, then you can simply point Engine to the manifest of your course and import from that.

To do this, you will POST a JSON object to /courses with the referenceRequest property set to an object containing two values:

• the url property should point to a SCORM/xAPI/cmi5 manifest or one of the AICC course structure files
• the webPathToCourse should provide the URL to the root directory of the course's content. This can be an absolute path (e.g., /courses/myCourseOneFolder) as long as it lives on the same domain as Engine's player.

Example:

{
    "referenceRequest": {
        "url": "http://example.org/courses/mycourse/imsmanifest.xml",
        "webPathToCourse": "http://example.org/courses/mycourse"
    }
}

Since Engine is not handling the actual content files for the course (only the manifest), you must ensure that the content is already available at the path specified.

Unlike the importJobs endpoints, importing by manifest will run synchronously . This means that you won't have to wait for the import job to complete -- the HTTP request will not return until your manifest has been imported.

Ad Hoc Import

You can sometimes have e-learning content that lives on a web server somewhere, but you do not have an actual zip package with a manifest inside it. This is much more likely with standards like AICC or xAPI where the content can communicate directly back to Engine outside the context of a 'player'.

Engine has a way to 'import' a course such as this so that you can launch and track it along with your normally imported course zip packages.

To do this, you will have to POST a JSON object to /courses and include the adHocReferenceRequest property.

Here is an example of what this object could look like and a brief description of what value each of these properties should have.

{
    "launchUrl": "http://example.com/courses/tenant-21048/RuntimeBasicCalls_SCORM12/shared/launchpage.html",
    "webPathToCourse": "http://example.com/courses/tenant-21048/RuntimeBasicCalls_SCORM12/",
    "learningStandard": "scorm12",
    "title": "Golf Example - SCORM 1.2"
}

• launchUrl - The URL of the launch page of the course.
• webPathToCourse - The root folder of the course's content. This is folder that a course manifest would go in, if one existed.
• learningStandard - The learning standard of the course being imported. Acceptable values are aicc, scorm11, scorm12, scorm2004,scorm20042ndedition, scorm20043rdedition, scorm20044thedition, tincan, and cmi5 (values are case insensitive, and Engine will ignore any spaces in the name).
• title - The title of the course. Will used as the

Using the course that you've described in the JSON body, Engine will generate a placeholder manifest in memory and import your course using that. Like importing with a manifest, an ad-hoc import will run synchronously.

Validating a Course Zip or Manifest

Before importing a course for real, some customers like to validate that the to-be-imported course is, in fact, valid and would be imported successfully.

Engine provides a parameter named dryRun that you can pass (with a value of true) to any of our synchronous import methods (i.e., POST to /courses or /courses/upload). When you set this to true, Engine will not extract your course files to FilePathToContentRoot or save any course information to the database. It will only check that the manifest file is valid for its learning standard and that the course would be imported without issue.