Technical Detail
This page describes the technical updater process. It is the low level process the Appliance runs at step 7 on the main Appliance Update page.
The low level updater process is deliberately designed to be separate from the main Wise Owl software components. While there is some overlap, this separation ensures the updater is not affected by errors in the normal Wise Owl Legal Appliance.
At a high level, the updater:
- Verifies the updater package.
- Unzips the package.
- Deactivates the various Wise Owl Legal components.
- Installs the various Wise Owl Legal components.
- Performs any other Appliance updates or configuration.
- Restarts all Wise Owl Legal components.
- Notifies that the update was successfully installed.
Low Level Initialisation
The updater first makes a "shadow copy" of itself. This allows the updater to update itself.
It then checks if previous log files have been uploaded to Wise Owl for analysis. If not, it exits and will try again in 5 minutes. This is the most common cause of transitory errors.
The updater is designed to fail gracefully, leaving as much information about what went wrong as possible, if there is any error. As such, it initialises error handlers, begins logging to disk and loads a fail safe email address to contact if anything goes wrong. This early part of the updater has been rigorously tested to minimise failures; so if something goes wrong, at minimum an email should be sent and error log files will be saved on disk.
Load Configuration And Select Package
The updater must then decide what to update (as multiple instances of Wise Owl Legal can be installed on the same physical Appliance) and what to package to install.
It first locates the existing Wise Owl components on the Appliance and gets their version. It also uses the scheduler configuration to connect to the SQL database.
It can then decide what package to install based on what the user selected on the About page. A Wise Owl Technician can instruct you to run the updater from a command prompt; if no update was selected from the About page you will be presented with a list of packages to install.
The updater now has all the information it needs to install the package.
Update Initialisation
At this point the updater double checks everything it needs: database access, the package file, that the new version is greater than or equal to the current one and that there is sufficient disk space available for the update.
It also verifies with the Wise Owl update server that the package is correct and has not been tampered with.
Now, the updater is ready to being the installation. A start email is sent and the Wise Owl update server is notified that it is about to begin the update.
Update Process
The actual update process now begins!
Several housekeeping tasks are run first:
- The job to upload logs after the updater completes is scheduled.
- An update pending file is created.
- The updater checks if this version has already failed and is retrying: if it has failed too many times (more than 5), it fails and gives up. Manual intervention is required to repair the Appliance.
- The Appliance web server is deactivated.
The full system backup is started. This can take several minutes to run. However, backups are incremental, so only data changed since the last backup is copied. If the backup fails or runs for too long, the update is aborted.
The package file is unzipped to a temporary folder.
The list of components to update and processes to perform is read from the package file. These are stored as CMD or PowerShell scripts in the update package itself.
All system level configuration settings are read from the Wise Owl SQL database. These are sent to each script so they can use the information to copy or configure component correctly.
Each script is executed in turn. The first script deactivates all background components on the Appliance, the last script re-activates them. Each script updates a single component of the Wise Owl Appliance; there are currently 16 scripts.
If all the scripts succeed, the web server is re-activated and the package is marked as successful in the Wise Owl SQL database.
Finally, the update success is reported to the Wise Owl update server and the success email is sent. It also reports the new version of the Appliance to the update server; Wise Owl tracks the update status of each Appliance in this way.
Failures
Depending on what stage the updater fails at determines how it handles that failure. At minimum, the details of the error are written to log files on the Appliance.
By default, each version will be retried up to 5 times if there are any errors. After 5 times, the update will be deemed a failure and it will give up.
A failure during Low Level Initialisation will send an email directly to the Wise Owl Helpdesk. This represents a very low level error; the Appliance likely requires repair or replacement. The Wise Owl update server is not contacted.
A failure during Load Configuration And Select Package will send an email to the Wise Owl Helpdesk and, if the configuration loaded successfully, to a nominated "fail safe" email address (usually a technical administrator for the Appliance). If the SQL database can be accessed, an email will also be sent to the user who initiated the update. The Wise Owl update server is not contacted.
A failure during Update Initialisation will contact the Wise Owl update server directly. Emails will be sent to the "fail safe" address and the user who initiated the update.
A failure during the actual Update Process will contact the Wise Owl update server directly. Emails will be sent to the "fail safe" address and the user who initiated the update.
Obviously, if the Appliance is not able to contact an email server or the Internet, it will not be able to notify Wise Owl of any errors which occurred. You must be connected to the Internet to update your Wise Owl Appliance.