Breaking Changes in Engine 2018


Rustici Engine 2018 is finally here! While we're excited to share this new release with our existing Rustici Engine customers, we need to make sure that everyone understands what to expect when upgrading to this new version.

A lot of improvements have been introduced this year, but some of them are a departure from existing behavior. Where possible, we offer the ability to stick with your expected behavior, if you prefer the old way of doing things. Please see below for a description of what has changed and what might be required of your team.

Along with the changes listed here, we've also changed a few of the method signatures that you can override in your integration layer (applicable to non-API integration customers). I've left those changes out of this article because our support team will update those files for you as part of the upgrade process. If you'd like to know the details of these changes, feel free to reach out to our team by emailing us at 

A Rose By Any Other Name

As you may have noticed on our website, the product formerly known as SCORM Engine is now called Rustici Engine. Along with that change, we've also renamed a couple of things in Engine.

The first thing you'll see is that the actual web application has been renamed from ScormEngineInterface to just RusticiEngine. If you want to keep the old name, you can rename the war file on Java, or rename the application folder on .NET (or just make sure to point your IIS application to the new folder). Along with that change, you should rename your Engine config file (which has traditionally been named for Java customers and SCORMEngineSettings.config for .NET customers) to or RusticiEngineSettings.config

Also, we have renamed the default endpoint that Engine's LRS is hosted under. In previous versions of Engine, we used the endpoint "/TCAPI", which was an acronym for Tin Can API. We've decided to take this product rename as an opportunity to modernize this endpoint to the more up-to-date "/lrs".

If you'd like to continue to host Engine's LRS under the path "/TCAPI", then there are two changes you'll need to make:

  • Add the "xAPIUrlPrefix" setting to your config file, and set it to "TCAPI".
  • On Java, change the web.xml file's mapping for the TCAPIServlet to use the "/TCAPI/*" path instead of "/lrs/*".
  • On .NET, change the web.config so that any reference to "lrs" in the handlers/httpHandlers refers again to "TCAPI".

If you have any xAPI statement pipes currently pointing to the /TCAPI endpoint, then renaming the LRS endpoint to /lrs will break them. We suggest either updating these pipes to point to the new endpoint or setting up some sort of rewrite rule on your server to redirect requests for /TCAPI over to the new /lrs endpoint.

.NET Engine customers:

Make sure to take a look at the web.config included in your new version of Engine and apply any changes that we've made in the release to your own web.config. This is true of every major release, but it is particularly important in this case because of the number of changes made. 

If your team has not made any changes to Engine's default web.config, then you should just replace the old Engine web.config with the one included in the latest release every time you upgrade to make sure that you have the most up-to-date configuration.

The V2 API & Tenant Management

In past versions, Engine would automatically create tenants as they are referenced through the API. However, when designing version 2 of the API, our team decided that tenants are too important a resource to create automatically, or possibly even accidentally. When everything that can be done in Engine is done inside of a tenant, it is obviously important to be able to manage the existence of those tenants. As a result of this decision, when not using the original V1 of the API, you will need to manually create a tenant using the API.

If you are currently using V1 of the API, you can continue to do so in Engine 2018. You will just need to add a setting named "ApiEnableV1" to your Engine config file with a value of "true". Calls to V1 will still automatically create tenants as they are requested. On the other hand, Engine's LRS now requires that tenants exist before you reference them. If you are specifying a tenant in your xAPI requests, then you will need to ensure that you have already created that tenant before executing your request. You can do this by either explicitly creating a new tenant with the V2 API, or you can just reference the tenant using any endpoint of the V1 API to automatically create the tenant.

Please note that the new V2 API will not work if you have an integration layer that relies on your own implementation of ExternalConfiguration. If you integrate with Engine solely through the API, then you should be able to move the V2 API without any trouble.

Postback Schemas

Engine can be configured to send periodic updates to your application about registration state and course import job completion. These postbacks have changed in 2018 now send the same schema that is used by the new V2 API by default. If you are currently using these postbacks in an older version of Engine, then you will need to either update your application's webhooks so that they support this new schema or add a setting named "ApiPostbackDataModelVersion" with a value of "v1" to your Engine config file.

Registration Data Changes

Normally, we recommend against reporting off Engine's tables directly, but we know some older integrations are set up to do that. If your application is querying Engine's tables (especially any starting with ScormActivity*), then you may run into some problems after upgrading to Engine 2018.

To speed up the process of working with registration state (which happens on almost every request), we've started saving the registration runtime details as a single object in a binary column in the database, rather than persisting them to the various normalized tables we used previously. While this would not impact existing data in those tables (it's still there), it would mean any runtime data that comes in after the upgrade would not be available in them.

Because of this, if you need to continue pulling data directly out of the tables that start with "ScormActivity", then you will need to add the "StoreRuntimeDataAsLob" setting to your Engine config and set the value to "false". This will make Engine use its old behavior and keep your reporting intact.

Unless your integration requires it for the reason above, you should most likely not adjust this setting otherwise. In the vast majority of cases, saving the registration data in the new way will improve the performance of the player saving progress, and reduce load on the database server (fewer queries).

Currently, Engine 2018 can convert existing registrations to the binary format, but it does not provide a way to convert registrations from the binary format back to their pre-upgrade state. Because of this, it is very important that you verify whether or not your integration relies on Engine's tables before pushing your upgrade to production. Otherwise, you risk being unable to run your reports on any registrations converted to the new binary format.

Changes to Course Folder Naming

We've also made some changes to how we store your course files. This change only affects customers that import by passing Engine their course zip files to extract.

Previously, when extracting course files to the file system, we would create a new directory with a name that was based on the zip file you passed us. If a folder with that same name already existed, we would append a date/time value to make it unique.

Now, we will name the directory based on the ID of the course being imported. For API customers, this would be the course id value passed with the import job. For older integration customers, this would be the serialized form of the ExternalPackageId you use.

Within that directory, we will also create a subfolder for each version of the course you import. So, for example, if you import a course with an ID of "myCourse123", you would end up with a folder structure something like: /courses/myCourse123/0.

We've decided to make this change as this is a better practice that leads to more maintainable and understandable course file storage paths. It also helps with the creation of auth cookies if using our built-in CloudFront support, and with potentially removing files when deleting a course. 

This won't affect any previously imported courses, however, and it typically won't require a change from your application. We mention it only in case there are customers concerned with how Engine stores their unzipped course files. If you're worried about this change in behavior, please reach out to our support team, and we can talk through it together. 

Was this article helpful?
2 out of 2 found this helpful
Have more questions? Submit a request
Powered by Zendesk