PoC Guide: Automated Configuration Tool


The Automated Configuration tool facilitates migrating and exporting configurations to the Citrix Virtual Apps and Desktop Service (CVADS). This Proof of Concept guide illustrates the step by step instructions on how to use this tool.

Administrators can easily test and explore the Citrix Virtual Apps and Desktop Service (CVADS) features and advantages, while simultaneously running existing On-Premises environments and even facilitate moves between cloud regions, back up existing configurations, and other use cases. The Automated Configuration download link also contains additional information and detailed documentation on said use cases and customizations.

What is the Automated Configuration tool for Citrix Virtual Apps and Desktops?

This tool is designed to help automate the migration of CVAD configuration (policies, applications, catalogs, admin roles, scopes and others) from one or more On-Premises site(s) to the Citrix Virtual Apps and Desktop service (CVADS) hosted on Citrix Cloud. It can also be used to migrate information between different Cloud regions or tenants.

The migration can be performed in stages by running the tool multiple times, allowing administrators to easily achieve the desired configuration state. There is a 2-minute video that provides a quick tour of the Automated Configuration tool:


Why use this tool?

IT Administrators in charge of large or complex environments often find migrations to be a tedious process. They frequently end up writing their own tools to accomplish this task successfully since it tends to be specific to their use cases.

Citrix wants to help ease this process by providing a tool that addresses use cases through automation. Administrators can easily test current configurations in Citrix Cloud and take advantage of the benefits offered by CVADS while keeping their current environments intact. Such benefits include reduced administrative overload when Citrix manages part of the back-end and control plane, automatic and customizable Citrix Cloud component updates, and others.

How is this tool implemented?

Citrix uses industry standard configuration as code to provide a mechanism to help automate migration processes. This tool discovers and exports one or more on-premises sites as a collection of configuration files, which administrators can optionally edit. These files’ configuration can then be imported into CVADS.

This code is not limited to migrations, it is the future for creating configuration for Citrix sites, and as such, applicable for many different use cases. Disaster recovery, Development/Testing/Staging to Production site synchronization, Geographic (GEO) moves, and several other scenarios are supported. For administrators using public cloud providers, this can help create a combination of objects automatically (parallel to Microsoft Azure ARM templates and AWS CloudFormation).

The tool also allows administrators to merge multiple on-premises sites into a single site, while avoiding name collisions. Administrators can control whether the On-Premises or Cloud controls resources. Files can now be placed in a secure network file share that requires authentication when using the SecurityFileFolder parameter which points to the CvadAcSecurity.yml file.


On-Premises environment

  • Citrix Virtual Apps and Desktops (CVAD) On-Premises environment with at least one registered VDA.
  • CVAD On-Premises environment running on one of the following versions: Any Long Term Service Release (LTSR) versions with their latest CU (7.6, 7.15, 1912); Or one of the corresponding latest two Current Releases (CR) versions (for example: 2003, 2006).
  • The domain-joined machine where you plan on running the Automated Configuration tool commands must be running .NET 4.7.2 version or higher.
  • A machine with the Citrix PowerShell SDK, which is automatically installed on the DDC. Note: If running the tool on a different machine, it must be domain-joined and Studio must have the correct PowerShell snap-ins installed. This installer can be found on your corresponding version’s Product ISO installation media, which can be obtained from the Citrix Downloads > Citrix Virtual Apps and Desktops website.
  • Download the Automated Configuration tool MSI from the Official Downloads website
  • Valid CVADS or Workspace Premium Plus licenses.
  • Administrator must be able to log into the Cloud Portal and obtain: The resource location name, customer ID, client Secret (app ID and Secret Key)
  • The existing Citrix Cloud Resource Location has at least one Cloud Connector, which is marked as green (Healthy) and is part of the same domain as the On-Premises setup. Note: Citrix recommends having two or more Cloud Connectors (for redundancy and High Availability). For information on how to set up your Cloud Connectors, refer to this guide.

This proof of concept guide demonstrates how to

  1. Complete the On-Premises pre-requisites
  2. Export your On-Premises site configuration into YAML (.yml) files
  3. Complete the cloud pre-requisites
  4. Complete the requisites for importing site configuration when using different provisioning methods (Machine Creation Services (MCS) for both Pooled and Static Catalogs)
  5. Import your Site Configuration into Cloud (by editing the required files)
  6. Troubleshooting tips and where to find more information

Complete Pre-requisites for Exporting from on-premises site

These steps must be run in your DDC or the domain-joined machine where you want to run the Automated Configuration tool.

  1. Download the latest Automated Configuration tool MSI to your On-Premises DDC or a domain-joined machine. Note: See the Pre-requisites section for more details on how to run it from a different machine. The tool can be downloaded from here. Note: See the Pre-requisites section for more details on how to run it from a different machine.
  2. Run the MSI on your On-Premises DDC, by right-clicking on the AutoConfig_PowerShell_x64.msi installer and clicking on Install. Pre-requisites
  3. Read the License Agreement and check the box if you accept the terms. Then click Install: Pre-requisites
  4. Files are copied and the progress bar continues moving until it finishes the install. Pre-requisites

  5. After the MSI runs, a window indicating successful completion pops up. Click Finish to close the MSI setup window. Pre-requisites
  • 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 your On-Premises site configuration

