Citrix Virtual Apps and Desktops

Migrate XenApp 6.x

Important:

Migrating moves data from an earlier deployment to a newer version. The process includes installing newer components and creating a new Site, exporting data from the older farm, and then importing the data to the new Site.

Open source migration scripts are available at https://github.com/citrix/xa65migrationtool. However, Citrix does not support these scripts.

The remainder of this article contains information that can be used as a reference with the open source migration scripts.

Introduction

You can use the Migration Tool described in this article to migrate from XenApp 6.x to XenApp 7.6. Then, you can upgrade from XenApp 7.6 to a supported LTSR or the current Citrix Virtual Apps and Desktops release; see Upgrade a deployment.

For information about architecture, component, and feature changes that were introduced with the 7.x releases, see Changes in 7.x.

XenApp 6.x Migration Tool

The XenApp 6.x Migration Tool is a collection of PowerShell scripts containing cmdlets that migrate XenApp 6.x (6.0 or 6.5) policy and farm data. On the XenApp 6.x controller server, you run export cmdlets that gather that data into XML files. Then, from the XenApp 7.6 Controller, you run import cmdlets that create objects using the data gathered during the export.

The following sequence summarizes the migration process; details are provided later.

  1. On a XenApp 6.0 or 6.5 controller:
    1. Import the PowerShell export modules.
    2. Run the export cmdlets to export policy and/or farm data to XML files.
  2. Copy the XML files (and icons folder if you chose not to embed them in the XML files during the export) to the XenApp 7.6 Controller.
  3. On the XenApp 7.6 Controller:
    1. Import the PowerShell import modules.
    2. Run the import cmdlets to import policy and/or farm data (applications), using the XML files as input.
  4. Complete post-migration steps.

Before you run an actual migration, you can export your XenApp 6.x settings and then perform a preview import on the XenApp 7.6 site. The preview identifies possible failure points so you can resolve issues before running the actual import. For example, a preview might detect that an application with the same name already exists in the new XenApp 7.6 site. You can also use the log files generated from the preview as a migration guide.

Unless otherwise noted, the term 6.x refers to XenApp 6.0 or 6.5.

Migration Tool package

The migration tool contains two separate, independent packages:

  • ReadIMA: Contains the files used to export data from your XenApp 6.x farm, plus shared modules.

    Module or file Description
    ExportPolicy.psm1 PowerShell script module for exporting XenApp 6.x policies to an XML file.
    ExportXAFarm.psm1 PowerShell script module for exporting XenApp 6.x farm settings to an XML file.
    ExportPolicy.psd1 PowerShell manifest file for script module ExportPolicy.psm1.
    ExportXAFarm.psd1 PowerShell manifest file for script module ExportXAFarm.psm1.
    LogUtilities.psm1 Shared PowerShell script module that contains logging functions.
    XmlUtilities.psd1 PowerShell manifest file for script module XmlUtilities.psm1.
    XmlUtilities.psm1 Shared PowerShell script module that contains XML functions.
  • ImportFMA: Contains the files used to import data to your XenApp 7.6 farm, plus shared modules.

    Module or file Description
    ImportPolicy.psm1 PowerShell script module for importing policies to XenApp 7.6.
    ImportXAFarm.psm1 PowerShell script module for importing applications to XenApp 7.6
    ImportPolicy.psd1 PowerShell manifest file for script module ImportPolicy.psm1.
    ImportXAFarm.psd1 PowerShell manifest file for script module ImportXAFarm.psm1.
    PolicyData.xsd XML schema for policy data.
    XAFarmData.xsd XML schema for XenApp farm data.
    LogUtilities.psm1 Shared PowerShell script module that contains logging functions.
    XmlUtilities.psd1 PowerShell manifest file for script module XmlUtilities.psm1.
    XmlUtilities.psm1 Shared PowerShell script module that contains XML functions.

Limitations

  • Not all policies settings are imported; see Policy settings not imported. Settings that are not supported are ignored and noted in the log file.
  • While all application details are collected in the output XML file during the export operation, only server-installed applications are imported into the XenApp 7.6 site. Published desktops, content, and most streamed applications are not supported (see the Import-XAFarm cmdlet parameters in Step-by-step: import data for exceptions).
  • Application servers are not imported.
  • Many application properties are not imported because of differences between the XenApp 6.x Independent Management Architecture (IMA) and the XenApp 7.6 FlexCast Management Architecture (FMA) technologies; see Application property mapping.
  • A Delivery Group is created during the import. See Advanced use for details about using parameters to filter what is imported.
  • Only Citrix policy settings created with the AppCenter management console are imported; Citrix policy settings created with Windows Group Policy Objects (GPOs) are not imported.
  • The migration scripts are intended for migrations from XenApp 6.x to XenApp 7.6 only.
  • Nested folders greater than five levels deep are not supported by Studio and will not be imported. If your application folder structure includes folders more than five levels deep, consider reducing the number of nested folder levels before importing.

Security considerations

The XML files created by the export scripts can contain sensitive information about your environment and organization, such as user names, server names, and other XenApp farm, application, and policy configuration data. Store and handle these files in secure environments.

Carefully review the XML files before using them as input when importing policies and applications, to ensure they contain no unauthorized modifications.

Policy object assignments (previously known as policy filters) control how policies are applied. After importing the policies, carefully review the object assignments for each policy to ensure that there are no security vulnerabilities resulting from the import. Different sets of users, IP addresses, or client names may be applied to the policy after the import. The allow/deny settings may have different meanings after the import.

Logging and error handling

The scripts provide extensive logging that tracks all cmdlet executions, informative messages, cmdlet execution results, warnings, and errors.

  • Most Citrix PowerShell cmdlet use is logged. All PowerShell cmdlets in the import scripts that create new site objects are logged.
  • Script execution progress is logged, including the objects being processed.
  • Major actions that affect the state of the flow are logged, including flows directed from the command line.
  • All messages printed to the console are logged, including warnings and errors.
  • Each line is time-stamped to the millisecond.

Citrix recommends specifying a log file when you run each of the export and import cmdlets.

If you do not specify a log file name, the log file is stored in the current user’s home folder (specified in the PowerShell $HOME variable) if that folder exists; otherwise, it is placed in the script’s current execution folder. The default log name is “XFarmYYYYMMDDHHmmSS-xxxxxx” where the last six digits constitute a random number.

By default, all progress information is displayed. To suppress the display, specify the NoDetails parameter in the export and import cmdlet.

Generally, a script stops execution when an error is encountered, and you can run the cmdlet again after clearing the error conditions.

Conditions that are not considered errors are logged; many are reported as warnings, and script execution continues. For example, unsupported application types are reported as warnings and are not imported. Applications that already exist in the XenApp 7.6 site are not imported. Policy settings that are deprecated in XenApp 7.6 are not imported.

The migration scripts use many PowerShell cmdlets, and all possible errors might not be logged. For additional logging coverage, use the PowerShell logging features. For example, PowerShell transcripts log everything that is printed to the screen. For more information, see the help for the Start-Transcript and Stop-Transcript cmdlets.

Requirements, preparation, and best practices

To migrate, you must use the Citrix XenApp 6.5 SDK. Download that SDK from https://www.citrix.com/downloads/xenapp/sdks/powershell-sdk.html.

Review this entire article before beginning a migration.

You should understand basic PowerShell concepts about execution policy, modules, cmdlets, and scripts. Although extensive scripting expertise is not required, you should understand the cmdlets you execute. Use the Get-Help cmdlet to review each migration cmdlet’s help before executing it. For example: Get-Help -full Import-XAFarm.

Specify a log file on the command line and always review the log file after running a cmdlet. If a script fails, check and fix the error identified in the log file and then run the cmdlet again.

Good to know

  • To facilitate application delivery while two deployments are running (the XenApp 6.x farm and the new XenApp 7.6 site), you can aggregate both deployments in StoreFront or Web Interface. See the eDocs documentation for your StoreFront or Web Interface release.
  • Application icon data is handled in one of two ways:

    • If you specify the EmbedIconData parameter in the Export-XAFarm cmdlet, exported application icon data is embedded in the output XML file.
    • If you do not specify the EmbedIconData parameter in the Export-XAFarm cmdlet, exported application icon data is stored under a folder named by appending the string “-icons” to the base name of the output XML file. For example, if the XmlOutputFile parameter is “FarmData.xml” then the folder “FarmData-icons” is created to store the application icons.

      The icon data files in this folder are .txt files that are named using the browser name of the published application (although the files are .txt files, the stored data is encoded binary icon data, which can be read by the import script to re-create the application icon). During the import operation, if the icon folder is not found in the same location as the import XML file, generic icons are used for each imported application.

  • The names of the script modules, manifest files, shared module, and cmdlets are similar. Use tab completion with care to avoid errors. For example, Export-XAFarm is a cmdlet. ExportXAFarm.psd1 and ExportXAFarm.psm1 are files that cannot be executed.
  • In the step-by-step sections below, most <string> parameter values show surrounding quotation marks. These are optional for single-word strings.

For exporting from the XenApp 6.x server

  • The export must be run on a XenApp 6.x server configured with the controller and session-host (commonly known as controller) server mode.
  • To run the export cmdlets, you must be a XenApp administrator with permission to read objects. You must also have sufficient Windows permission to run PowerShell scripts; the step-by-step procedures below contain instructions.
  • Ensure the XenApp 6.x farm is in a healthy state before beginning an export. Back up the farm database. Verify the farm’s integrity using the Citrix IMA Helper utility (CTX133983). From the IMA Datastore tab, run a Master Check (and then use the DSCheck option to resolve invalid entries). Repairing issues before the migration helps prevent export failures. For example, if a server was removed improperly from the farm, its data might remain in the database; that could cause cmdlets in the export script to fail (for example, Get-XAServer -ZoneName). If the cmdlets fail, the script fails.
  • You can run the export cmdlets on a live farm that has active user connections; the export scripts read only the static farm configuration and policy data.

For importing to the XenApp 7.6 server

  • You can import data to XenApp 7.6 deployments (and later supported versions). You must install a XenApp 7.6 Controller and Studio, and create a site before importing the data you exported from the XenApp 6.x farm. Although VDAs are not required to import settings, they allow application file types to be made available.
  • To run the import cmdlets, you must be a XenApp administrator with permission to read and create objects. A Full Administrator has these permissions. You must also have sufficient Windows permission to run PowerShell scripts; the step-by-step procedures below contain instructions.
  • No other user connections should be active during an import. The import scripts create many new objects, and disruptions may occur if other users are changing the configuration at the same time.

Remember that you can export data and then use the -Preview parameter with the import cmdlets to see what would happen during an actual import, but without actually importing anything. The logs will indicate exactly what would happen during an actual import; if errors occur, you can resolve them before starting an actual import.

