This section discusses the topic of major version upgrades for Engine. If you are simply deploying a new maintenance release (a "minor version"), you will be using a much simpler process than what is outlined here. Ignore this documentation and use the maintenance release documentation instead.
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 in them. You only need to go through the process when transitioning between major versions of Engine (i.e. moving from Engine 2016 to Engine 2017). As Engine grows older, more and more past schemas are joining the ranks of the dead. To help all of customers upgrade to the latest version of Engine, regardless of their current version, 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 firstname.lastname@example.org 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
Note: This section applies only to customers who currently support xAPI.
Engine requires use of the filesystem to support some xAPI features; see this relevant section from the xAPI documentation. If your application used xAPI file storage, you will need to carefully consider it during the upgrade.
For users coming from more recent versions of Engine, you may have been required to specify an
xAPIFilesPath explicitly if you were using it. Check your Engine configuration file to see if you are specifying a value for this setting; if not, you do not need to worry about the xAPI file migrations. You can set the SkipxAPIFileStoreMigrations setting to
true instead of setting a value for
xAPIFilesPath. If you are using this setting, however, you will have to provide it to the upgrade tool.
For users coming from Engine 2014.1 and earlier, Engine supplied a default value for the
xAPIFilesPath configuration setting. Unfortunately, the default behavior was to use the value of
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 problem. 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
The first step will be determining whether you have any such data. Look under your
FilePathToContentRoot directory for a folder named
tincan. If such a folder is present, then you will need to move it. Create a directory somewhere where your xAPI data can be stored safely. Move the
tincan folder there, and then specify the directory you created (not the
tincan directory, but its parent) as
xAPIFilesPath in your upgrade configuration file and in the configuration file of the Engine version to which you are upgrading. (This will all need to be done as part of your actual cutover process; if you do this before that your older version of Engine could end up creating more files that you would otherwise miss.)
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 section applies primarily to customers who began using Engine before the release of Engine 2015.1.x. If you integrate with Engine solely through the API, then you can disregard the following.
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 as
EngineInstall.xml. When entering your connection string, make sure to escape any XML-unsafe characters like ampersands. That file will include the minimum list of settings you will need to support. Running the upgrade tool involves many of the considerations necessary for running the install tool, but the tools are executed slightly differently.
Before running the upgrade tool, customers running MySQL or Oracle will need to set up their database connectoryou will need to set up your JDBC connector, as described in the install tool documentation. Copy your modified
EngineInstall.xml file into the same directory as the install tool, and run the command:
java -Dlogback.configurationFile=logback.xml -cp "lib/*" RusticiSoftware.ScormContentPlayer.Logic.Upgrade.ConsoleApp EngineInstall.xml
Be careful to run the upgrade tool and not the install tool; do not provide a
-install flag to the upgrade tool, and do not attempt to pass your connection string over the command line.
Customers who have separate system and tenant databases should generally upgrade the system and tenant databases separately. Provide a configuration file with your system connection string, and then run the install command with the
-system flag to upgrade the system database only (e.g.,
EngineInstall.exe EngineInstall.xml -system
java -Dlogback.configurationFile=logback.xml -cp "lib/*" RusticiSoftware.ScormContentPlayer.Logic.Upgrade.ConsoleApp EngineInstall.xml -system). To upgrade a tenant databases, provide your tenant database connection string in the settings file and then run the upgrade command with the
-tenant flag (e.g.,
EngineInstall.exe EngineInstall.xml -tenant
java -Dlogback.configurationFile=logback.xml -cp "lib/*" RusticiSoftware.ScormContentPlayer.Logic.Upgrade.ConsoleApp EngineInstall.xml -tenant). You should also provide the
TargetTenant setting for each tenant database. You must upgrade your system database completely before modifying any tenant databases, but once you have done that you can upgrade multiple tenant databases simultaneously to save time.
If using an XML file for configuration presents problems for your automated deployment tools, talk to us and we can explain a few other options that may be easier to integrate into a script.
Customers upgrading from a version before Engine 2015 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.