Upgrading Engine

Introduction

The upgrade process for Engine is more involved than usual because of some substantial schema changes implemented in 2014.1.x to improve performance. For your convenience, we have built a tool to enact these schema changes.

This document is intended as a reference only. If you want to upgrade, please contact us at support@scorm.com so we can arrange for you to have the help of one of our dedicated support engineers who will talk through this process with you, answer any questions you may have, and address any of your concerns.

Step 1: Update your database

Step 1a: Back up your database

Before you run our upgrade tool or run scripts on Engine's tables, please back up the database that contains them. Rustici Software is not responsible for any lost data caused by attempting to upgrade Engine without having a backup in place.

Step 1b: Update your database

What you will have to do will depend on what version of Engine you are upgrading from, and on whether or not you have Tin Can data.

Upgrading from Engine Version 2011.1 or Earlier

• Back up your current database
• In order, run the database upgrade scripts starting with the first one released after your version of Engine and finishing with 2011.1. (If you are already on version 2011.1.x, do nothing for this step.)
• Proceed to step 1c.

Upgrading from Engine 2012.x, if you have no Tin Can data

• Back up your current database.
• Proceed to step 1c. You do not need to run any scripts.

Upgrading from Engine 2012.x, if you have Tin Can Data

• Back up your current database.
• Run the DB upgrade script for 2013.1.
• Run the 2013.1 TinCanSchemaConverter tool. (You will need to speak to our support to get this tool.)
• Continue to step 1c.

Upgrading from Engine 2013.x

• Back up your current database.
• Proceed to step 1c. You do not need to run any scripts.

Step 1c: Run the Upgrade Tool

The upgrade tool will analyze your schema and perform the necessary operations to convert your data to the current schema. Running the program requires slightly different steps, depending on whether you are on Java or .NET.

You will need to supply a connection string to the database that has permissions to run SQL ALTER commands and create tables.

General .NET instructions

An executable, EngineUpgrade.exe, is included in the ScormEngineInterface/bin folder of your distribution. Navigate to that folder on the command line.

Running the upgrade is simply a matter of supplying your connection information to the program in the form of command-line arguments. The full command is EngineUpgrade.exe persistenceEngine connectionString schemaPrefix, where:

• The first argument, persistenceEngine, should be your DBMS type (either mysql, oracle, postgresql, or sqlserver).
• The second argument, connectionString should be your connection string. This is often the same as the connection string used in your Engine configuration file (SCORMEngineSettings.config). The connection string may need to change if your typical engine user does not have permission to alter tables. Be careful to quote the connection string so that none of its characters (or whitespace) are interpreted as special control characters by your shell.
• The last argument, schemaPrefix, should be the schema prefix you use to specify tables. This should also be the same as the schema prefix specified by your Engine configuration file. If you do not use a schema prefix, this argument can be omitted.

Note: For legal reasons, the MySQL connector for .NET cannot be distributed with the rest of Engine, and is therefore not present in the folder with the upgrade tool. If you need to connect to a MySQL database, you will need to download the connector (version 6.3) yourself. You can find it here: http://dev.mysql.com/downloads/connector/net/6.3.html. Once downloaded, copy the library into the folder with the rest of the binaries.

General Java instructions

You will find everything you need in the Upgrade folder of your distribution. That folder will contain a command-line script (upgrade.sh on Unix; upgrade.bat on Windows) that can be used to run the upgrade. The script must be run from that folder.

On Unix, run sh engineupgrade.sh pathToJdbcConnector persistenceEngine connectionString [schemaPrefix].

On Windows, run engineupgrade.bat pathToJdbcConnector persistenceEngine connectionString [schemaPrefix].

Both platforms have four command-line arguments:

• The first argument, pathToJdbcConnector, is the path to the jar file containing the connector you use to connect to your database.
• The second argument, persistenceEngine, should be your DBMS type (either mysql, oracle, postgresql, or sqlserver). It should have the same value as the DataPersistenceEngine setting in your configuration file (SCORMEngineSettings.properties).
• The third argument, connectionString, should be the connection string you use to connect to the database.
  • This utility does not run in an application container, so *you cannot reference JNDI connection definitions. You must define complete JDBC connection urls, as would be found in your server's configuration file. The connection string must also be followed by a pipe (|) and your JDBC class name. For example, a valid connection string might be: jdbc:mysql://myHostName/myDbName?user=myUserName&password=mypassword|com.mysql.jdbc.Driver
  • Take care to quote this argument; the characters used in connection strings are often special characters in most shells.
• The fourth argument, schemaPrefix, should be the schema prefix you use to specify tables. This should also be the same as the schema prefix specified by your Engine configuration file. If you do not use a schema prefix, this argument can be omitted.

Step 2: Update the application files

Updating Your Integration Layer

Occasionally, we may remove integration methods that have proven to be problematic or change their signature. Some customers may have overrides for these deleted or overridden methods, and so we have taken extra precautions to make sure that Engine will not run if it detects an outdated integration layer override, in order to make customers aware of the potential problem. We also occasionally have to make changes to Engine's public APIs that are used by the integration layer.

Our recommendation is that you provide us with your integration layer and external key classes at the start of the upgrade. This will give us an opportunity to evaluate the changes and prepare you to rebuild your integration assembly against the new RusticiSoftware.ScormEngine.dll assembly, or integration JAR file against the new scplogic.jar file.

If you don't do this, you will most likely see some errors and/or warnings. Some examples of these are as follows:

• In 2014.1.x, we have removed the signature of "TinCanGetEngineActivityIdSuffix" that took an ExternalRegistrationId and ExternalConfiguration as arguments, replacing it instead with a signature that takes an ExternalPackageId and ExternalConfiguration as arguments. If you have overridden this method, you will have to update your implementation to accept the new arguments.

• If you use Engine's DataHelper methods in your integration, you'll find that calling DataHelper dh = Retrieve.Implementation.GetHelper(externalConfig) will cause a compile error, because GetHelper now returns an IDataHelper object.

• In order to make it possible to swap out implementations for automated testing, methods in ScormEngineManager class have been moved into ScormEngineManager.Implementation (ScormEngineManager.getImplementation() on Java). Using ScormEngineManager directly will still work, but you'll see compiler warnings about obsolete methods.

If you run into any errors or warnings while building or using your integration with the new version of Engine, just let us know and we'll be happy to help you update the code.

Updating Your SCORM Engine configuration File

The "ScormEngineScriptsUrl" setting in the SCORMEngineSettings configuration file was optional in previous versions of Engine, but is now required. It should point to the "scripts" folder inside your ScormEngineInterface application folder.

Example for .NET Engine:

<!-- SCORMEngineSettings.config -->
<add key="ScormEngineUrl" value="/ScormEngineInterface"/>
<add key="ScormEngineScriptsUrl" value="/ScormEngineInterface/scripts"/>

Example for Java Engine:

<!-- SCORMEngineSettings.properties -->
<entry key="ScormEngineUrl">/ScormEngineInterface</entry>
<entry key="ScormEngineScriptsUrl">/ScormEngineInterface/scripts</entry>

Minor Engine Upgrades

Between major releases of the SCORM Engine we may make point releases that fix bugs and add small pieces of functionality that are needed by our clients. When you update your SCORM Engine implementation to one of these point releases we recommend that you follow these instructions so that we can continue to support you easily.

If you have any questions about these instructions, or you think they are not optimal for your deployment scenario, then please contact us and we will help you through the upgrade process.

The SCORM Engine interface is a web application that is customized for our clients by adding a custom Client Integration dll to its bin folder and configuring its web config settings through the SCORMEngineSettings.config file. We test our configurations with all files at the same code level so we encourage you to think of the files in the SCORM Engine directory as a single unit, despite the fact we may be providing a patch that only affects a handful of JavaScript files. Some updates may include database scripts for schema or stored procedure changes but we will explicitly call out if/when that is necessary. The standard upgrade instructions depend on your deployment scenario:

Updating Your SCORM Engine for Java

Updating the SCORM Engine application for your Java platform should primarily consist of redeploying the included WAR files. If you have made custom UI changes to your environment you will need to unpack the WAR files, merge your changes, and recreate your WAR files. Information on what changes you may need to make to accommodate your custom UI changes can be found below in the .NET section.

Updating Your SCORM Engine for .NET

SCORM Engine 2010.1 and higher

Single SCORM Engine Web Application, default user interface

In the most common deployment scenario where the SCORM Engine is deployed separately to the Client LMS as a single web application, and the Client LMS uses the standard UI files located in ScormEngineInterfaceDir/defaultui. You'll essentially need to completely replace the SCORM Engine application while keeping your own integration DLL and configuration file. Follow these steps (assuming the SCORMEngineInterface web app is located at ScormEngineInterfaceDir, and your integration DLL is named ClientIntegration.dll):

• Copy away the client integration DLL: ScormEngineInterfaceDir/bin/ClientIntegration.dll
• Copy away the client settings file: ScormEngineInterfaceDir/SCORMEngineSettings.config
• Delete ScormEngineInterfaceDir.
• Unpack the ScormEngineInterface web app to ScormEngineInterfaceDir.
• Copy back the client integration DLL to ScormEngineInterfaceDir/bin/.
• Copy back the SCORMEngineSettings.config to ScormEngineInterfaceDir.

Single SCORM Engine Web Application, custom user interface.

In this deployment the Client LMS has its own set of SCORM Engine UI files, usually based on the /defaultui files, in a separate web application. It is rare that we will have made changes to the UI files in a point release. If we have then we will indicate the changes so that the client can merge these changes into their modified UI. Additionally:

• Replace ScormEngineInterface as in the Single SCORM Engine Web Application, default user interface steps.
• Copy ScormEngineInterface/bin/RusticiSoftware.ScormEngine.dll to the bin directory of the webapp hosting the UI.

Single Central SCORM Engine, multiple Remote SCORM Engines

In this deployment there is a single SCORM Engine co-located with the database and one or more remote SCORM Engines co-located with the course content.

• Replace Central ScormEngineInterface as in the Single SCORM Engine Web Application, default user interface steps.
• Repeat this process for each Remote SCORM Engine.

Step 3: Custom UI Updates

If you using a custom UI, meaning something other than scormengine/defaultui/deliver.aspx (or jsp), you will need to make the following additions to to take advantage of the new IE Compatibility Mode package property. If this step is skipped, your player will continue to function but it will continue to use the hard-coded META tag, if any.

Deliver.aspx or jsp

<html>
  <head>
    <!-- Remove the following <meta> tag: -->
    <meta http-equiv="X-UA-Compatible" content="IE=EmulateIE8" />
    <!-- Add this tag instead: -->
    <%=Data.InternetExplorerCompatibilityMetaTag %>

Intermediate.aspx or jsp

<html>
  <head>
    <!-- Add this tag: -->
    <%=Data.InternetExplorerCompatibilityMetaTag %>