Migrate XenApp 6.x

NOTE: You cannot use the Citrix Smart Migrate product with this version of XenApp and XenDesktop. However, the Migration Tool is available.

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.

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 farm data to XML files.
   3. 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.
2. On the XenApp 7.6 Controller:
   1. Import the PowerShell import modules.
   2. Run the import cmdlets to import policy and farm data (applications), using the XML files as input.
3. 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.

New in this release

This December 2014 release (version 20141125) contains the following updates:

• If you encounter issues using the migration tool on a XenApp 6.x farm, report them to https://discussions.citrix.com/forum/1411-xenapp-7x/.
• New packaging - the XAMigration.zip file now contains two separate, independent packages: ReadIMA.zip and ImportFMA.zip. To export from a XenApp 6.x server, you need only ReadIMA.zip. To import to a XenApp 7.6 server, you need only ImportFMA.zip.
• The Export-XAFarm cmdlet supports a new parameter (EmbedIconData) that eliminates the need to copy icon data to separate files.
• The Import-XAFarm cmdlet supports three new parameters:
  • MatchServer - import applications from servers whose names match an expression
  • NotMatchServer - import applications from servers whose names do not match an expression
  • IncludeDisabledApps - import disabled applications
• Prelaunched applications are not imported.
• The Export-Policy cmdlet works on XenDesktop 7.x.

Migration Tool package

The migration tool is available under the XenApp 7.6 Citrix download site. The XAMigration.zip file contains two separate, independent packages:

• ReadIMA.zip - contains the files used to export data from your XenApp 6.x farm, plus shared modules.

• ImportFMA.zip - contains the files used to import data to your XenApp 7.6 farm, plus shared modules.

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 and server names, plus other 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 might be applied to the policy after the import. The allow and 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, the file is placed in the script’s current execution folder. The default log name is XFarmYYYYMMDDHHmmSS-xxxxxx where the last six digits are 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 more 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 need to understand basic PowerShell concepts. Although extensive scripting expertise is not required, you need understand the cmdlets you run. Use the Get-Help cmdlet to review each migration cmdlet’s help before running 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 product documentation for your StoreFront or Web Interface release (Manage > Create a store).
• 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 run.
• In the step-by-step sections, 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 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 contain instructions.
• Do not have any other active user connections during an import. The import scripts create many new objects, and disruptions might 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, without actually importing anything. The logs 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 are 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 run (for example: Set-ExecutionPolicy RemoteSigned).

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

   Import-Module .\ExportPolicy.psd1

   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, run the Export-Policy cmdlet.

   Parameter	Description
   -XmlOutputFile “.xml"	XML output file name. This file holds 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 “"	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"
   <!--NeedCopy-->
   

9. To export farm data, run the Export-XAFarm cmdlet, specifying a log file and an XML file.

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 running the Import-Policy or Import-XAFarm cmdlet with the Preview parameter). You can then 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 Export-XAFarm, 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 (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 run (for example: Set-ExecutionPolicy RemoteSigned).

7. Import the PowerShell module definition files ImportPolicy.psd1 and ImportXAFarm.psd1:

   Import-Module .\ImportPolicy.psd1

   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, run the Import-Policy cmdlet, specifying the XML file containing the exported policy data.

   Parameter	Description
   -XmlInputFile “.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 “"	XSD file name. The import scripts use this file to validate the syntax of the XML input file. See Advanced use for how-to-use information. Default: PolicyData.XSD
   -LogFile “"	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 following 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"
   <!--NeedCopy-->
   

9. To import applications, run the Import-XAFarm cmdlet, specifying a log file and the XML file containing the exported farm data.

   Parameter	Description
   -XmlInputFile “.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 “"	XSD file name. The import scripts use this file to validate the syntax of the XML input file. See Advanced use for how-to-use information. Default: XAFarmData.XSD
   -LogFile “"	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 “"	Delivery Group name for all imported applications. See Advanced use for how-to-use information. Default: “ -Delivery Group”
   -MatchFolder “"	Import only those applications in folders with names that match the string. See Advanced use for how-to-use information. Default: No matching occurs.
   -NotMatchFolder “"	Import only those applications in folders with names that do not match the string. See Advanced use for how-to-use information. Default: No matching occurs.
   -MatchServer “"	Import only those applications from servers whose names match the string. See Advanced use for how-to-use information.
   -NotMatchServer “"	Import only those applications from servers whose names do not match the string. See Advanced use for how-to-use information. Default: No matching occurs.
   -MatchWorkerGroup “"	Import only those applications published to worker groups with names that match the string. See Advanced use for how-to-use information. Default: No matching occurs.
   -NotMatchWorkerGroup “"	Import only those applications published to worker groups with names that do not match the string. See Advanced use for how-to-use information. Default: No matching occurs.
   -MatchAccount “"	Import only those applications published to user accounts with names that match the string. See Advanced use for how-to-use information. Default: No matching occurs.
   -NotMatchAccount “"	Import only those applications published to user accounts with names that do not match the string. See Advanced use for how-to-use information. 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"
   
   <!--NeedCopy-->
   

10. 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, except for 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. Keep the settings values the same (except for deprecated policy settings, as noted in the next step).

   • If you have a few 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 many 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 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 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 might change the effect of filters.

Filters

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

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, only some accounts might be resolved. While there is only a small chance that different domains and users have the same name, 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 that the basic properties were preserved during the import. Use the information in the Application property mapping section 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 might 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 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 long time, you can 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 not only create the Delivery Group object, 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 many 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"
-AppLimit "200"
<!--NeedCopy-->

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"
<!--NeedCopy-->

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 parameter 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 might 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 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.

  • 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
     <!--NeedCopy-->
    

  • 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’
     <!--NeedCopy-->
    

    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/.*"
     <!--NeedCopy-->
    

  • 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’
     <!--NeedCopy-->
    

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

     Import-XAFarm -XmlInputFile XAFarm.xml -LogFile XAFarmImport.log -NotMatchServer 'Current' -DeliveryGroupName 'Legacy'
     <!--NeedCopy-->
    

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 recommends 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. Unfiltered policies are never imported. The features and components that support these settings have either been replaced by new technologies and 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 *
• Prelaunch disconnect timer interval, Prelaunch 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 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:

The following application properties are partially migrated:

The following XenApp 6.x properties are not imported: