Upgrade a deployment


You can upgrade Workspace Environment Management (WEM) deployments to newer versions without having to first set up new machines or sites; this is called an in-place upgrade.

In-place upgrades from versions earlier than Workspace Environment Management 4.7 to version 1808 or later are not supported. To upgrade from any of those earlier versions, you need to upgrade to version 4.7 first and then upgrade to the target version. For details, see this table:

From To In-place upgrade supported
4.6 and earlier 4.7 Yes
4.6 and earlier 1808 or later No (upgrade to version 4.7 before upgrading to the target version)
4.7 1808 or later Yes


The WEM database, infrastructure service, and administration console must all be of the same version.

The Workspace Environment Management components must be upgraded in the following order:

  1. Infrastructure services
  2. Database
  3. Administration console
  4. Agent

Step 1: Upgrade the infrastructure services

To upgrade the Workspace Environment Management infrastructure services, run the new Workspace Environment Management infrastructure services setup on your infrastructure server. The upgrade procedure is otherwise identical to the installation procedure.


After you upgrade the Infrastructure Services, you must reconfigure the Infrastructure Services using the WEM Infrastructure Service Configuration utility. See Configure the infrastructure service.

Upgrade the operating system of an infrastructure server

To upgrade the operating system of an infrastructure server, first install the infrastructure service on a different machine with the new operating system, manually configure it with identical infrastructure service settings, and then disconnect the “old” infrastructure server.

Step 2: Upgrade the database


The database upgrade process is not reversible. Ensure that you have a valid database backup before launching the upgrade process.


You can also upgrade the database using the Workspace Environment Management PowerShell SDK module. For SDK documentation, see Citrix Developer Documentation.

Use the WEM Database Management Utility to update the database. This is installed on your Workspace Environment Management infrastructure server during the infrastructure services installation process.


If you are using Windows authentication for your SQL Server, run the database upgrade utility under an identity that has sysadmin permissions.

1. From the Start menu select Citrix>Workspace Environment Management>WEM Database Management Utility.

2. Click Upgrade Database.

WEM database upgrade

Server and instance name. Address of the SQL Server\instance on which the database is hosted. It must be reachable exactly as entered from the infrastructure server.

Database name. Name of the database to be upgraded.

Infrastructure service uses Windows authentication.

When this option is cleared (the default) the database expects the infrastructure service to connect to it using the vuemUser SQL user account. The vuemUser SQL user account is created by the installation process. This requires Mixed-Mode Authentication to be enabled for the SQL instance.

When this option is selected, the database expects the infrastructure service to connect to it using a Windows account. In this case the Windows account you select must not already have a login on the SQL instance. In other words, you cannot use the same Windows account to run the infrastructure service as you used to create the database.

The option Use integrated connection is selected by default. It allows the wizard to use the Windows account of the identity it is running under to connect to SQL and create the database. If this Windows account does not have sufficient permissions to create the database, you can either run the database management utility as a Windows account with sufficient privileges, or you can clear this option and provide an SQL account with sufficient privileges instead.

Click Upgrade to start the database upgrade process. Once you are notified that the database upgrade has completed successfully, you can exit the application.

If there are errors during the database upgrade, please check the VUEM Database Management Utility Log file in your Workspace Environment Management infrastructure services installation directory.

Step 3: Upgrade the administration console

All Workspace Environment Management settings configured with the Administration Console are stored in the database and are preserved during upgrade.

To upgrade the administration console, run the administration console setup executable. The procedure is otherwise identical to the installation procedure.

Step 4: Upgrade the agent


  • Before upgrading an agent, make sure no users are logged in. This ensures that the upgrade process can modify the files on that machine.
  • The version of the WEM infrastructure service must be equal to or greater than the version of the WEM agent. Citrix recommends that you upgrade the agent to the latest version so that you can use the most recent features.

To upgrade the agent, run the new agent setup executable on the target machine.

Upgrade a deployment