UNIFYConnect v8.1

Appearance

Upgrading UNIFYConnect ​

Overview ​

UNIFYConnect upgrades are not performed in place. Install the new version in a separate directory, migrate the configuration, run every applicable database upgrade script, and then redirect the service and web component to the new installation.

NOTE

Only UNIFYBroker v5.3 can be upgraded directly to UNIFYConnect v6 or later. If the installed version is older than v5.3, first follow the legacy upgrade documentation.

Before Upgrading ​

  1. Stop connector, adapter, channel, Link, and scheduled operations, then stop the UNIFYConnect service.
  2. Back up the UNIFYConnect database and any separate module or plug-in databases.
  3. Back up the installation directory, particularly Services\Extensibility, Services\appsettings.json, installed plug-ins, and any locally configured PowerShell policy.
  4. Review the release notes for UNIFYConnect and every installed module or plug-in.
  5. Download the package that matches the target host (win-x64, win-arm64, linux-x64, or linux-arm64).

WARNING

Do not extract the new version over the existing installation. Do not copy old Services\Libs, Services\Workers, or Services\Patches content into the new installation.

Upgrading from UNIFYConnect v7 to v8 ​

UNIFYConnect v8 uses .NET 10 and PowerShell 7.5. Before upgrading:

  • Install the .NET 10 ASP.NET Core Runtime on the service host.
  • Test custom PowerShell scripts and modules with PowerShell 7.5. Review What's New in PowerShell 7.5 for compatibility changes.
  • Obtain v8-compatible versions of all plug-ins. Custom plug-ins must be rebuilt to target .NET 10.
  • Retain the complete Services\Workers\PowerShell directory supplied with v8. The PowerShell worker has its own dependency chain and must not be replaced with files from an earlier installation.

The core UNIFYConnect database schema did not change between v7.4 and v8.0, so there is no core v7.4-to-v8.0 database upgrade script. Modules and plug-ins can have their own database requirements; follow their release notes separately.

Upgrading from UNIFYConnect v8.0 to v8.1 ​

UNIFYConnect v8.1 runs PowerShell components in the out-of-process worker by default. Before upgrading:

  • Review PowerShell Execution Modes and test custom scripts in worker-process mode.
  • Merge the new powerShellSettings objects from the supplied engine configuration files into existing configuration. Do not replace the new files with v8.0 copies.
  • Review any per-script execution overrides and worker concurrency, lifetime, and memory settings. See PowerShell Configuration.
  • Obtain v8.1-compatible versions of all modules and plug-ins.
  • Run upgrade-8-to-8-1.sql against the core database, using the script for the configured database provider.

Installing the New Version ​

  1. Extract the new package to an empty directory, as described in Installing the UNIFYConnect Service.
  2. Migrate the existing Services\Extensibility configuration file by file. Where the new package supplies a file with the same name, merge the existing configuration into the new file instead of overwriting it. Copy files that have no new counterpart.
  3. Confirm that settings introduced by the new version, particularly each engine's v8.1 powerShellSettings object, remain present after the merge.
  4. Merge local Services\appsettings.json changes into the new file rather than replacing it.
  5. If a local PowerShell execution policy was configured in Services\Libs\powershell.config.json, copy it to the equivalent location.
  6. Install compatible service plug-ins in the new Services\PlugIns directory. Use versions that explicitly support UNIFYConnect v8.1.
  7. Run all applicable database upgrade scripts as described below.
  8. Start the new installation as a console application and resolve any configuration, database, plug-in, or PowerShell errors before registering it as a service.

Upgrading from UNIFYBroker v5.3 ​

The configuration format changed from XML in UNIFYBroker v5.3 to JSON in UNIFYConnect v6. Copy the old Services\Extensibility directory into the new installation. On first start, the service attempts to convert the supported XML configuration.

Install v8.1-compatible versions of all plug-ins; v5.3 plug-in binaries are not compatible.

NOTE

After the service has started and the conversion has completed successfully, remove the old XML configuration files from the new Extensibility directory so they are not converted again.

Remove any existing UNIFYBroker v5.3 Windows service registration manually. The UNIFYConnect setup script does not remove the legacy service registration.

Database Upgrade Scripts ​

Database scripts are located under %InstallDir%\Database\SqlServer or %InstallDir%\Database\PostgreSql. Run only scripts that advance the existing database version, in version order. Do not run install.sql against an existing UNIFYConnect database.

Always take a full database backup before running an upgrade script. Consult the release notes for installed modules and plug-ins because they may supply additional scripts.

SQL Server ​

The v8.1 package contains these core upgrade scripts:

  • upgrade-5-3-to-6-1.sql
  • upgrade-6-1-to-7-0.sql
  • upgrade-7-3-to-7-4.sql
  • upgrade-8-to-8-1.sql

SQL Snapshot Isolation is required for UNIFYConnect v6 and later.

PostgreSQL ​

The v8.1 package contains these core upgrade scripts:

  • upgrade-5-3-to-6-1.sql
  • upgrade-6-1-to-7-0.sql
  • upgrade-7-2-to-7-3.sql
  • upgrade-8-to-8-1.sql

The absence of a script for a particular version transition means that the core database schema did not change for that transition. It does not remove the need to check module and plug-in upgrade instructions.

Registering the Upgraded Service ​

Windows ​

Run Setup\install-windows-service.ps1 from the new installation with administrator privileges. The script replaces the current UNIFYConnect service registration so that it targets the new installation. See Installing the UNIFYConnect Service.

Linux ​

If UNIFYConnect runs under systemd, update WorkingDirectory and ExecStart to the new installation, reload the unit, and restart it:

bash
sudo systemctl daemon-reload
sudo systemctl restart unifyconnect
sudo systemctl status unifyconnect

Upgrading the Web Component ​

  1. Extract the new web component package to a separate directory.
  2. Merge required customisations from the previous Web.config into the new file. Preserve settings introduced by the new version.
  3. Install web component plug-ins that correspond to the service plug-ins.
  4. Reconfigure IIS to target the new installation, following Installing the UNIFYConnect Web Component.

The v8 web component requires Windows and the .NET Framework 4.8.1 Runtime.

Verification and Cleanup ​

Verify the new service and web component before removing the previous installation. At minimum:

  • Open the service Swagger page and confirm that the API responds.
  • Review startup logs for configuration conversion, database, plug-in, and PowerShell errors.
  • Test representative imports, adapter generation, channel and Link operations, scheduled jobs, and custom PowerShell scripts.
  • Confirm that the web component connects to the new service.

After the upgrade is confirmed, retain the backups according to your recovery policy and remove superseded installation directories when they are no longer needed.

©2026 UNIFY Solutions Pty. Ltd.