UNIFYConnect v8.0

Appearance

Upgrading UNIFYConnect ​

Overview ​

UNIFYConnect upgrades are not performed in place. Install the new version in a separate directory, migrate the configuration, run any applicable database upgrade scripts, 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, and scheduled operations, then stop the UNIFYConnect service.
  2. Back up the UNIFYConnect database.
  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 moves the service to .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 v8 PowerShell worker has its own dependency chain and must not be replaced with files from an earlier installation.
  • Decide whether PowerShell scripts will remain in process or use the new out-of-process execution mode. In-process execution remains the v8.0 default unless it is overridden.

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.

Installing the new version ​

  1. Extract the new package to an empty directory, as described in Installing the UNIFYConnect Service.
  2. Copy the existing Services\Extensibility configuration into the new installation.
  3. Compare any configuration files supplied by the new version with their previous counterparts and merge local customisations without removing new settings.
  4. Merge local Services\appsettings.json changes into the new file rather than replacing it. This is particularly important for the v8 powerShellSettings section.
  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 the latest version supported by UNIFYConnect v8.
  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-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.0 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

SQL Snapshot Isolation is required for UNIFYConnect v6 and later.

PostgreSQL ​

The v8.0 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

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 the Setup\install-windows-service.ps1 script 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 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.