Skip to main content

Upgrading to newer versions

Extra manual steps are required for 1.60+

1.60 introduces breaking changes (new authentication system, SQL 2017+, web.config changes, WSFED reconfiguration). Read Upgrading to iCL Portal 1.60+ and follow the steps there in addition to the general upgrade flow above.

Upgrading the web front end​

When a new iCL Portal version is released, there are generally the following steps to take

  • Backup the SQL Databases of iCL Portal and make sure that a restore actually works
  • Backup your current Web.config and NLog.config of the iCL Portal Web Front-end
  • Delete all files in the bin folder of the website except App_Data, Web.config and NLog.config
recycle app pool

In case some file cannot be deleted because it is being used by another process (IIS), open IIS Manager and recycle the application pool of the iCL Portal website.

DO NOT RESTART IIS

Do not restart IIS, as this will interrupt any pending requests and may cause data corruption and/or data loss!

  • Extract the iCL.Portal.xxxx.zip archive into the web-site folder.

  • finally, run the "migrate_databases.bat" file. It will ask you whether you would like to apply any pending DB schema changes to all the tenant databases of iCL Portal.

  • Confirm with Y and press enter.

Data migrations may take a while

From iCL Portal 1.60 onwards, migrate_databases.bat also runs data migrations (not just schema changes). These can take considerable time on large tenants.

The system stays operable during data migrations

The system is already operable and can be used while the data migrations are running. Users can continue working; you do not need to keep them locked out until the migrations finish.

  • Open the web.config file and replace the <runtime>...</runtime> element with the one provided in the package (runtime.xml)

  • Follow additional instructions in the provided readme (like modifications of the Web.config) in the accompanying upgrade manual.

Upgrading the dox42 host​

The dox42 host ships as a self-contained Windows service (iCLPortalDox42). Its release packages contain empty operator-settable values, so blindly copying a new package over an existing install would wipe the connection strings, iKey, tags, and log folder. Use upgrade.bat instead.

  1. Do not extract the new package over the existing install.
  2. Extract the new Dox42Host v{version}.zip into a fresh folder (e.g. C:\Installers\Dox42Host-v{version}).
  3. Run upgrade.bat as administrator from the extracted folder, passing the existing install path (or enter it when prompted):
    upgrade.bat "C:\Program Files\iCLPortalDox42"
  4. The script will:
    • stop the iCL.Portal.Reporting.Dox42$dox42_<MACHINE> service,
    • mirror the new bin\ over the old one (removed DLLs are purged),
    • merge the existing operator values (Default connection string, StorageConnectionString, iKey, ApplicationInsights customer/environment tags, NLog logDir) from the old config into the new config files,
    • copy the updated root scripts (install.bat, uninstall.bat, config.bat, start.bat, upgrade.bat, upgrade.ps1),
    • offer to restart the service.
  5. If the new release introduces additional operator-settable keys, re-run config.bat in the install folder afterwards to review them.