Step-by-step: export data

Complete the following steps to export data from a XenApp 6.x controller to XML files.

  1. Download the XAMigration.zip migration tool package from the Citrix download site. For convenience, place it on a network file share that can be accessed by both the XenApp 6.x farm and the XenApp 7.6 site. Unzip XAMigration.zip on the network file share. There should be two zip files: ReadIMA.zip and ImportFMA.zip.

  2. Log on to the XenApp 6.x controller as a XenApp administrator with at least read-only permission and Windows permission to run PowerShell scripts.

  3. Copy ReadIMA.zip from the network file share to the XenApp 6.x controller. Unzip and extract ReadIMA.zip on the controller to a folder (for example: C:\XAMigration).

  4. Open a PowerShell console and set the current directory to the script location. For example: cd C:\XAMigration.

  5. Check the script execution policy by running Get-ExecutionPolicy.

  6. Set the script execution policy to at least RemoteSigned to allow the scripts to be executed. For example: Set-ExecutionPolicy RemoteSigned.

  7. Import the module definition files ExportPolicy.psd1 and ExportXAFarm.psd1: Import-Module .\\ExportPolicy.psd1 and Import-Module .\\ExportXAFarm.psd1.

    Good to know

    • If you intend to export only policy data, you can import only the ExportPolicy.psd1 module definition file. Similarly, if you intend to export only farm data, import only ExportXAFarm.psd1.
    • Importing the module definition files also adds the required PowerShell snap-ins.
    • Do not import the .psm1 script files.
  8. To export policy data and farm data, run the following cmdlets.

Policy data: Run Export-Policy.

Parameter Description
-XmlOutputFile “string.xml” XML output file name; this file will hold the exported data. Must have an .xml extension. The file must not exist, but if a path is specified, the parent path must exist. Default: None; this parameter is required.
-LogFile string Log file name. An extension is optional. The file is created if it does not exist. If the file exists and the NoClobber parameter is also specified, an error is generated; otherwise, the file’s content is overwritten. Default: See Logging and error handling.
-NoLog Do not generate log output. This overrides the LogFile parameter if it is also specified. Default: False; log output is generated
-NoClobber Do not overwrite an existing log file specified in the LogFile parameter. If the log file does not exist, this parameter has no effect. Default: False; an existing log file is overwritten
-NoDetails Do not send detailed reports about script execution to the console. Default: False; detailed reports are sent to the console
-SuppressLogo Do not print the message “XenApp 6.x to XenApp/XenDesktop 7.6 Migration Tool Version #yyyyMMdd-hhmm#” to the console. This message, which identifies the script version, can be helpful during troubleshooting; therefore, Citrix recommends omitting this parameter. Default: False; the message is printed to the console

Example: The following cmdlet exports policy information to the XML file named MyPolicies.xml. The operation is logged to the file named MyPolicies.log.

Export-Policy -XmlOutputFile ".\MyPolicies.XML" -LogFile ".\MyPolicies.Log"

Farm data: Run Export-XAFarm.

Parameter Description
XmlOutputFile “string.xml” XML output file name; this file will hold the exported data. Must have an .xml extension. The file must not exist, but if a path is specified, the parent path must exist. Default: None; this parameter is required.
-LogFile “string Log file name. An extension is optional. The file is created if it does not exist. If the file exists and the NoClobber parameter is also specified, an error is generated; otherwise, the file’s content is overwritten. Default: See Logging and error handling
-NoLog Do not generate log output. This overrides the LogFile parameter if it is also specified. Default: False; log output is generated
-NoClobber Do not overwrite an existing log file specified in the LogFile parameter. If the log file does not exist, this parameter has no effect. Default: False; an existing log file is overwritten
-NoDetails Do not send detailed reports about script execution to the console. Default: False; detailed reports are sent to the console
-SuppressLogo Do not print the message “XenApp 6.x to XenApp/XenDesktop 7.6 Migration Tool Version #yyyyMMdd-hhmm#” to the console. This message, which identifies the script version, can be helpful during troubleshooting; therefore, Citrix recommends omitting this parameter. Default: False; the message is printed to the console
-IgnoreAdmins Do not export administrator information. See Advanced use. Default: False; administrator information is exported
-IgnoreApps Do not export application information. See Advanced use. Default: False; application information is exported
-IgnoreServers Do not export server information. Default: False: server information is exported
-IgnoreZones Do not export zone information. Default: False; zone information is exported.
-IgnoreOthers Do not export information such as configuration logging, load evaluators, load balancing policies, printer drivers, and worker groups. Default: False; other information is exported. The purpose of this switch is to allow you to proceed with an export when an error exists that would not affect the actual data being used for the exporting or importing process.
-AppLimit integer Number of applications to be exported. See Requirements, preparation, and best practices. Default: All applications are exported
-EmbedIconData Embed application icon data in the same XML file as the other objects. Default: Icons are stored separately. See Requirements, preparation, and best practices
-SkipApps integer Number of applications to skip. See Advanced use. Default: No applications are skipped

Example: The following cmdlet exports farm information to the XML file named MyFarm.xml. The operation is logged to the file MyFarm.log. A folder named “MyFarm-icons” is created to store the application icon data files; this folder is at the same location as MyFarm.XML.

Export-XAFarm -XmlOutputFile ".\MyFarm.XML" -LogFile ".\MyFarm.Log"