Using an export<!--NeedCopy--> PowerShell command, you can export your existing On-Premises configuration and obtain the necessary .yml files. These files are used to import your desired configuration into Citrix Cloud.

  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<!--NeedCopy--> 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. Exporting Config

  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)<!--NeedCopy--> , which can be found under %HOMEPATH%\Documents\Citrix\AutoConfig<!--NeedCopy--> . Refer to the Troubleshooting Tips section if you encounter any errors. Exporting Config

  4. The resulting .yml files are now in the current user’s Documents\Citrix\AutoConfig<!--NeedCopy--> path: Exporting Config
  • Note: See the following image for an example of the contents on a .yml file (Application.yml<!--NeedCopy--> )

Exporting Config

  • Note: If necessary, copy the .yml files to the machine you want to use to import settings to your Citrix Cloud environment. Exporting and importing can be done from the same machine.

Complete Prerequisites in Cloud

Go to your Resource Location and make sure your Cloud Connectors are both showing green (Available). Note: If you need instructions on how to set up your Cloud Connectors, refer to this guide.

  1. To verify the health status of your Cloud Connectors, first log in to your cloud portal with your Citrix administrator credentials (or your Azure AD credentials, when applicable). Cloud Prerequisites

  2. If you have more than one Organization ID (Org ID), select your corresponding tenant. Cloud Prerequisites

  3. Upon logon, go to the hamburger menu on the top left corner and then click Resource Locations: Cloud Prerequisites

  4. Access the Cloud Connector(s) tile under your Resource Location. Cloud Prerequisites

  • Note: The Cloud Connector(s) must show green, indicating a Healthy status, as seen on the following image. Citrix recommends having more than one Cloud Connector per Resource Location, for redundancy purposes.

Cloud Prerequisites

Requisites for Importing Site Configuration using different Provisioning Methods

Dealing with Provisioning Services (PVS) Machine Catalogs, Delivery and Application Groups and Policies

No extra steps are required to import your PVS Catalogs and their corresponding applications at this time. Follow the steps mentioned on the Import your Site Configuration into Cloud section in this guide.

Dealing with Machine Creation Services (MCS): Pooled VDI multi-session (Random) and RDS Machine Catalogs (PREVIEW)

Note: A separate section is available with instructions for Static assigned virtual machines. Refer to the steps mentioned on the MCS Static Assigned VDIs section in this guide.

The import and export commands are supported for this task now. Both the golden image and the configuration in Catalogs with User data: Discard can be migrated. However the virtual machines in these catalogs do not get migrated, since the site you are importing from is responsible for maintaining the life cycle of the virtual machine.

When machines are turned on, their state might change, affecting import data for the virtual machines synchronization. Therefore when migrating these catalogs using the tool, it creates a catalog metadata and initiates master image creation. However zero machines are imported.

Important Considerations:

  • Since this process is still in preview, it is not automatically enabled. You must contact Citrix support or your Customer Success Management team to enable this feature for your org ID.
  • The MCS catalog import process can take a couple of hours based on the size of the master image. Therefore the import command within the tool only starts the MCS catalog creation and does not wait for it to finish.
  • After the import has completed, the catalog creation progress can be monitored via Studio in the cloud deployment.
  • Once the master image is created you can provision machines. Consider your hypervisor’s existing capacity, since you have consumption from your on-premises usage.
  • All other objects (including the Delivery Group, applications, policies, and everything that uses the catalog) can be imported, without having to wait for the master image creation. The same commands available within the tool can be used to migrate catalogs and all other objects.
  • When the catalog has finished creating, machines can be added to the imported catalog, and then users can launch their resources.

Note: After these considerations, follow Import your Site Configuration into Cloud section in this guide to merge your configuration as needed.

Dealing with Machine Creation Services (MCS): Static Assigned Machines (PREVIEW)

Note: A separate section is available with instructions for Pooled and RDS Machines. Refer to the steps mentioned on the MCS Pooled VDI and RDS Machines

The import and export commands are supported for this task now. This process imports some low-level details which are stored in the database so it needs to be run from a machine with database access. The tool import process migrates the configuration, master image and the machines as well. It is a quick operation since no images are created.

Important Considerations:

  • Since this process is still in preview, you must reach out to Citrix in order to enable this feature for your org ID, since this is not automatically enabled.
  • The VDAs need to be pointed to the Cloud Connectors for them to register with Citrix Cloud.
  • Refer to the Activating sites documentation to activate your Cloud site and thus control reboot schedule, power management, and others, via Citrix Cloud.
  • Once the migration is completed, if you want to delete the corresponding catalog from your on-premises site, you must select the option to leave VM and AD account. Otherwise both records will be deleted and the Cloud site left pointing to the deleted virtual machine.

