Product Documentation

About the Upgrade Tool

May 25, 2016

To upgrade from XenMobile 9.0 - MDM edition, App Edition, and Enterprise Edition - to XenMobile 10.1, you use the Upgrade Tool. You can download the tool from the downloads page. The fixed and known issues in this release are listed later in this article:

The latest release of the Upgrade Tool includes UI improvements, support for Remote PostgreSQL 9.3.11, and support for Device Manager 9.0 RP3 and App Controller RP7.

The Upgrade Tool is built within the XenMobile 10.1 virtual machine. You enable the one-time only wizard through the command-line console during the initial installation of XenMobile 10.1.

Upgrade Paths

An upgrade path is a recommended sequence to ensure that your data is properly migrated. This section contains the upgrade paths for the following device type and enrollment mode combinations:

  • iOS and Android devices (all enrollment modes), plus Windows phones and tablets enrolled in MDM mode
  • Windows phones enrolled in Enterprise mode

There is no upgrade path for Windows phones or tablets enrolled in MAM mode or for Windows tablets enrolled in Enterprise mode.

iOS and Android devices (all enrollment modes) and Windows phones and tablets (MDM)

To upgrade, follow the sequence starting with the step that matches the version you are upgrading.

1. If you are using XenMobile 8.6 or 8.7, first upgrade to XenMobile 9.0.

You cannot use the Upgrade Tool to upgrade from XenMobile 8.6 or 8.7 to XenMobile 10.1.

2. Use the Upgrade Tool to upgrade from XenMobile 9.0 to XenMobile 10.1.

  • After upgrading XenMobile 9 to XenMobile 10.1, some customers have reported issues with accessing the WorxStore, opening apps, and other features. While Citrix works to resolve these issues, you can temporarily roll back the upgrade to XenMobile 9. For details, see Rolling Back XenMobile Upgrades.
  • When the Multi-Tenant Console (MTC) is enabled on XenMobile 9.0, you can migrate the MTC to XenMobile 10.1. For steps, see Upgrading the MTC tenant server to XenMobile 10.1.

3. Update XenMobile 10.1 to XenMobile 10.3 (or 10.3.5).

When this update follows an upgrade from XenMobile 9.0 to 10.1, you can migrate the data for supported Android, iOS, and Windows device types.

4. Update XenMobile 10.3 to XenMobile 10.3.5.

Windows phones (Enterprise mode)

The following steps are recommended for upgrading a XenMobile 9.0 Enterprise environment, with Windows Phones enrolled in Enterprise mode and using Worx Home 9.x, to XenMobile 10.3.

1. Install the latest patches for Device Manager and App Controller.

2. Download the latest Upgrade Tool.

3. Upgrade Worx Home on Device Manager to 10.2 and then deploy Worx Home.

If users are running Worx Home 9.x with Windows phone enrollment, we recommend that you upgrade Worx Home to 10.2 before upgrading. And, as soon as the upgrade is done to 10.1, XenMobile server must be upgraded to 10.3 before connecting the devices.

4. Manually uninstall Worx Home 9.x from user devices.

5. Instruct users to go to the Download Hub on their phone to install Worx Home 10.2, which you deployed from Device Manager.

6. Upgrade to XenMobile 10.1 and then immediately upgrade to XenMobile 10.3 before connecting devices to the upgraded XenMobile server.

7. Make NetScaler changes for devices to connect back, as described in Upgrade Tool Post-Requisites.

Upgrade Overview (XenMobile 9.0 to 10.1)

The following figures illustrate the basic steps you take to upgrade from XenMobile 9.0 to XenMobile 10.1.

localized image
localized image
localized image

See Prerequisites and XenMobile 10.1 Known and Fixed Issues, as well as the Upgrade Tool fixed and known issues listed here, before starting the migration to XenMobile 10.1.

Upgrade Tool Fixed Issues in This Release


For a list of fixed issues in earlier releases of the Upgrade Tool, download this PDF.