After the export scripts complete, the XML files specified on the command lines contain the policy and XenApp farm data. The application icon files contain icon data files, and the log file indicate what occurred during the export.

Step-by-step: import data

Remember that you can run a preview import (by issuing the Import-Policy or Import-XAFarm cmdlet with the Preview parameter) and review the log files before performing an actual import.

Complete the following steps to import data to a XenApp 7.6 site, using the XML files generating from the export.

  1. Log on to the XenApp 7.6 controller as an administrator with read-write permission and Windows permission to run PowerShell scripts.

  2. If you have not unzipped the migration tool package XAMigration on the network file share, do so now. Copy ImportFMA.zip from the network file share to the XenApp 7.6 Controller. Unzip and extract ImportFMA.zip on the Controller to a folder (for example: C:\XAMigration).

  3. Copy the XML files (the output files generated during the export) from the XenApp 6.x controller to the same location on the XenApp 7.6 Controller where you extracted the ImportFMA.zip files.

    If you chose not to embed the application icon data in the XML output file when you ran the Export-XAFarm cmdlet, be sure to copy the icon data folder and files to the same location on the XenApp 7.6 controller as the output XML file containing the application data and the extracted ImportFMA.zip files.

  4. Open a PowerShell console and set the current directory to the script location: cd C:\XAMigration.
  5. Check the script execution policy by running Get-ExecutionPolicy.
  6. Set the script execution policy to at least RemoteSigned to allow the scripts to be executed. For example: Set-ExecutionPolicy RemoteSigned.
  7. Import the PowerShell module definition files ImportPolicy.psd1 and ImportXAFarm.psd1: Import-Module .\\ImportPolicy.psd1 and Import-Module .\\ImportXAFarm.psd1.

    Good to know:

    • If you intend to import only policy data, you can import only the ImportPolicy.psd1 module definition file. Similarly, if you intend to import only farm data, import only ImportXAFarm.psd1.
    • Importing the module definition files also adds the required PowerShell snap-ins.
    • Do not import the .psm1 script files.
  8. To import policy data and application data, run the following cmdlets.

Policy data: Run Import-Policy, specifying the XML file containing the exported policy data.

Parameter Description
-XmlInputFile “string.xml” XML input file name; this file contains data collected from running the Export-Policy cmdlet. Must have an .xml extension. Default: None; this parameter is required.
-XsdFile “string XSD file name. The import scripts use this file to validate the syntax of the XML input file. See Advanced use. Default: PolicyData.XSD
-LogFile “string Log file name. If you copied the export log files to this server, consider using a different log file name with the import cmdlet. Default: See Logging and error handling.
-NoLog Do not generate log output. This overrides the LogFile parameter, if it is also specified. Default: False; log output is generated
-NoClobber Do not overwrite an existing log file specified in the LogFile parameter. If the log file does not exist, this parameter has no effect. Default: False; an existing log file is overwritten
-NoDetails Do not send detailed reports about script execution to the console. Default: False; detailed reports are sent to the console
-SuppressLogo Do not print the message “XenApp 6.x to XenApp/XenDesktop 7.6 Migration Tool Version #yyyyMMdd-hhmm#” to the console. This message, which identifies the script version, can be helpful during troubleshooting; therefore, Citrix recommends omitting this parameter. Default: False; the message is printed to the console
-Preview Perform a preview import: read data from the XML input file, but do not import objects to the site. The log file and console indicate what occurred during the preview import. A preview shows administrators what would happen during a real import. Default: False; a real import occurs

Example: The folowing cmdlet imports policy data from the XML file named MyPolcies.xml. The operation is logged to the file named MyPolicies.log.

Import-Policy -XmlInputFile ".\MyPolicies.XML" -LogFile ".\MyPolicies.Log"

Applications: Run Import-XAFarm, specifying a log file and the XML file containing the exported farm data.

Parameter Description
-XmlInputFile “string.xml” XML input file name; this file contains data collected from running the Export-XAFarm cmdlet. Must have an .xml extension. Default: None; this parameter is required.
-XsdFile “string XSD file name. The import scripts use this file to validate the syntax of the XML input file. See Advanced use. Default: XAFarmData.XSD
-LogFile “string Log file name. If you copied the export log files to this server, consider using a different log file name with the import cmdlet. Default: See Logging and error handling
-NoLog Do not generate log output. This overrides the LogFile parameter, if it is also specified. Default: False; log output is generated
-NoClobber Do not overwrite an existing log file specified in the LogFile parameter. If the log file does not exist, this parameter has no effect. Default: False; an existing log file is overwritten
-NoDetails Do not send detailed reports about script execution to the console. Default: False; detailed reports are sent to the console
-SuppressLogo Do not print the message “XenApp 6.x to XenApp/XenDesktop 7.6 Migration Tool Version #yyyyMMdd-hhmm#” to the console. This message, which identifies the script version, can be helpful during troubleshooting; therefore, Citrix recommends omitting this parameter. Default: False; the message is printed to the console
-Preview Perform a preview import: read data from the XML input file, but do not import objects to the site. The log file and console indicate what occurred during the preview import. A preview shows administrators what would happen during a real import. Default: False; a real import occurs
-DeliveryGroupName “string Delivery Group name for all imported applications. See Advanced use. Default: “xenapp-farm-name - Delivery Group”
-MatchFolder “string Import only those applications in folders with names that match the string. See Advanced use. Default: No matching occurs
-NotMatchFolder “string Import only those applications in folders with names that do not match the string. See Advanced use. Default: No matching occurs
-MatchServer “string Import only those applications from servers whose names match the string. See Advanced use.
-NotMatchServer “string Import only those applications from servers whose names do not match the string. See Advanced use. Default: No matching occurs
-MatchWorkerGroup “string Import only those applications published to worker groups with names that match the string. See Advanced use. Default: No matching occurs
-NotMatchWorkerGroup “string Import only those applications published to worker groups with names that do not match the string. See Advanced use. Default: No matching occurs
-MatchAccount “string Import only those applications published to user accounts with names that match the string. See Advanced use. Default: No matching occurs
-NotMatchAccount “string Import only those applications published to user accounts with names that do not match the string. See Advanced use. Default: No matching occurs
-IncludeStreamedApps Import applications of type “StreamedToClientOrServerInstalled”. (No other streamed applications are imported.) Default: Streamed applications are not imported
-IncludeDisabledApps Import applications that have been marked as disabled. Default: Disabled applications are not imported

