The XenApp 6.x Migration Tool (the 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.
A video overview of the migration tool is available here.
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.
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. |
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. |
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.
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.
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.
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.
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.
A video of an export walk-through is available here.
cd C:\XAMigration
Set-ExecutionPolicy RemoteSigned
Import-Module .\ExportPolicy.psd1
Import-Module .\ExportXAFarm.psd1
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 |
Export-Policy -XmlOutputFile ".\MyPolicies.XML" -LogFile ".\MyPolicies.Log"
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 for how-to-use information. Default: False; administrator information is exported |
-IgnoreApps |
Do not export application information. See Advanced use for how-to-use information. 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 Note: The purpose of the -IgnoreOthers 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 Advanced use for how-to-use information. 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 for details |
-SkipApps <integer> |
Number of applications to skip. See Advanced use for how-to-use information. Default: No applications are skipped |
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.
A video of an import walk-through is available here.
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.
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.
cd C:\XAMigration
Set-ExecutionPolicy RemoteSigned
Import-Module .\ImportPolicy.psd1
Import-Module .\ImportXAFarm.psd1
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 for how-to-use information. 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 |
Import-Policy -XmlInputFile ".\MyPolicies.XML" -LogFile ".\MyPolicies.Log"
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 for how-to-use information. 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 for how-to-use information. Default: "<xenapp-farm-name> - Delivery Group" |
-MatchFolder "<string>" |
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 "<string>" |
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 "<string>" |
Import only those applications from servers whose names match the string. See Advanced use for how-to-use information. |
-NotMatchServer "<string>" |
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 "<string>" |
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 "<string>" |
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 "<string>" |
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 "<string>" |
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 |
Import-XAFarm -XmlInputFile ".\MyFarm.XML" -LogFile ".\MyFarm.Log"
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.
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.
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. |
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).
|
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.
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 the “Logging and error handling” section, 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.
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.
Export-XAFarm -XmlOutputFile "Apps1-200.xml" -AppLimit "200"
Export-XAFarm -XmlOutputFile "Apps201-300.xml" -AppLimit "100" -SkipApps "200"
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.
Import-XAFarm –XmlInputFile XAFarm.xml –LogFile XAFarmImport.log –MatchWorkerGroup ‘Productivity Apps’ –DeliveryGroupName ‘Productivity Apps’
Import-XAFarm –XmlInputFile XAFarm.xml –LogFile XAFarmImport.log –MatchFolder ‘Productivity Apps’ –DeliveryGroupName ‘Productivity Apps’
Import-XAFarm -XmlInputFile .\THeFarmApps.XML -MatchFolder ".*/MS Office Apps/.*"
Import-XAFarm –XmlInputFile XAFarm.xml –LogFile XAFarmImport.log –MatchAccount ‘DOMAIN\\Finance Group’ –DeliveryGroupName ‘Finance’
Import-XAFarm -XmlInputFile XAFarm.xml -LogFile XAFarmImport.log -NotMatchServer 'Current' -DeliveryGroupName 'Legacy'
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.
* Replaced with Windows Remote Assistance
* Replaced with Windows Remote Assistance
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 |
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 |
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. |
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 SSL 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. |