Upgrading to 4.2

Upgrading to Content Controller 4.2

This document provides instructions on how to use the upgrade.sh script to perform the required database upgrade for Content Controller 4.2. The script is designed to be run in four distinct phases, guiding you through the entire process.

Prerequisites

Before running the upgrade script, ensure your environment meets the following requirements.

Required Software

The script requires that java be installed and accessible in your system’s PATH.

Required Files

The following files must be present in the same directory where you execute the upgrade.sh script:

  • logback.xml: The logging configuration file for the upgrade process (provided by Rustici).
  • EngineInstall.xml: The configuration file for the upgrade process.
    • ❗️Note: This file can typically be found at /usr/share/tomcat/webapps/ScormEngineInterface/WEB-INF on your application servers. You must make a copy of this file in the same directory as the upgrade script.

Network Access

The script must be run on a machine that has network access to the application’s database. The connection settings within EngineInstall.xml will be used to perform the upgrade.

Usage

Execute the script from your terminal using the bash command, followed by the specific phase you wish to run.

Syntax:

bash upgrade.sh <phase>

Where <phase> is one of the following:

  • phase1
  • phase2
  • phase3
  • phase4

Upgrade Phases

The upgrade is broken down into four phases. It is critical to understand the requirements for each phase, especially phase 3, which requires application downtime.

Phase 1: Index Creation (Online)

This is the first step of the upgrade process. It can be run while your application is online without impacting users. This phase only needs to be run once.

bash upgrade.sh phase1

Phase 2: XAPI Data Migration (Online)

This phase copies your existing xAPI data into a new, updated table structure. It can be a time-consuming process depending on the amount of data to be migrated.

  • This phase can be run while the application is online.
  • You can run this phase multiple times to migrate new data that arrives after the initial run.
  • The process can be safely stopped and resumed if necessary.
bash upgrade.sh phase2

Phase 3: Schema Update (Offline) ⚠️

This phase makes changes to the database schema and must be run while the application is offline.

  1. Stop the tomcat and contentcontroller services on all application servers.
  2. Run the Phase 3 command: 
    bash upgrade.sh phase3
  3. Once the script confirms that Phase 3 is finished, you can restart the tomcat and contentcontroller services.
  4. Follow the instructions given at the completion of phase 3 to upgrade your Content Controller installation to 4.2, then finish with phase 4, below.

Phase 4: Deferred Cleanup (Online)

This is the final phase of the upgrade. It can be run once the application is back online after Phase 3 is complete.

bash upgrade.sh phase4

Filesystem Cleanup

After phase 4 has completed, the upgrade script and related files can be removed from your system.