Example: The following cmdlet imports applications from the XML file named MyFarm.xml. The operation is logged to the file named MyFarm.log.

Import-XAFarm -XmlInputFile ".\MyFarm.XML" -LogFile ".\MyFarm.Log"

After the import completes successfully, complete the post-migration tasks.

Post-migration tasks

After successfully importing XenApp 6.x policies and farm settings into a XenApp 7.6 site, use the following guidance to ensure that the data has been imported correctly.

Policies and policy settings

Importing policies is essentially a copy operation, with the exception of deprecated settings and policies, which are not imported. The post-migration check essentially involves comparing the two sides.

  1. The log file lists all the policies and settings imported and ignored. First, review the log file and identify which settings and policies were not imported.

  2. Compare the XenApp 6.x policies with the policies imported to XenApp 7.6. The values of the settings should remain the same (except for deprecated policy settings, as noted in the next step).

    • If you have a small number of policies, you can perform a side-by-side visual comparison of the policies displayed in the XenApp 6.x AppCenter and the policies displayed in the XenApp 7.6 Studio.
    • If you have a large number of policies, a visual comparison might not be feasible. In such cases, use the policy export cmdlet (Export-Policy) to export the XenApp 7.6 policies to a different XML file, and then use a text diff tool (such as windiff) to compare that file’s data to the data in the XML file used during the policy export from XenApp 6.x.
  3. Use the information in the Policy settings not imported section to determine what might have changed during the import. If a XenApp 6.x policy contains only deprecated settings, as a whole policy, it is not imported. For example, if a XenApp 6.x policy contains only HMR test settings, that policy is completely ignored because there is no equivalent setting supported in XenApp 7.6.

    Some XenApp 6.x policy settings are no longer supported, but the equivalent functionality is implemented in XenApp 7.6. For example, in XenApp 7.6, you can configure a restart schedule for Server OS machines by editing a Delivery Group; this functionality was previously implemented through policy settings.

  4. Review and confirm how filters will apply to your XenApp 7.6 site versus their use in XenApp 6.x; significant differences between the XenApp 6.x farm and the XenApp 7.6 site could change the effect of filters.

Filters

Carefully examine the filters for each policy. Changes may be required to ensure they still work in XenApp 7.6 as originally intended in XenApp 6.x.

Filter Considerations
Access Control Access Control Should contain the same values as the original XenApp 6.x filters and should work without requiring changes.
Citrix CloudBridge A simple Boolean; should work without requiring changes. (This product is now known as NetScaler SD-WAN.)
Client IP Address Lists client IP address ranges; each range is either allowed or denied. The import script preserves the values, but they may require changes if different clients connect to the XenApp 7.6 VDA machines.
Client Name Similar to the Client IP Address filter, the import script preserves the values, but they may require changes if different clients connect to the XenApp 7.6 VDA machines.
Organizational Unit Values might be preserved, depending on whether or not the OUs can be resolved at the time they are imported. Review this filter closely, particularly if the XenApp 6.x and XenApp 7.6 machines reside in different domains. If you do not configure the filter values correctly, the policy may be applied to an incorrect set of OUs. The OUs are represented by names only, so there is a small chance that an OU name will be resolved to an OU containing different members from the OUs in the XenApp 6.x domain. Even if some of the values of the OU filter are preserved, you should carefully review the values.
User or Group Values might be preserved, depending on whether or not the accounts can be resolved at the time they are imported. Similar to OUs, the accounts are resolved using names only, so if the XenApp 7.6 site has a domain with the same domain and user names, but are actually two different domains and users, the resolved accounts could be different from the XenApp 6.x domain users. If you do not properly review and modify the filter values, incorrect policy applications can occur.
Worker Group Worker groups are not supported in XenApp 7.6. Consider using the Delivery Group, Delivery Group Type, and Tag filters, which are supported in XenApp 7.6 (not in XenApp 6.x). Delivery Group: Allows policies to be applied based on Delivery Groups. Each filter entry specifies a Delivery Group and can be allowed or denied. Delivery Group Type: Allows policies to be applied based on the Delivery Group types. Each filter specifies a Delivery Group type that can be allowed or denied. Tag: Specifies policy application based on tags created for the VDA machines. Each tag can be allowed or denied.

