by Uddave Jajoo, Indianapolis CUGC Leader

This is in continuation to the previous blog post Guidelines for Migration from CVAD on Prem to Citrix DaaS – Control Layer: Part ). In this blog, I focus on the process of Exporting Site Database configuration from On-Prem XenDesktop Sites and Importing it to the Citrix Cloud Site.

Part 2: Control Layer

1. Install the Citrix ACT Tool.
2. Export the on-premises site configuration.
3. Merge your site data config to Citrix Cloud using ACT Tool.

To begin with this process, download the tool and install the MSI by using the prompts as shown below. An icon for “Auto config” would be created.

Install the Citrix ACT Tool
Run the MSI on your On-Premises DDC, by right-clicking on the AutoConfig_PowerShell_x64.msi installer and clicking on Install.
Read the License Agreement and check the box if you accept the terms. Then click Install:
Files are copied and the progress bar continues moving until it finishes the install.
After the MSI runs, a window indicating successful completion pops up. Click Finish to close the MSI setup window. Note: Upon successful execution, the MSI creates the corresponding folder structure, located in C:\Users\<username>\Documents\Citrix\AutoConfig<!–NeedCopy–> , and also a desktop icon called Auto Config, which launches a PowerShell command prompt. This tool is the one used on subsequent steps.

Export the on-premises site configuration

1. After running the MSI installer on the previous step, you get an Auto Config shortcut automatically created on the Desktop. Right-click this shortcut and click Run as Administrator. 2. Run the Export-CvadAcToFile command. This command exports policies, manually provisioned catalogs, and delivery groups. It also exports applications, application folders, icons, zone mappings, tags, admin roles and scopes, and other items. Note: For MCS machine catalogs and delivery groups, refer to the steps on Requisites for Importing Site Configuration using different Provisioning Methods section in this guide.

3. Once the tool finishes running, the overall status shows as True and the export process is completed (the output lines shown match the following illustration).  Note: If there are any errors, diagnostic files are created in the action-specific subfolders (Export, Import, Merge, Restore, Sync, Backup, Compare), which can be found under %HOMEPATH%\Documents\Citrix\AutoConfig<!–NeedCopy–>

4. The resulting .yml files are now in the current user’s Documents\Citrix\AutoConfig path.

Get the required information:

Customer ID: Go to the API Access tab and copy the Customer ID value, which can be found next to the customer ID<!--NeedCopy--> text as seen on the following screenshot (red rectangle):

ClientID & Secret Get the ClientId and Secret from the existing already created Secret Client (Cloud Connector installation)

Import your Site Configuration into Cloud During this step, you obtain the customer connection details, manually create your Zone mappings, and import the configuration to your Cloud tenant.

CustomerInfo.yml

1. First, open your CustomerInfo.yml<!--NeedCopy--> file using a text editor application, such as Notepad. The following screenshot shows the CustomerInfo.yml<!--NeedCopy--> file values that must be edited (underlined in red): < # Created/Updated on 2020/01/29 16:46:47             CustomerId: ‘markhof123’             ClientId: ‘6713FEA6-46CC-4F8A-BC71-539F2DDK5384’             Secret: ‘TwBLaaabbbaaaaaaaaaaw==’             Environment: Production             AltRootUrl: ‘’             StopOnError: False             AlternateFolder: ‘’             Locale: ‘en-us’             Editor: ‘C:\Program Files\Notepad++\notepad++.exe’             Confirm: True             DisplayLog: True>

2. Paste the ID<!--NeedCopy--> and Secret<!--NeedCopy--> values onto the corresponding fields in the CustomerInfo.yml<!--NeedCopy--> file:

ZoneMapping.yml

Manually create the Zone Mapping file (ZoneMapping.yml) On-Premises Zones cannot be automatically migrated to a cloud Resource Location, so they must be mapped using the ZoneMapping.yml<!–NeedCopy–> file. Note: Migration failures occur if the zone is not mapped with a homonymous resource location (a Resource Location with the exact same name).

