Major Releases

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 (e.g., 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 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

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, and in the upgrade configuration file (discussed below), 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 FilePathToContentRoot.

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. They may also ask for DDL create scripts from your Engine database's ScormPackage and ScormRegistration tables. These are important for configuring the upgrade tool to work correctly with your custom package and registration columns. 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

Engine ships with a separate tool for upgrading its database, which is located in the application's /bin directory/RusticiEngine/Installer folder. This directory also includes a configuration template file called EngineInstall.xml.template. It includes the minimum list of settings needed to run the upgrade tool as well as many of the instructions covered below. Fill out the fields in this file, and save the result without the .template extension as EngineInstall.xml. Although the upgrade tool involves many of the same considerations necessary for running the install tool, the tool will run quite differently depending on how this file is configured.

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. The tool runs independently of IISan application server like Tomcat, so you don't need to deploy Engine to execute the database upgrade. Simply copy your modified EngineInstall.xml file into the same directory as the tool and run the command:

EngineInstall.exe EngineInstall.xml

java -Dlogback.configurationFile=logback.xml -cp "lib/*" RusticiSoftware.ScormContentPlayer.Logic.Upgrade.ConsoleApp EngineInstall.xml

Be careful to ensure that the tool runs as an upgrade rather than an installation. For example, do not provide an -install flag to the upgrade tool, and do not attempt to pass your database type or connection string as command line arguments.

If using an XML file for configuration presents problems for your automated deployment tools, talk to us, and we can review another option that may be easier to integrate into a script. Most of the upgrade settings information below still applies, but rather than using an XML configuration file, you would instead set these programmatically by extending our EngineUpgradeManager class to run an Integrated Upgrade.

Integration Types

Customers that started on a pre-2015 Engine version often continue maintaining custom integration code. Within this integration layer are classes that can extend our ExternalRegistrationId and ExternalPackageId classes, which define unique, custom package and registration identifiers on the ScormPackage and ScormRegistration tables. The upgrade tool must be informed of these columns with settings in the upgrade configuration file called ExternalPackageKeyColumns and ExternalRegistrationKeyColumns.

The format to define these custom columns is as follows:

[column name]:type=[type];(length=[column length if applicable])

If you have multiple integration columns, then you should separate the column definitions with a comma:

student_id:type=nvarchar;length=100,course_id:type=int

The 'type' in this format typically refers to the type used in the database column, but you should talk to a dedicated support engineer first. In practice, these settings in the upgrade configuration file could look like this:

<entry key="ExternalPackageKeyColumns">
    course_id:type=int
</entry>

<entry key="ExternalRegistrationKeyColumns">
    assignment_id:type=nvarchar;length=100,
    course_id:type=int
</entry>

If an integration column is of a VARCHAR data type, talk to the Rustici support team about the use of the AsciiKey annotation to improve certain index utilizations.

Otherwise, if your application integrates with Engine exclusively through either the V1 or V2 REST API, then neither ExternalPackageKeyColumns nor ExternalRegistrationKeyColumns is applicable, and you should set IncludeApiIntegration to true.

<entry key="IncludeApiIntegration">true</entry>

If you're unsure, check out your current Engine application's RusticiEngineSettings.configproperties (Engine 2018 and above) or SCORMEngineSettings.configproperties (Engine 2017 and below) file and see if there are entries for LogicIntegrationAssemblyName and LogicIntegrationClassName is an entry for LogicIntegrationClassName. TheseThis would point to an integration layer, which could contain classes that define external package and registration keys.

Minimum Database Settings

The most common database setup for Engine consists a single database containing both the system and tenant schemas. In this scenario, the database configuration settings are pretty straightforward:

DataPersistenceEngine must be one of sqlserver, oracle, mysql, or postgresql.

SystemDatabaseConnectionString contains the one connection string to which the Engine application connects. Since both system and tenant schemas reside in the same database, there is no need to specify a separate TenantDatabaseConnectionString. In any case, make sure to escape any XML-unsafe characters like ampersands. Additionally, If you run the upgrade tool from the command line, you will not be able to use JNDI identifiers. Instead, you must provide a JDBC URL, followed by a pipe (|), followed by the class name of your JDBC connector.

<entry key="DataPersistenceEngine">sqlserver</entry>
<entry key="SystemDatabaseConnectionString">server=localhost;uid=user;pwd=password;database=ScormEngine</entry>

<entry key="DataPersistenceEngine">postgresql</entry>
<entry key="SystemDatabaseConnectionString">jdbc:postgresql://server/db?user=user&amp;password=pw|org.postgresql.Driver</entry>

Separate Tenant Databases

Customers who have separate system and tenant databases should upgrade them separately. You must upgrade your system database first before modifying any tenant databases. However, once the system database upgrade is completed, you can then upgrade tenant databases either one-at-a-time or simultaneously to save time.

To upgrade the system database, provide the configuration file with the SystemDatabaseConnectionString setting, and then run the install command with the -system flag to upgrade the system database only:

EngineInstall.exe EngineInstall.xml -system

java -Dlogback.configurationFile=logback.xml -cp "lib/*" RusticiSoftware.ScormContentPlayer.Logic.Upgrade.ConsoleApp EngineInstall.xml -system

To upgrade a tenant database, the tool requires two additional setting, TenantDatabaseConnectionString and TargetTenant. Set the connection string of the tenant database being upgraded to TenantDatabaseConnectionString, and set the actual tenant name to TargetTenant.

The previous setting for SystemDatabaseConnectionString should remain in the upgrade configuration file, and its value should also remain the same for each tenant database you upgrade. In contrast, the TenantDatabaseConnectionString and TargetTenant setting values will both change for each tenant database that you upgrade.

To execute the upgrade, run the command with the -tenant flag.

EngineInstall.exe EngineInstall.xml -tenant

java -Dlogback.configurationFile=logback.xml -cp "lib/*" RusticiSoftware.ScormContentPlayer.Logic.Upgrade.ConsoleApp EngineInstall.xml -tenant

Migrating to Tenancy Model from Older Engine Versions

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. In brief, the upgrade will require the customer to provide a SQL query for the PackageToTenantQuery setting that will return the name of the tenant associated with a package, given that package's external keys.

Migrating Away from Package Properties

Engine 2015 introduced the REST API and modern configuration system. Although intended as a replacement for Package Properties (the original way to configuration course-level settings), Engine supported the use of both the /courses/{courseId}/configuration endpoint and Package Properties. However, as of version 21, Engine will no longer support Package Properties or its web-based editor tool as a means to configure course-level settings.

This change has implications for the upgrade process, as the database upgrade tool can migrate settings from Package Properties to the modern configuration system. When upgrading to version 22 or above, you must set the PackagePropertiesHandling setting to either DROP or MIGRATE in the EngineInstall.xml file. If it's set to MIGRATE, the tool will proceed with the migration. In contrast, DROP will cause the tool to skip the migration and instead drop the obsolete tables associated with Package Properties. The latter is appropriate if you've already upgraded to Engine 21 or above or you've always set course configuration exclusively through the REST API and never used Package Properties.

Setting Defaults for the Upgrade Tool

If PackagePropertiesHandling is set to MIGRATE, one can configure the tool to minimize the number of records that it migrates into the modern configuration system. If a course has a Package Property setting that's already set to a default value, the tool won't migrate it. Therefore, it is advantageous to configure EngineInstall.xml file with these same defaults.

If you maintain a custom integration layer, you may have method overrides that automatcally apply Package Property settings during course import. These overrides serve as defaults and would be located in the integration class that inherits from either DefaultIntegration or ApiIntegration. Depending on the logic involved, these may necessitate entries in the EngineInstall.xml file prior to running the upgrade tool.

For example, you may have override methods like this:

public override LaunchType DefaultScoLaunchType(LearningStandard learningStandard, bool singleSco, ExternalConfiguration externalConfig)
{
    return new LaunchType(LaunchTypeValue.NEW_WINDOW);
}

public override YesNo DefaultShowNavBar(LearningStandard learningStandard, bool singleSco, ExternalConfiguration externalConfig)
{
    return new YesNo(YesNoValue.YES);
}

@Override
public LaunchType DefaultScoLaunchType(LearningStandard learningStandard, boolean singleSco,ExternalConfiguration externalConfig) throws Exception
{
    return new LaunchType(LaunchTypeValue.NEW_WINDOW);
}

@Override
public YesNo DefaultShowNavBar(LearningStandard learningStandard, boolean singleSco, ExternalConfiguration externalConfig) throws Exception
{
    return new YesNo(RusticiSoftware.ScormContentPlayer.Logic.YesNoValue.YES);
}

To prevent the upgrade tool from migrating records unneccessarily, add these settings to the EngineInstall.xml file:

<add key="PlayerScoLaunchType" value="NEW_WINDOW"/>
<add key="PlayerShowNavBar" value="YES"/>

<entry key="PlayerScoLaunchType">NEW_WINDOW</entry>
<entry key="PlayerShowNavBar">YES</entry>

If you have more complicated logic in your overrides or are setting default properties during import through another mechanism, let us know, and we'll help you convert those to settings.

To find the Package Property equivalents in the configuration system, refer to these documentation sections:

• Navigation
• Launch Behavior
• Compatibility
• Communication
• Debug
• Rudimentary Sequencing
• Redimentary Rollup

In addition, you should also check for Package Property settings defined in the SCORMEngineSettings.configproperties (Engine 2017 and below) or RusticiEngineSettings.configproperties (Engine 2018 and above) base configuration file. Since these are also serving as defaults, add them to the EngineInstall.xml file as well.

Finally, to ensure that Engine continues to use your defaults after upgrading the database and deploying the application, apply these same settings either in the RusticiEngineSettings.configproperties base configuration file or through the configuration system.

Package Properties Editor

Likewise, as of version 21, Engine will no longer contain the web-based Package Properties Editor utility. Consequently, if you were using this feature and still require a UI, you must leverage Engine's /configuration API endpoints and build your own to replace it. Granted, every Package Property setting has an equivalent in the modern configuration system, but rather than recreating the entire Package Properties Editor, your UI could feature a subset of settings that you know are commonly adjusted.

System Versus Tenant Schema

By default, Engine installs both the system and tenant schemas into a single database. However, these schemas can be installed in separate databases. If your Engine database is set up like this, check your SCORMEngineSettings.configproperties or RusticiEngineSettings.configproperties file for the UseSystemDatabaseForTenantSettings setting. Normally, Engine saves configuration settings in the system schema. However, if this setting is present in your configuration and set to false, then Engine is storing settings in the tenant schema instead. If that's the case, the upgrade tool needs to do the same, so add the setting to the EngineInstall.xml file:

<add key="UseSystemDatabaseForTenantSettings" value="false"/>

<entry key="UseSystemDatabaseForTenantSettings">false</entry>