To recap, filters that involve domain user changes require the most attention if the XenApp 6.x farm and the XenApp 7.6 site are in different domains. Because the import script uses only strings of domain and user names to resolve users in the new domain, some of the accounts might be resolved and others might not. While there is only a small chance that different domains and users have the same name, you should carefully review these filters to ensure they contain correct values.

Applications

The application importing scripts do not just import applications; they also create objects such as Delivery Groups. If the application import involves multiple iterations, the original application folder hierarchies can change significantly.

  1. First, read the migration log files that contain details about which applications were imported, which applications were ignored, and the cmdlets that were used to create the applications.
  2. For each application:

    • Visually check to ensure the basic properties were preserved during the import. Use the information in Application property mapping to determine which properties were imported without change, not imported, or initialized using the XenApp 6.x application data.
    • Check the user list. The import script automatically imports the explicit list of users into the application’s limit visibility list in XenApp 7.6. Check to ensure that the list remains the same.
  3. Application servers are not imported. This means that none of the imported applications can be accessed yet. The Delivery Groups that contain these applications must be assigned machine catalogs that contain the machines that have the published applications’ executable images. For each application:

    • Ensure that the executable name and the working directory point to an executable that exists in the machines assigned to the Delivery Group (through the machine catalogs).
    • Check a command line parameter (which may be anything, such as file name, environment variable, or executable name). Verify that the parameter is valid for all the machines in the machine catalogs assigned to the Delivery Group.

Log files

The log files are the most important reference resources for an import and export. This is why existing log files are not overwritten by default, and default log file names are unique.

As noted in Logging and error handling, if you chose to use additional logging coverage with the PowerShell Start-Transcript and Stop-Transcript cmdlets (which record everything typed and printed to the console), that output, together with the log file, provides a complete reference of import and export activity.

Using the time stamps in the log files, you can diagnose certain problems. For example, if an export or import ran for a very long time, you could determine if a faulty database connection or resolving user accounts took most of the time.

The commands recorded in the log files also tell you how some objects are read or created. For example, to create a Delivery Group, several commands are executed to not only create the Delivery Group object itself, but also other objects such as access policy rules that allow application objects to be assigned to the Delivery Group.

The log file can also be used to diagnose a failed export or import. Typically, the last lines of the log file indicate what caused the failure; the failure error message is also saved in the log file. Together with the XML file, the log file can be used to determine which object was involved in the failure.

After reviewing and testing the migration, you can:

  1. Upgrade your XenApp 6.5 worker servers to current Virtual Delivery Agents (VDAs) by running the 7.6 installer on the server, which removes the XenApp 6.5 software and then automatically installs a current VDA. See Upgrade a XenApp 6.5 worker to a new VDA for Windows Server OS for instructions.

    For XenApp 6.0 worker servers, you must manually uninstall the XenApp 6.0 software from the server. You can then use the 7.6 installer to install the current VDA. You cannot use the 7.6 installer to automatically remove the XenApp 6.0 software.

  2. From Studio in the new XenApp site, create machine catalogs (or edit existing catalogs) for the upgraded workers.

  3. Add the upgraded machines from the machine catalog to the Delivery Groups that contain the applications installed on those VDAs for Windows Server OS.

Advanced use

By default, the Export-Policy cmdlet exports all policy data to an XML file. Similarly, Export-XAFarm exports all farm data to an XML file. You can use command line parameters to more finely control what is exported and imported.

Export applications partially

If you have a large number of applications and want to control how many are exported to the XML file, use the following parameters:

  • AppLimit: Specifies the number of applications to export.
  • SkipApps: Specifies the number of applications to skip before exporting subsequent applications.

You can use both of these parameters to export large quantities of applications in manageable chunks. For example, the first time you run Export-XAFarm, you want to export only the first 200 applications, so you specify that value in the AppLimit parameter.

Export-XAFarm -XmlOutputFile "Apps1-200.xml"

The next time you run Export-XAFarm, you want to export the next 100 applications, so you use the SkipApps parameter to disregard the applications you’ve already exported (the first 200), and the AppLimit parameter to export the next 100 applications.

Export-XAFarm -XmlOutputFile "Apps201-300.xml" -AppLimit "100" -SkipApps "200"

Do not export certain objects

Some objects can be ignored and thus do not need to be exported, particularly those objects that are not imported; see Policy settings not imported and Application property mapping. Use the following parameters to prevent exporting unneeded objects:

  • IgnoreAdmins: Do not export administrator objects
  • IgnoreServers: Do not export server objects
  • IgnoreZones: Do not export zone objects
  • IgnoreOthers: Do not export configuration logging, load evaluator, load balancing policy, printer driver, and worker group objects
  • IgnoreApps: Do not export applications; this allows you to export other data to an XML output file and then run the export again to export applications to a different XML output file.

You can also use these parameters to work around issues that could cause the export to fail. For example, if you have a bad server in a zone, the zone export might fail; if you include the IgnoreZones parameter, the export continues with other objects.

Delivery Group names

