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

Note: If you're unfamiliar with using Engine's API endpoints to import courses, you first should read the Importing Courses section before proceeding.

Course Version Number

When using a courseId for the first time, the course's version number begins at '0'. If you import again using the same courseId and mayCreateNewVersion parameter as 'true', Engine increments the course's version number by 1. To find the latest version number of a course, make a GET request to the /courses/{courseId} endpoint, and the response will contain a version property.

{
    "id": "fe067aed-0a1b-4778-8649-78e0e28040b8",
    "title": "Golf Explained - Run-time Advanced Calls",
    "xapiActivityId": "urn:uuid:66db02d0-e2cc-5793-a3db-3698c8b8f298",
    "updated": "2021-07-15T21:06:51.797Z",
    "webPath": "/EngineCourses/default/fe067aed-0a1b-4778-8649-78e0e28040b8/4",
    "version": 4,
    "activityId": "golf_sample_default_org",
    "courseLearningStandard": "SCORM20043RDEDITION",
    "launchable": true,
    "rootActivity": {...}
}

Registration Behavior

When Engine creates a new registration, it does so against the latest available course version. However, the behavior for how existing registrations launch is configurable. During the registration launch process, Engine decides whether or not to restart a registration's progress. The WhenToRestartRegistration setting defines when this restart should occur. Consequently, since Engine also restarts registrations against the latest course version, this setting also controls when an existing registration will switch from its current course version to the latest.

By default, Engine will only move a registration to the latest course version if it has already been marked as complete and a new course version exists. 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:

Note: Although it's understandable to think about WhenToRestartRegistration only in the context of course versioning, keep in mind that some WhenToRestartRegistration options do not require a new course version. Only half of the above setting values contain the AND_NEWER_PACKAGE_VERSION_EXISTS condition. If any of the other options are in effect (excluding NEVER), Engine would simply restart the registration against its current course version.

Registration Instance Number

While processing a registration launch, Engine evaluates the WhenToRestartRegistration condition. If met, Engine moves the registration to the latest available course version by creating a new instance of that registration. 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.

Keep in mind that Engine does not delete the old registration instance, and the original registration will remain intact and available in Engine's database. In this section, you learned about querying the API to retrieve the current state of a registration by using the /registrations/{registrationId} endpoint. To retrieve a previous instance of that registration, you can use /registrations/{registrationId}/instances/{instanceId}.

Notice that /registrations/{registrationId}/instances/{instanceId} takes an instanceId as part of the URI. The registration instance number is similar to a course's version number, but it tracks the "version" of a registration rather than a course. Therefore, when you create a registration and use a registrationId for the first time, the instance begins at '0'. If the WhenToRestartRegistration condition causes Engine to create a new registration instance, it increments this number by 1.

Whether you make a GET request to /registrations/{registrationId} or /registrations/{registrationId}/instances/{instanceId}, the response will always contain both instance and course.version properties.

{
    "id": "7bf957af-add0-4fbe-90f0-f1f0b932ffdd",
    "instance": 2,
    "updated": "2021-07-23T16:22:23.830Z",
    "registrationCompletion": "INCOMPLETE",
    "registrationSuccess": "FAILED",
    "totalSecondsTracked": 616.0,
    "firstAccessDate": "2021-07-21T15:46:06.060Z",
    "lastAccessDate": "2021-07-23T16:22:23.830Z",
    "createdDate": "2021-07-21T15:07:53.947Z",
    "course": {
        "id": "fe067aed-0a1b-4778-8649-78e0e28040b8",
        "title": "Golf Explained - Run-time Advanced Calls",
        "version": 5
    },
    "learner": {...},
    "activityDetails": {...},
    "registrationCompletionAmount": 0.0
}

Examples

There are two important points to be aware of when using Engine's versioning system, both of which have implications for your application's workflow.

• When setting course configuration through /courses/{courseId}/configuration, Engine applies settings to the latest course version only.
• When importing a new course version, Engine copies all course level settings from the previous version to the newly imported version.