1. Primary: You can find this name under your On-Premises Citrix Studio console > Configuration > Zones. (Example primary for XenDesktopNA: XenDesktopZone)

2. Back in the same directory where your .yml files reside (Documents\Citrix\AutoConfig)<!--NeedCopy-->, open up the ZoneMapping.yml<!--NeedCopy--> using Notepad or your preferred text editor.  Note: The Primary<!--NeedCopy--> value must be replaced with the name of your corresponding Zone you want to migrate objects from (in your on-premises environment).

3. Still on the ZoneMapping.yml<!--NeedCopy--> file, the Name_Of_Your_Resource_Zone<!--NeedCopy--> value must be replaced with your Cloud Resource Location name. This value can be found on your cloud portal under the Hamburger menu > Resource Locations:

4. Copy your Resource Location name (Example: XenDesktopResourceLocation1): 5. Paste this value on the ZoneMapping.yml file instead of the Name_Of_Your_Resouce_Zone value:

6. When mapping Zones to different Resource locations, the file must look like this instead:

CvadSecurity.yml

7. Back in the same directory where your .yml files reside (Documents\Citrix\AutoConfig), open up the CvadAcSecurity.yml using Notepad or your preferred text editor. 8. In the CvadAcSecurity.yml file, enter the username and password for your hypervisor connection, then Save the file.

HostConnections.yml

In terms of different sites and different hosting connection with same name, please make sure to properly update the respective hosting connections in the HostConnectios.yml file before running the Merge operation. Modify the hosting connection name in the .yml file as below:   Find on-prem connection name and replace it with the new name you would want to be created in the Citrix Cloud for that respective connection. Example: HostConnectionNameOnPrem present in two different sites and then replace it with the required new name in each of the Site HostConnections.yml file For XenDesktopSite1 – HostConnectionNameOnPrem1 and For XenDesktopSite2 – HostConnectionNameOnPrem2

Merge your Site Data config to Citrix Cloud using ACT Tool 1. Back on the Migration tool PowerShell console, run the following command: Merge-CvadAcToSite to merge the existing Cloud configuration (if any exists) with the configuration exported from the On-Premises site. 2. When each task runs successfully, the output looks green as .yml files are imported and the corresponding components are added to the cloud site: 3. The resulting files show in the following directory: <This PC>\Documents\Citrix\AutoConfig\ Import_<YYYY_MM_DD_HH_mm_ss> 4. In this same folder, you can find a Backup_YYYY_MM_DD_HH_mm_ss folder.  Note: Copy this folder somewhere safe as it is a backup of the configuration. 5.  The Backup folder contains the following files, which are helpful for reverting changes, if needed: Verify configuration created in Cloud Studio 1. Access your Virtual Apps and Desktops service Manage tab via the Cloud Console > My Services > Virtual Apps and Desktops service > Manage tab). 2. Refresh to make sure the Machine catalogs, Delivery groups, policies, tags, and applications are now showing as expected.  Note: Depending on what you import, the results vary as they are specific to your own unique configuration. Review each section to make sure the expected items are listed.

With this blog post, Citrix Admins and customers will be able to successfully migrate their Site Database to Citrix Cloud. In case of any issues encountered, please feel free to nudge the Citrix Support and to also reach out to me @udjajoo or email me @er.uddavejajoo@gmail.com.

I will be writing one final blog with respect to this series for Control Layer Migration to Citrix cloud soon which will be focused on Cutover of resources from On-Prem DDCs to Citrix Cloud Connectors.

Reference Articles:

PoC Guide: Automated Configuration Tool | Citrix Tech Zone
Migrate configuration to Citrix Cloud
MIgrate From on Premises to cloud

NEXT: Guidelines for Migration of CVAD On-Prem to Citrix DaaS–Control Layer: Part 3

Are you a member of CUGC? Join FREE today!