New versions are developed for two reasons:

• Implementing new functionality.

• Fixing bugs.

Some of the new functionality introduced requires changes to the data model in the database. Therefore, each version of the framework defines a corresponding Data Model Version.

Each new version (release) of the TOPICA framework is designed to be backward compatible. That is, a new framework version will run applications using databases with older data model versions. Not all old data models are supported. Framework version from 4.20 up to and including the current version 4.30 in theory supports data model versions as old as 4.17 - but in practice each new version is only tested on a few recent data models (e.g. framework version 4.30 has been tested on data models 4.30 and 4.29, but not older data models).

Note

In some new versions, there might be a few incompatibilities and/or new runtime requirements, that will require attention when updating. Such backward incompatibility issues will be mentioned (and highlighted) at the top of the ReleaseNotes, that comes with each new version, and that is visible in the Startup Menu. Always read ReleaseNotes and take required actions before updating to new version of the framework!

How to update to a newer version of the framework:

• Read and understand the ReleaseNotes in the Startup Menu, and take any required actions. If you update multiple version numbers, read all the ReleaseNotes files. For example, when updating from 4.24 to 4.27, you must read the ReleaseNotes files from 4.25, 4.26 and 4.27!

• Unpack the new framework (that is typically distributed as a .zip-file) to a new folder. Remember where you placed this folder.

• Updating the framework "in place" (an existing "web home"):

  • In the "web home", delete all files and folders except the folders App_Data and Configuration.

    Why this step? Because there are some parts of the framework, that executes all files in a folder. Simply copying files from new framework version into a folder containing files from old framework version might result in that a few files from the old version will remain. This could result in some hard to trace errors.

  • Copy all the unpacked folders and files from where you unpacked the new framework version. It is important to create the same folder structure as before.

• Of course, it is also possible to create a new web home for the new framework version, and then copy existing configuration folders(s) into this new web home. This would essentially be a new installation of the framework, but when the configuration (e.g. the Server.config file) refers to an existing database, it feels like an update of the application. Obviously, the new web home will have a different URL (unless you configure IIS so that the old URL will refer to the new web home).

It is not always necessary to update the data model in existing databases after updating the TOPICA framework. You do need to update the data model in these situations:

• You need some new functionality, that requires a new data model version.

• The data model in the database is so old, that the new version of the framework does not support it anymore.

The scripts to update data model version creates/alters/drops database objects (tables, views, columns, indexes, stored procedures, functions, etc.). In some cases, an object cannot be dropped or altered, if some other objects in the database depend on this object. For example, it is impossible to alter a column, if an index referencing that column exists.

The update scripts delivered with TOPICA "know" how the data model in a given version is supposed to look like (e.g. they "know" whether a column is referenced by any indexes - so appropriate action can be taken, e.g. dropping the index, altering the column, and recreating the index).

However, it is possible that someone has modified the data model "manually" by SQL (e.g. added indexes to improve performance, or added some views to facilitate reports).

Such "manual" modifications to the data model may cause the update scripts to FAIL. Therefore, it is important to know whether such modifications exist.

• If you are the only developer working on an application, and you know that no "manual" modifications to the database structure have ever been made, you know that the data model is OK for updating.

• If others have been working on the application (and/or you may have made some changes in the distant past, that you do not remember anymore), you may not be sure whether the data model is OK for updating. In this case, use the following procedure to check the current data model:

  • Select main menu item "Tools / Framework tools"

  • Select "Database / DataModel.aspx" (shift-click to open in separate window).

  • Click "Reference". This displays the data model = database objects in the dbo schema in the browser (in XML format).

  • Save this page as an .XML-file somewhere on your local PC's disk.

  • Locate relevant "reference" data model file (<webhome>/Database/Reference/Reference4XX.xml, where "4XX" is the data model version number - e.g. data model version 4.27 is stored in Reference427.xml).

  • Compare the XML file you saved in above step to the reference file that comes with the framework, using for example WinMerge.

  • If this comparison displays any differences, it is an indication that some "manual" modifications have been done in the current database. Therefore, it is possible that updating the data model version could fail.

    Consider each difference / manual modification: some may be harmless (not interfering with the update process), some may be dangerous (causing the update process to FAIL). Some knowledge of SQL, SQL Server in particular, AND the TOPICA data model may, will be necessary to determine which modifications are "dangerous".

    Note
    Some constructs that look "dangerous" will only actually be "dangerous" (cause problems for the update data model process), if the update data model process touches the relevant database objects.

    For dangerous modifications, it is the responsibility of the configurator to remove any modifications before updating the data model, and applying them again after the data model update.