After upgrading from XenMobile 9 to XenMobile 10.1 and then updating to XenMobile 10.3, webclip policies are not deployed in Windows 10 devices that had been enrolled in XenMobile 9. The webclip policies deploy to Windows 10 devices that are newly enrolled in XenMobile 10.3. [#610101]

After upgrading from XenMobile 9 to XenMobile 10.1, VPP licensing in large volumes does not work. [#610418]

User subscriptions are not migrated if the subscription information includes the domain name in upper case. [#620542]

An app prepared with the Worx App SDK is not migrated if it contains a non-standard URL, such as not formatting the store ID in the URL as idapp-ID?mt=8. [#625920]

Upgrade Tool Known Issues in This Release


Be aware of this XenMobile 10.1 known issue, because it is likely that your XenMobile 9.0 host name may have an uppercase letter. In this case, after upgrading to XenMobile 10.1, devices cannot access the WorxStore. 

  • When you configure XenMobile server with an uppercase letter in the host name, such as, the WorxStore does not open on devices after the devices enroll. [#545527]

Data and policy issues

  • After upgrading, syslog server configuration data is not migrated to the XenMobile server. [#558539]
  • If the device setting in XenMobile 9.0 for maximum or minimum operating system is set to 10 or above and for excluded devices for MDX and enterprise apps, after upgrading, the rule does not migrate properly. Apps that should appear do not and apps that should not appear do. [#603412]
  •  When users upgrade from a XenMobile 9 deployment that is based on named SQL instances by using the recommended steps in the Supporting Named SQL Instances article to resolve a FQDN issue, the support bundle uploads successfully, but a database connection error appears. As a result, users cannot complete the upgrade. [#605775]
  • Some Restriction policy configurations are deprecated in 10.1. Therefore, XenMobile fails to deploy the entire Restriction policy successfully to Windows 10 phones after you upgrade from XenMobile 9 to XenMobile 10.1 and update to XenMobile 10.3. If you view and save the policy settings in XenMobile 10.3, however, the policy deploys successfully. [#608541]
  • In XenMobile 9.0, when you define the Users organizational unit (OU) in the LDAP connection parameters, after you upgrade to XenMobile 10, the full root context is not appended to users organizational unit. For example, OU=MDMUsers, OU=SALES should be OU=MDMUsers, OU=SALES, DC=citrite, DC=com. As a result, you need to make the update manually in XenMobile 10. [#635981]

Google Play apps

  • If you include a public Google Play app for Android devices with a default icon, after migrating, the default icon does not appear in the XenMobile console. You must either edit and save the app or click Check for Updates in order for the image to appear. [#557996]

SQL Server

  • The Upgrade Tool does not support named instances of XenMobile 9.0 SQL Server databases. The tool provides a port number, but no instance name. The upgrade fails with a java.sql.SQLException error if the tool attempts a connection to the unintended instance rather than the default instance. To fix the issues, see Supporting Named SQL Instances. [#575679]
  • If you use a PostgreSQL database, MAM devices are unable to re-enroll after an upgrade. To work around this issue, delete the device entries from XenMobile and send enrollment notifications to the users. [#632831]
  • If your Device Manager 9.0 server is set up using Local PostgreSQL and you use localhost as a reference for the database server, an upgrade will fail. To work around this, edit on the Device Manager 9.0 server and replace all localhost references with the IP address of the Device Manager database server, then continue with the Upgrade pre-requisites. [#635023]


Issues with RBAC settings occur after upgrading:

  • If you have RBAC roles configured with access restricted to LDAP and Active Directory or any child, after upgrading, when you log on to the XenMobile console as an administrator, the same settings are not selected.
  • If you have configured a super administrator role, all permissions are selected by default. After upgrading, only three permissions are selected - RBAC, Enrollment, and Release Management.
  • If you have created a custom super administrator role, all support permissions should be selected by default. After upgrading, none of the support permission settings is selected. [#569350, #569395, #569423]

Windows CE

  • Windows CE devices are not supported in XenMobile 10.1.

Worx Home and WorxStore

  • After you update XenMobile 10.1 to XenMobile 10.3, when users open Worx Home on iOS and Android devices, the WorxStore appears blank. As a workaround, either restart NetScaler or clear the NetScaler cache. [#609706]
  • Before upgrading from XenMobile 9 to XenMobile 10.1, if your WorxStore has a custom name, issues occur with enrollment, access to Worx Home and access to the Worx Store. As a workaround, change the store to the default setting of Store before upgrading. [#619458]
    For details on the prerequisite workaround, see Prerequisites.
  • Users with MAM-only devices are unable to authenticate to Worx Home after an upgrade from XenMobile 9.0 to XenMobile 10.1 followed by setting the LDAP option User search by to sAMAccountName and then upgrading to XenMobile 10.3.x. [#628233]

Android for Work

  • After an upgrade, SAML login for Android for Work fails because the SAML certificate has a .pem extension, which the XenMobile server won't import. [#631795]

To work around this issue, make sure XenMobile has the correct SAML certificate, as follows:

1. Export from XenMobile 9 App Controller the SAML certificate with a private key ( That certificate is in PEM format and has a .pem extension.

2. Use the openssl command to generate a PFX file from the PEM file:

openssl pkcs12 -export -out certificate.pfx  -in certificate.pem

3. Imported the PFX file into XenMobile 10.3 as a SAML keystore.

4. Export the SAML certificate without the private key from XenMobile 10.3 and then upload it to Android for Work domain.

What the Upgrade Tool Does

The XenMobile 10.1 Upgrade Tool migrates configuration and user data from the XenMobile 9.0 server to a new instance of XenMobile 10.1 with the same fully qualified domain name (FQDN).

  • Regardless of your XenMobile edition, you can do an upgrade test drive with production configuration data to compare XenMobile 9.0 and XenMobile 10.1 without affecting your production environment.
  • You can do a full production upgrade to move everything from XenMobile 9.0 to XenMobile 10.1. You cannot, however, move from the test drive to a production upgrade. Instead, you must begin again with the production upgrade. 

For architectural diagrams of XenMobile 10.1 deployments, see Architecture Overview.

When you choose Test Drive in the tool, only configuration data is migrated to XenMobile 10.1; no device (in the case of XenMobile Enterprise Edition deployments) or user data is migrated.

When you choose Upgrade in the tool, all configuration, device, and user data is migrated. When you log on to the XenMobile 10.1 console after the upgrade, you see all the user and device data that was migrated from XenMobile 9.0.

Note: This is not an in-place migration; all data is copied during migration, not moved, to XenMobile 10.1. Everything in XenMobile 9.0 remains intact until you move the XenMobile 10.1 server into production. When users connect to XenMobile 10.1 in production, if for some reason you want to revert to XenMobile 9.0, those users must re-enroll in XenMobile 9.0.

Citrix recommends that you do an upgrade test drive first to get a feel for how the process works and what you should see after you do a full production upgrade. After the test drive, you can do a full production upgrade to an isolated environment for further testing. After you have validated the upgrade, you can do another production upgrade to your production environment.

After a successful production upgrade, to move XenMobile 10.1 to live production, you must do the following:

1. If NetScaler is load balancing XenMobile Device Manager servers, you need to:

  • Create a new XenMobile 10.1 load balancing service.
  • Switch the XenMobile 9.0 service to the XenMobile 10.1 service.

2. For standalone environments, update the DNS entry to map the XenMobile 9.0 FQDN to the new XenMobile 10.1 server IP. This step is not required for clustered environments.

For more information, see Upgrade Tool Post-Requisites.

What the Upgrade Tool Does Not Do

The following information is not migrated to XenMobile 10.1 when you use the Upgrade Tool:
  • Licensing information.
  • Reports data.
  • Server group policies and associated deployments (not supported in XenMobile 10.1).
  • Managed Service Provider (MSP) group.
  • Policies and packages related to Windows CE and Windows 8.0.
  • Deployment packages not in use; for example, when no users or groups are assigned to a deployment package.
  • Any other configuration or user data as described in the migration.log file.
  • CXM Web (replaced by Citrix WorxWeb).
  • DLP policies (replaced by Citrix Sharefile).
  • Custom Active Directory attributes.
  • If you have configured multiple branding policies, the branding policy is not migrated. XenMobile 10.1 supports one branding policy; you have to leave one branding policy in XenMobile 9.0 to successfully migrate to XenMobile 10.
  • Any settings in the auth.jsp file in XenMobile 9.0 that are used to restrict access to the console. Console access restrictions in XenMobile 10.1 are firewall settings that you can configure in the command-line interface.
  • Sys log server configurations.
  • Form-fill connectors configured on XenMobile 9.0 (not supported in XenMobile 10.1).
Also note the following changes with XenMobile 10.1:
  • XenMobile 10.1 does not support Active Directory users who are assigned to local groups.
  • The local groups hierarchy is flattened.

Planning Your Upgrade


For each of the stages, follow the steps in Enabling and Running the Upgrade Tool and Prerequisites. The upgrade process is complex; be sure you complete the prerequisites before you begin. If you enter the wrong certificate password, for example, the upgrade fails. In the case of failure, you must configure a new XenMobile 10.1 instance in the command-line console and start the Upgrade Tool again.

Citrix recommends that you do your upgrade in the following stages.

  1. Do a test drive in a staging environment.
    1. Set up a fresh NetScaler 10.5 with NetScaler Gateway and NetScaler load balancing virtual servers, preferably set up using the XenMobile 10 utility.
    2. Make the appropriate firewall and DNS changes.
  2. Do a production upgrade in a staging environment.
    1. Adjust the existing NetScaler configuration by following the post-requisite steps.
    2. Make the appropriate firewall and DNS changes.
  3. Do a production upgrade in your production environment and go live.
    1. Plan for downtime while running the migration.
    2. Adjust the existing NetScaler configuration by following the post-requisite steps.
    3. Make the appropriate firewall and DNS changes.

Terminology Change with XenMobile 10.1

Note that after you upgrade, deployment packages in Device Manager are now referred to as delivery groups in XenMobile 10.1, as shown in the following figure. For more information, see Managing Delivery Groups.


Delivery groups


Inside the delivery group, you can view the policies, actions, and apps required for the group of users who require the resources.



XenMobile Enterprise Edition Deployment Device Enrollment After Upgrade

Users do not need to re-enroll their devices after you do a production upgrade to XenMobile 10.1. The devices should connect automatically to the XenMobile 10.1 server based on the heartbeat interval. Users may, however, be asked to re-authenticate before the device can reconnect.

If you want to connect a device to XenMobile 10.1 immediately, on the device, use WorxHome > Device Info > Refresh Policy.

After the user devices connect, check to make sure you see the devices in the XenMobile console, as shown in the following figure.