If you do not want to put all of your applications into one Delivery Group (for example, because they are accessed by different sets of users and published to different sets of servers), you can run Import-XAFarm multiple times, specifying different applications and a different Delivery Group each time. Although you can use PowerShell cmdlets to move applications from one Delivery Group to another after the migration, importing selectively to unique Delivery Groups can reduce or eliminate the effort of moving the applications later.

  • Use the DeliveryGroupName parameter with the Import-XAFarm cmdlet. The script creates the specified Delivery Group if it doesn’t exist.
  • Use the following parameters with regular expressions to filter the applications to be imported into the Delivery Group, based on folder, worker group, user account, and/or server names. Enclosing the regular expression in single or double quotation marks is recommended. For information about regular expressions, see https://docs.microsoft.com/en-us/dotnet/standard/base-types/regular-expressions?redirectedfrom=MSDN.

    • MatchWorkerGroup and NotMatchWorkerGroup: For example, for applications published to worker groups, the following cmdlet imports applications in the worker group named “Productivity Apps” to a XenApp 7.6 Delivery Group of the same name.

      Import-XAFarm –XmlInputFile XAFarm.xml –LogFile XAFarmImport.log –MatchWorkerGroup ‘Productivity Apps’ –DeliveryGroupName ‘Productivity Apps’

    • MatchFolder and NotMatchFolder: For example, for applications organized in application folders, the following cmdlet imports applications in the folder named “Productivity Apps” to a XenApp 7.6 Delivery Group of the same name.

      Import-XAFarm –XmlInputFile XAFarm.xml –LogFile XAFarmImport.log –MatchFolder ‘Productivity Apps’ –DeliveryGroupName ‘Productivity Apps’

      For example, the following cmdlet imports applications in any folder whose name contains “MS Office Apps” to the default Delivery Group.

      Import-XAFarm -XmlInputFile .\TheFarmApps.XML -MatchFolder ".*/MS Office Apps/.*"

    • MatchAccount and NotMatchAccount: For example, for applications published to Active Directory users or user groups, the following cmdlet imports applications published to the user group named “Finance Group” to a XenApp 7.6 Delivery Group named “Finance”.

      Import-XAFarm –XmlInputFile XAFarm.xml –LogFile XAFarmImport.log –MatchAccount ‘DOMAIN\\Finance Group’ –DeliveryGroupName ‘Finance’

    • MatchServer and NotMatchServer: For example, for applications organized on servers, the following cmdlet imports applications associated with the server not named “Current” to a XenApp Delivery Group named “Legacy”.

      Import-XAFarm -XmlInputFile XAFarm.xml -LogFile XAFarmImport.log -NotMatchServer 'Current' -DeliveryGroupName 'Legacy'

Customization

PowerShell programmers can create their own tools. For example, you can use the export script as an inventory tool to keep track of changes in a XenApp 6.x farm. You can also modify the XSD files or (create your own XSD files) to store additional data or data in different formats in the XML files. You can specify a nondefault XSD file with each of the import cmdlets.

Although you can modify script files to meet specific or advanced migration requirements, support is limited to the scripts in their unmodified state. Citrix Technical Support will recommend reverting to the unmodified scripts to determine expected behavior and provide support, if necessary.

Troubleshooting

  • If you are using PowerShell version 2.0 and you added the Citrix Group Policy PowerShell Provider snap-in or the Citrix Common Commands snap-in using the Add-PSSnapIn cmdlet, you might see the error message “Object reference not set to an instance of an object” when you run the export or import cmdlets. This error does not affect script execution and can be safely ignored.
  • Avoid adding or removing the Citrix Group Policy PowerShell Provider snap-in in the same console session where the export and import script modules are used, because those script modules automatically add the snap-in. If you add or remove the snap-in separately, you might see one of the following errors:
    • “A drive with the name ‘LocalGpo’ already exists.” This error appears when the snap-in is added twice; the snap-in attempts to mount the drive LocalGpo when it’s loaded, and then reports the error.
    • “A parameter cannot be found that matches parameter name ‘Controller’.” This error appears when the snap-in has not been added but the script attempts to mount the drive. The script is not aware that the snap-in was removed. Close the console and launch a new session. In the new session, import the script modules; do not add or remove the snap-in separately.
  • When importing the modules, if you right-click a .psd1 file and select Open or Open with PowerShell, the PowerShell console window will rapidly open and close until you stop the process. To avoid this error, enter the complete PowerShell script module name directly in the PowerShell console window (for example, Import-Module .\\ExportPolicy.psd1).
  • If you receive a permission error when running an export or import, ensure you are a XenApp administrator with permission to read objects (for export) or read and create objects (for import). You must also have sufficient Windows permission to run PowerShell scripts.
  • If an export fails, check that the XenApp 6.x farm is in a healthy state by running the DSMAINT and DSCHECK utilities on the XenApp 6.x controller server.
  • If you run a preview import and then later run the import cmdlets again for an actual migration, but discover that nothing was imported, verify that you removed the Preview parameter from the import cmdlets.

Policy settings not imported

The following computer and user policy settings are not imported because they are no longer supported. Please note, unfiltered policies are never imported. The features and components that support these settings have either been replaced by new technologies/components or the settings do not apply because of architectural and platform changes.

Computer policy settings not imported

  • Connection access control
  • CPU management server level
  • DNS address resolution
  • Farm name
  • Full icon caching
  • Health monitoring, Health monitoring tests
  • License server host name, License server port
  • Limit user sessions, Limits on administrator sessions
  • Load evaluator name
  • Logging of logon limit events
  • Maximum percent of servers with logon control
  • Memory optimization, Memory optimization application exclusion list, Memory optimization interval, Memory optimization schedule: day of month, Memory optimization schedule: day of week, Memory optimization schedule: time
  • Offline app client trust, Offline app event logging, Offline app license period, Offline app users
  • Prompt for password
  • Reboot custom warning, Reboot custom warning text, Reboot logon disable time, Reboot schedule frequency, Reboot schedule randomization interval, Reboot schedule start date, Reboot schedule time, Reboot warning interval, Reboot warning start time, Reboot warning to users, Scheduled reboots
  • Shadowing *
  • Trust XML requests (configured in StoreFront)
  • Virtual IP adapter address filtering, Virtual IP compatibility programs list, Virtual IP enhanced compatibility, Virtual IP filter adapter addresses programs list
  • Workload name
  • XenApp product edition, XenApp product model
  • XML service port