Important
Whether or not you have a suspicion that the update process may fail, it is advisable to create a database backup immediately before updating data model version (and shut down user access while the update takes place!). If anything goes wrong in the process, such a backup may be the ONLY way to get the data back!

Updating data model is done one version number at a time. For example, to update from data model version 4.24 to 4.27, the following steps are needed:

• 4.24 -> 4.25

• 4.25 -> 4.26

• 4.26 -> 4.27

Each new version of the TOPICA framework comes with a set of command line scripts to update data model in existing databases. You may run these scripts from the command line, but it is by far easier to use the Administration Module that is introduced in release 4.25.

Reasons for using choosing the Administration Module over the command line scripts:

• The Administration Module internally runs the command line scripts - so the result is the same. The Administration Module is simply a nicer user interface for running the scripts.

• The Administration Module automatically saves (logs) all script output in the folder <webhome>/Configuration/<configname>/Log/Administration

Each new release contains scripts to update a to several previous data model versions.

• From version 4.27 and newer, it is recommended to always use the Administration Module. This version contains fixes to some bugs in previous version of the update scripts. In version 4.27 and newer, you may update data model version all the way from 4.20.

• In releases 4.25 and 4.26, it is recommended to use Administration Module, but it is ONLY possible to update to the current version. For example, to update data model 4.24 -> 4.25, use version 4.25 of the framework.

• In releases older than 4.25, the only option is to use the command line scripts. You should use the scripts in versions 4.N to update from data model 4.(N-1) to 4.N. For example, to update data model 4.23 to 4.24, use the update scripts contained in release 4.24, not the ones in 4.25.

Important
After updating, check the output of the update script carefully. This output may give clues to any errors - and hence how the database may be fixed.

Data model updates may fail for a number of reasons:

• Modification to the database.

• Time-outs because of long running conversions (more likely the more data exist in the database). Note that an update that runs fine in a development environment may fail in a production environment, because the production environment coantains more data than the development environment.

• Problems in the SQL Server runtime environment - e.g. disk may run full preventing the database to grow.

• Error in the update scripts.

Important
If a data model update fails, the database may be in a bad state (data may be lost, and/or database may be partly converted and thus unusable). In such case, restoring the database from previously saved backup may be the best way to continue. Of course, after restore the reason for the update fail should be fixed before attempting next update!

After installing a new version of the TOPICA framework, this is how you should proceed:

• Ask you self: do you really need any new functionality supported in the new data model version (check release notes) - or is the current data model unsupported in the new framework version?

  • If the answer is "no", you do not have to update data model version - so you do not need to do anything.

  • If the answer is "yes", you must update to the new data model version.

    • First check the prerequisites for updating the data model (see above).

      Important
      Remember to create a database backup!

    • If the new framework version is 4.27 or newer, use the Administration Module, and you may update the data models from 4.20 and upward in the same framework version. For example, you may use framework 4.30 to update data model 4.20 -> 4.21 -> 4.22 -> 4.23 -> 4.24 -> 4.25 -> 4.26 -> 4.27 -> 4.28 -> 4.29 -> 4.30. It is still one version at a time, but you may do all the updating from same "web home" (just one button click for each update).

    • If the new version is 4.25 or 4.26, you may use the Administration Module, but it is only possible to update from the previous version:

      • Use release 4.25 to update data model from 4.24 to 4.25.

      • Use release 4.26 to update data model from 4.25 to 4.26.

    • If the new framework version is 4.24 or older, use command line scripts to update data model version.

Other Resources