The following scenarios illustrate the above points:

Example 1

Import a new course version and then later decide that you don't want existing registrations to restart:

• Import a new course (version 0).
• Use /courses/{courseId}/configuration to set WhenToRestartRegistration to WHEN_NEWER_PACKAGE_VERSION_EXISTS.
• Create a registration (instance 0).
• Launch and complete the registration.
• Import a new version of the course (version 1).
• After deciding that you do not want existing registrations to restart, use /courses/{courseId}/versions/{versionId}/configuration to set WhenToRestartRegistration to NEVER. Use '0' in the URI to replace the versionId placeholder.
• Re-launch the same registration. It will continue to use its original course version and will not restart on the new version.

Notice that after importing the second version of the course (version 1), we now have to specifically target the older course version with the /courses/{courseId}/versions/{versionId}/configuration API call in order to change the setting value. That's because the main /courses/{courseId}/configuration endpoint only affects the most recent version of the course (version 1 in this case), and our existing registrations were associated with the older version (version 0).

Example 2

Import a new course and decide that registrations should restart if a new course version is available.

• Import a new course (version 0).
• Use /courses/{courseId}/configuration to set WhenToRestartRegistration to WHEN_NEWER_PACKAGE_VERSION_EXISTS.
• Import a new version of the course (version 1).
• Create, launch, and complete a registration (instance 0).
• Import a new version of the course (version 2).
• Re-launch the same registration. It will restart on the new course (version 2) and have a new instance (instance 1).

It's important to note that the registration restarted because Engine copied the course configuration settings from one version to the next during the version 1 and 2 imports. You will continue to get the WHEN_NEWER_PACKAGE_VERSION_EXISTS behavior on new versions until you decide to change it again.

Updating Course Assets

There are times when you may want to update a single file in a course -- maybe to fix a spelling mistake or include a missing image. In that case it may not be desirable to upload the whole course package again and force learners onto a new version of the course. Engine has an endpoint for updating individual files of the course content.

Just as with importing full course packages, there are multiple ways to update course content assets. You can provide the new file either via a fetch request or via direct upload. Both methods may be used to either update the current course version, or any previous version (through the /courses/{courseiId}/versions endpoints). Updating course assets using either method has no impact on versioning of courses or registration instances/state.

For both methods of updating assets the result of a POST request sent to their respective resources will be a JSON object that indicates the filename and destination of the stored asset.

Posting the Asset File Directly

To import a course asset file directly, send a POST request to the /courses/{courseId}/asset/upload or /courses/{courseId}/versions/{versionId}/asset/upload resource in the API. The body of the request will have the contents of your asset file, and the Content-Type of the request should be multipart/form-data. Along with the file contents, the destination path relative to the root of the course content directory must be specified in the destination parameter.

For example, consider this full web path to an image that needs to be updated: /courses/default/fe067aed-0a1b-4778-8649-78e0e28040b8/0/Etiquette/course.jpg.

In this example, the root folder of the course is /courses/default/fe067aed-0a1b-4778-8649-78e0e28040b8/0, as Engine has created a folder based on the course id and version number. Therefore, the destination path to the file that's relative to the root of the course content would be Etiquette/course.jpg.

For additional protection against unintended overwrites or accidental creation of new files that may not be used by the course, the updateAssetPolicy parameter can be provided. By default the policy is lax, which means that Engine will not consider overwrites or new files as problematic.

Fetching the Asset File

An alternative to posting the content of the asset directly, assets that are hosted online can be fetched using a URL instead. To have Engine fetch a content asset, send a POST request to the /courses/{courseId}/asset or /courses/{courseId}/versions/{versionId}/asset resource in the API. Like with posting the asset file directly, the destination parameter specifies the location to save the asset relative to the root of the course content directory and is required. The updateAssetPolicy parameter may also be used as mentioned earlier.