Note: After these considerations, follow Import your Site Configuration into Cloud section in this guide to merge your configuration as needed.

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. Note: For MCS, first follow the corresponding subsections under the Import your Site Configuration into Cloud section in this guide.

Obtaining Customer Connection Details

Administrators must edit the CustomerInfo.yml<!--NeedCopy--> file and add the corresponding CustomerName, CustomerID, and SecretKey values to it. These values can be obtained and generated from the Cloud portal, as shown in the following steps.

  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): Importing Configuration

  2. On your Cloud portal click the hamburger menu again and go to Identity and Access Management: Importing Configuration

  3. 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): Importing Configuration

  4. Paste the retrieved value between the quotes that follow the CustomerId field in your CustomerInfo.yml<!--NeedCopy--> file, between the “”<!--NeedCopy--> (quotes): Importing Configuration

  5. Back on your Cloud portal, go to the Identity and Access Management portal and API Access tab. Enter the name you want to identify this API key with on the Name your Secure Client box. Then click the Create Client button. Note: This action generates the Client ID<!--NeedCopy--> and the Secret Key<!--NeedCopy--> . Importing Configuration

  6. Copy the ID<!--NeedCopy--> and the Secret<!--NeedCopy--> values, one by one (paste them on the CustomerInfo.yml<!--NeedCopy--> file as shown in the following step). Then click Download to save the file for later reference. Importing Configuration

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

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. 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). Zone Mapping

  2. You can find this name under your On-Premises Citrix Studio console > Configuration > Zones. Note: if your Zone is named Primary<!--NeedCopy--> in your On-Premises environment, this value on the ZoneMapping.yml<!--NeedCopy--> file doesn’t need to be changed: Zone Mapping

  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: Zone Mapping

  4. Copy your Resource Location name (Shown as My Resource Location<!--NeedCopy--> on the following screenshot): Zone Mapping

  5. Paste this value on the ZoneMapping.yml<!--NeedCopy--> file instead of the Name_Of_Your_Resouce_Zone<!--NeedCopy--> value: Zone Mapping

  • Note: Multiple Zones in your On-Premises environment can also map to one Resource Location in the cloud. However there always must be one row in the file for each zone in the On-Premises environment. For multiple zones on-premises and one Resource Location, the format on this file would look as follows:

Zone Mapping

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

Zone Mapping

Merging configuration

  1. Back on the Migration tool PowerShell console, run the following command: Merge-CvadAcToSite<!--NeedCopy--> to merge the existing Cloud configuration (if any exists) with the configuration exported from the On-Premises site. Merging Configuration

  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: Merging Configuration

  3. The resulting files show in the following directory: <This PC>\Documents\Citrix\AutoConfig\Import_<YYYY_MM_DD_HH_mm_ss><!--NeedCopy--> Merging Configuration

  4. On this same folder, you can find a Backup_YYYY_MM_DD_HH_mm_ss<!--NeedCopy--> folder. Note: Copy this folder somewhere safe as it is a backup of the configuration.

  5. The Backup<!--NeedCopy--> folder contains the following files, which are helpful for reverting changes, if needed: Merging Configuration

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). Verifying Configuration

  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.

  • Machine Catalogs list example:

Verifying Configuration

If everything looks as expected, your CVADS migration is complete.

Troubleshooting Tips

General information for troubleshooting:

  • Running any cmdlet creates a log file and an entry in the master history log file. The entries contain the date, operation, result, backup, and log file locations of the execution. This log provides potential solutions and fixes to common errors.
  • The master history log is located in %HOMEPATH%\Documents\Citrix\AutoConfig<!--NeedCopy--> , in the file named History.Log<!--NeedCopy--> .* All operation log files are placed in a backup folder.
  • All log file names begin with CitrixLog<!--NeedCopy--> , then show the auto-config<!--NeedCopy--> operation and the date and timestamp of the cmdlet execution.
  • Logs do not auto-delete.
  • Console logging can be suppressed by using the -quiet<!--NeedCopy--> parameter
  • New support cmdlet to zip all log files for transfer to Citrix for support. Back up the cloud’s current state by running the Backup-CvadAcToFile<!--NeedCopy--> command. Then collect all log and *.yml<!--NeedCopy--> files into a single zip by running New-CvadAcZipInfoForSupport<!--NeedCopy--> . No customer security information is included. Forward the zip file at the following location %HOMEPATH%\Documents\Citrix\AutoConfig\CvadAcSupport_yyyy_mm_dd_hh_mm_ss.zipNew-CvadAcZipInfoForSupport<!--NeedCopy--> .

For more information:

  1. Refer to the Automated Configuration Tool Troubleshooting FAQ article.

  2. You can also reach out via the Support Forum

  3. Read the Automated Configuration Tool documentation

  4. Download new versions from the direct Downloads website link

  5. Check out our On-demand August 19 webinar recording - “Why Citrix Cloud migration is easier than ever”. We shared more information on the tool and hosted a Live Q&A session with a panel of Citrix experts.

  6. If after consulting the information listed previously you still need assistance, get in touch with your Citrix representatives, Customer Success Manager, or Support.