Upgrade a deployment
Introduction
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 |
Note:
- The WEM database, infrastructure service, and administration console must all be of the same version.
- Keep the following in mind when you plan to upgrade a WEM deployment earlier than 2006 to 2209 or later: To avoid database upgrade failures, upgrade to 2103 first and then to 2209 or later.
The Workspace Environment Management components must be upgraded in the following order:
- Infrastructure services
- Database
- Reconfiguring the infrastructure services
- Administration console
- 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.
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.
Note:
After you upgrade to Windows Server 2022, the WEM infrastructure service might fail to respond. As a workaround, reinstall the infrastructure service and configure it to connect to the WEM database.
Step 2: Upgrade the database
Important:
The database upgrade process is not reversible. Ensure that you have a valid database backup before launching the upgrade process.
Tip:
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.
Note:
If you are using Windows authentication for your SQL Server, run the database upgrade utility under an identity that has sysadmin permissions.
-
From the Start menu, select Citrix>Workspace Environment Management > WEM Database Management Utility.
-
Click Upgrade Database.
-
In the database upgrade wizard, type the required information.
-
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. By default, this option is not selected. In this case, the infrastructure service connects to the database using the vuemUser SQL user account. (The vuemUser SQL user account is created during the installation process.) Verify that Mixed-Mode Authentication is enabled for the SQL instance.
When selected, the infrastructure service connects to the database 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, do not use the same Windows account that you used to create the database to run the infrastructure service.
-
Use integrated connection. By default, this option is selected. The option lets the wizard use the Windows account of the identity under which the wizard is running to connect to SQL Server and to create the database. If this Windows account does not have sufficient permissions to create the database, run the database management utility as a Windows account with sufficient privileges, or clear this option and type a SQL account with sufficient privileges instead.
-
-
Click Upgrade to start the database upgrade process. After the database upgrade completes successfully, exit the wizard.
If errors occur during the database upgrade, check the VUEM Database Management Utility Log file available in your Workspace Environment Management infrastructure services installation folder.
Step 3: Reconfigure the infrastructure services
Reconfigure the Infrastructure Services using the WEM Infrastructure Service Configuration utility. See Configure the infrastructure service.
Step 4: 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 5: Upgrade the agent
Important:
- 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.