Upgrading Engine

Engine interacts with two persistence-related components: a database, and a filesystem. Over time, as we add new features to Engine or otherwise improve the old features, it is necessary to change the underlying structure of these components while preserving the data contained therein. This only happens during a major release of a new version of Engine, and for this purpose we have created an automated upgrade tool.

This document is intended only as a reference. If you want to upgrade Engine, you will need to contact us at support@scorm.com so we can provide you with the latest version of our software, as well as arrange for a dedicated support engineer to talk through the process with you and answer any questions you may have.

Before You Upgrade

Back Up Your Database and Files

We expect that most customers are performing regular backups of both their filesystem and their database, but it is especially important to do so during the upgrade. We encourage you to back up your database and take a snapshot of your xAPI filesystem data before running the upgrade tool. Rustici Software is not responsible for data loss caused by the use of the upgrade tool.

Securing Your xAPI Filesystem Data

Prior to Engine 2015.1.x, Engine would supply a default value for the TinCanFilesPath (now xAPIFilesPath) configuration setting (which controls where large xAPI documents and xAPI attachments are stored). Unfortunately, the default value was the same as FilePathToContentRoot, the directory where package contents are stored on the filesystem). Since files under that directory are typically accessible through your web server, we now consider this a security hole. To better protect you and your data, we now require you to define an xAPIFilesPath setting value explicitly, and we also verify at runtime that this value is not the same as FilePathToContentRoot.

If you did not explicitly define a TinCanFilesPath configuration setting value, you will need to move your xAPI filesystem data to a secure location before upgrading. Moving the data is simple. First, create a directory somewhere where your xAPI data can be stored. Second, look under your FilePathToContentRoot directory for a folder named tincan. Once found, move that entire directory to the directory you designated in the first step. Third, add the TinCanFilesPath configuration setting to your engine installation's configuration file with its value set to the directory chosen in the first step. Finally, you will need to restart the Engine server for the changes to take effect.

Extra Considerations for xAPI/Tin Can "Beta" Users (2012.1.x and 2012.2.x)

If you are on Engine version 2012.1 or 2012.2 and have xAPI (Tin Can) data, you will need to run a separate upgrade tool to convert your xAPI tables to their 2013.1.x equivalents. (At this time, we suspect that most of these customers have already upgraded, and that this will apply to very few customers, if any. After all, in 2012 xAPI was still in its infancy and hadn't even reached version 1.0 yet.) Instructions for that tool are outside the scope of this document; you must discuss this with your support engineer.

Update Your Integration Layer (If You Have One)

This applies primarily to customers who began using Engine before the release of Engine 2015.1.x.

At the start of your upgrade progress, our support engineers will ask you for a copy of your integration layer and external key classes. We will then provide specific advice on how to update the integration layer to match the modern version of Engine.

At a minimum, you should attempt to recompile your integration layer against the latest version of Engine, as signatures may have changed.

Running the upgrade tool

Your upgrade deliverable will come with a bundled configuration template file. The file is called EngineInstall.xml.template. Fill out the fields in this file, and save the result without the .template extension. For information on formatting connection strings (Java customers should especially take note), see the installer documentation.

Running the upgrade tool is essentially the same as running the install tool. The tool must be run from the same directory, and any necessary caveats about copying database connectors still apply. Copy your EngineInstall.xml file into that directory. The command will be: baseCommand EngineInstall.xml, where baseCommand is described in the installer documentation.

Multi-database customers should run the upgrade once per database. The same SystemDatabaseConnectionString should be used for each database you upgrade; the TenantDatabaseConnectionString will be the only connection string that differs. You must also select a different default TargetTenant for each database.

Customers who wish to update to our new tenancy model (which allows multiple tenants in each database) are highly encouraged to talk to us before attempting an upgrade, but in brief, the upgrade will require the customer to provide a SQL query that will return the name of the tenant associated with a package, given that package's external keys.