* Replaced with Windows Remote Assistance

User policy settings not imported

  • Auto connect client COM ports, Auto connect client LPT ports
  • Client COM port redirection, Client LPT port redirection
  • Client printer names
  • Concurrent logon limit
  • Input from shadow connections *
  • Linger disconnect timer interval, Linger terminate timer interval
  • Log shadow attempts *
  • Notify user of pending shadow connections *
  • Pre-launch disconnect timer interval, Pre-launch terminate timer interval
  • Session importance
  • Single Sign-On, Single Sign-On central store
  • Users who can shadow other users, Users who cannot shadow other users *

* Replaced with Windows Remote Assistance

Application types not imported

The following application types are not imported.

  • Server desktops
  • Content
  • Streamed applications (App-V is the new method used for streaming applications)

Application property mapping

The farm data import script imports only applications. The following application properties are imported without change.

IMA Property FMA Property
AddToClientDesktop ShortcutAddedToDesktop
AddToClientStartMenu ShortcutAddedToStartMenu
ClientFolder ClientFolder
CommandLineExecutable CommandLineExecutable
CpuPriorityLevel CpuPriorityLevel
Description Description
DisplayName PublishedName
Enabled Enabled
StartMenuFolder StartMenuFolder
WaitOnPrinterCreation WaitForPrinterCreation
WorkingDirectory WorkingDirectory
FolderPath AdminFolderName

IMA and FMA have different restrictions on folder name length. In IMA, the folder name limit is 256 characters; the FMA limit is 64 characters. When importing, applications with a folder path containing a folder name of more than 64 characters are skipped. The limit applies only to the folder name in the folder path; the entire folder path can be longer than the limits noted. To avoid applications from being skipped during the import, Citrix recommends checking the application folder name length and shortening it, if needed, before exporting.

The following application properties are initialized or uninitialized by default, or set to values provided in the XenApp 6.x data:

FMA Property Value
Name Initialized to the full path name, which contains the IMA properties FolderPath and DisplayName, but stripped of the leading string “Applications\”
ApplicationType HostedOnDesktop
CommandLineArguments Initialized using the XenApp 6.x command line arguments
IconFromClient Uninitialized; defaults to false
IconUid Initialized to an icon object created using XenApp 6.x icon data
SecureCmdLineArgumentsEnabled Uninitialized; defaults to true
UserFilterEnabled Uninitialized; defaults to false
UUID Read-only, assigned by the Controller
Visible Uninitialized; defaults to true

The following application properties are partially migrated:

IMA Property Comments
FileTypes Only the file types that exist on the new XenApp site are migrated. File types that do not exist on the new site are ignored. File types are imported only after the file types on the new site are updated.
IconData New icon objects are created if the icon data has been provided for the exported applications.
Accounts The user accounts of an application are split between the user list for the Delivery Group and the application. Explicit users are used to initialize the user list for the application. In addition, the “Domain Users” account for the domain of the user accounts is added to the user list for the Delivery Group.

The following XenApp 6.x properties are not imported:

IMA Property Comments
ApplicationType Ignored.
HideWhenDisabled Ignored.
AccessSessionConditions Replaced by Delivery Group access policies.
AccessSessionConditionsEnabled Replaced by Delivery Group access policies.
ConnectionsThroughAccessGatewayAllowed Replaced by Delivery Group access policies.
OtherConnectionsAllowed Replaced by Delivery Group access policies.
AlternateProfiles FMA does not support streamed applications.
OfflineAccessAllowed FMA does not support streamed applications.
ProfileLocation FMA does not support streamed applications.
ProfileProgramArguments FMA does not support streamed applications.
ProfileProgramName FMA does not support streamed applications.
RunAsLeastPrivilegedUser FMA does not support streamed applications.
AnonymousConnectionsAllowed FMA uses a different technology to support unauthenticated (anonymous) connections.
ApplicationId, SequenceNumber IMA-unique data.
AudioType FMA does not support advanced client connection options.
EncryptionLevel SecureICA is enabled/disabled in Delivery Groups.
EncryptionRequired SecureICA is enabled/disabled in Delivery Groups.
SslConnectionEnabled FMA uses a different TLS implementation.
ContentAddress FMA does not support published content.
ColorDepth FMA does not support advanced window appearances.
MaximizedOnStartup FMA does not support advanced window appearances.
TitleBarHidden FMA does not support advanced window appearances.
WindowsType FMA does not support advanced window appearances.
InstanceLimit FMA does not support application limits.
MultipleInstancesPerUserAllowed FMA does not support application limits.
LoadBalancingApplicationCheckEnabled FMA uses a different technology to support load balancing.
PreLaunch FMA uses a different technology to support session prelaunch.
CachingOption FMA uses a different technology to support session prelaunch.
ServerNames FMA uses a different technology.
WorkerGroupNames FMA does not support worker groups.