Migrate

Note:

Learn about product name changes here.

Citrix provides you with a toolkit to migrate your existing on-premises Workspace Environment Management (WEM) database into the WEM service. The toolkit includes a wizard to generate an SQL file containing the contents of your WEM database, and a simple way to upload the SQL file to the WEM service Azure database. This article describes how to complete your on-premises database migration. Review the entire sequence before starting the migration process so that you know what to expect.

Warning:

  • After your migration completes successfully, all data associated with your current WEM service database will be lost.

Note:

  • You can migrate your WEM database only after your WEM service is successfully provisioned.

  • Before starting the migration process, Citrix recommends that you back up your on-premises WEM database.

  • Before starting the migration process, Citrix recommends that you configure your database maintenance on the Database Maintenance tab. Doing so reduces the size of your WEM database so that you have a better migration experience. For more information on database maintenance, see Configure the infrastructure service.

  • If you attempt to migrate your WEM database while the WEM service is upgrading, the following error message appears in the notifications area in the top-right corner of the Citrix Cloud user interface: “The Workspace Environment Management database migration has failed because the Workspace Environment Management service is upgrading. Please try again later.” When this happens, try uploading the SQL file after your WEM service is upgraded successfully. Service upgrades are also notified in the top-right corner of the Citrix Cloud user interface.

System requirements

The toolkit currently supports only the migration from the WEM 4.7 and WEM 1808 database. To migrate from an earlier version, upgrade WEM 4.x to WEM 4.7 or WEM 1808, and then migrate the database to the WEM service. For more information on upgrading, see Upgrade a deployment.

Get started

Log on to your Citrix Cloud account. For more information, see What is a Citrix Cloud account.

Migrate your on-premises database

Step 1: Download the migration tool

Download the migration tool (WEM-migration-tool.zip) from the WEM service Downloads tab. Extract the zip file to a convenient folder.

Note:

Citrix recommends that you run the migration tool on the machine where the infrastructure service is installed. Doing so ensures that the infrastructure service can connect to the WEM database and the machine on which the infrastructure service is running has the necessary components.

Step 2: Export the database data to an SQL file

Run the Citrix WEM Migration Tool.exe contained in the zip file.

Citrix WEM migration tool

Enter the following data in the wizard:

Server and instance name. Address of the SQL server instance that hosts the database. It must be reachable from the infrastructure server exactly as typed here.

Use integrated connection (Windows credentials). If selected, allows the Database Migration Wizard to use the Windows account of the identity it is running under to connect to the SQL server, and then generate the SQL file containing the contents of your on-premise WEM database. If this Windows account does not have sufficient permissions, run the Citrix WEM Migration Tool.exe using a Windows account with sufficient privileges, or clear this option and provide an SQL account with sufficient privileges instead.

Database name. Name of the database to be migrated.

Target. The desired folder for saving the SQL file containing the contents of your on-premises WEM database. Use the Browse button to navigate to the folder where you want to save the SQL file.

Note:

When saving as a file, your WEM database file is automatically renamed to “Your database name_upload.7z”.

Click Export to start the database export process or click Cancel to exit the Database Migration Wizard.

During the export process, the Database Migration Status window appears.

After the export process finishes, click Finish to close the window and to return to the Database Migration Wizard.

Note:

  • Depending on your database size, the export process can take from a few seconds to a few minutes or even a few hours.

  • If you close the Database Migration Status window when the database export is in progress, you return to the Database Migration Wizard, but the Export button is disabled because the database export process continues in the background. To stop the export process completely, click Cancel.

If there are errors during export, check the Citrix WEM Migration Tool Debug Log file in the migration tool folder that contains the Citrix WEM Migration Tool.exe.

Step 3: Upload the SQL file into your WEM service database

Important:

Do not close the Workspace Environment Management service page before the upload finishes. Otherwise, your SQL file cannot be uploaded successfully.

  1. On the WEM service Downloads tab, click Upload to start the upload process.
  2. Click Choose File on the Upload SQL file page and then select the SQL file to be uploaded.
  3. Click OK to start the upload and to return to the WEM service Downloads tab.

After you return to the WEM service Downloads tab, the progress message appears under Upload, which updates as the upload progresses. After your SQL file is uploaded successfully, the migration process starts automatically.

Note:

After your SQL file is uploaded successfully, you must wait 10 minutes before you can upload again.

After migration

You will receive a notification message a few hours later, communicating the result of the migration to you. See notifications in the top-right corner of the Citrix Cloud user interface. After the migration completes successfully, perform the following steps on the Manage tab to view the data migrated from your on-premises WEM database.

Step 1: Reconnect to the WEM service

  1. Hover the mouse over the drop-down menu on the WEM service Manage tab.
  2. Click the Citrix Workspace icon.
  3. Click the ellipsis icon to expand additional options.
  4. Click Log Off to disconnect from the WEM service.
  5. Refresh your browser window to reconnect to the WEM service and to view the data migrated from your on-premises WEM database.

Step 2: Install the WEM agent on your machine

After you migrate your WEM database, you must install the WEM agent on your machine. The agent is available on the service’s Downloads tab.

Note:

Even if the latest WEM service agent is installed on your machine, you must reinstall it.