Proof of Concept: Automated Configuration Tool


Author: Thamara Trejos

Special Thanks: Amir Trujillo, Nitin Mehta, Daniel Feller


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, 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.

Why use this tool?

IT Administrators dealing with 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 has leveraged 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, and then import these files’ configuration 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).


On-Premises environment

  • 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 installing the Automated Configuration tool 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.
  • 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 (Provisioning Services - PVS and Machine Creation Services - MCS)
  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 install 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.

  2. Run the MSI on your On-Premises DDC, by right-clicking on the AutoConfig_PowerShell_x64.msi installer and clicking on Install. On-prem Pre-Requisites

  3. Read the License Agreement and check the box if you accept the terms. Then click Install: On-prem Pre-Requisites

  4. After the MSI runs, a window indicating successful completion pops up. Click Finish to close the MSI setup window.

On-prem Pre-Requisites

  • Note: Upon successful execution, the MSI creates the corresponding folder structure, located in C:\Users\<username>\Documents\Citrix\AutoConfig, 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 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: Exporting Config

  2. The Auto Config PowerShell tool launches and the current directory points to the tool’s default path (C:\Users\<username>\Documents\Citrix\AutoConfig). Note: This directory is also where the .yml files are created later. Exporting Config

  3. On the Auto Config Command Prompt, run the Export-CvadAcToFile -all $true command. This command exports policies, manually provisioned catalogs and delivery groups, applications, application folders, icons, zone mappings, tags, and other items. Note: For MCS and PVS 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

  4. Once the tool finishes running, the Overall status shows as True and the export process is completed (the output lines shown will 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. Refer to the Troubleshooting Tips section if you encounter any errors. Exporting Config

  5. The resulting .yml files are now in the current user’s Documents\Citrix\AutoConfig path: Exporting Config

  • Note: See the following image for an example of the contents on a .yml file (Application.yml)

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

Extra steps are required to import your PVS Catalogs and their corresponding applications. Follow these instructions to prepare your environment, before proceeding to import the Application settings.

Note: After performing these actions, follow the steps mentioned on the Import your Site Configuration into Cloud section in this guide.

  1. Run the Auto Config tool as an Administrator
  2. Type the following command Export-CvadAcToFile -all $true and press Return (Enter) on your keyboard. Provisioning Method PVS

  3. Successfully completed items show in green OK. Once the tool finishes running, a screen like the following shows up: Provisioning Method PVS

  4. Access the C:\Users\<username>\Documents\Citrix\AutoConfig folder and open up the CvadAcSecurity.yml file, which you must edit for PVS to work. Note: The UserName and Password fields refer to your PVS Site Server credentials. Be sure to specify your logon as DOMAIN\Username, add the password, and save the file when ready. Provisioning Method PVS

Dealing with Machine Creation Services (MCS) Machine Catalogs, Delivery and Application Groups and Policies

Currently, this tool does not support importing MCS machine catalogs or their corresponding delivery groups in an automated way. However, you can still import other configuration such as Applications and policies automatically using this tool.

You must ensure you create the machine catalog and delivery group using the same names as the ones on On-Premises setup. Follow these steps to prepare your environment, before proceeding to import the Application settings:

  1. In your Cloud portal, click the Hamburger menu > My Services > Virtual Apps and Desktops Service > Manage tab to create your MCS machine Catalog as you normally would. You must select the desired OS Type, Master Image, Storage, Licensing, Network, and Account settings.Important: Be sure to name your catalog exactly the same way your existing On-Premises catalog is named. Note: If needed, refer to this guide for information on how to set up your catalogs.

  2. Still in Cloud Studio, create the corresponding Delivery Group for the new Catalog and ensure you name it exactly after the corresponding On-Premises Delivery Group as well. Note: For more details on how to create your Machine Catalogs and Delivery Groups, refer to [this guide/en-us/tech-zone/learn/poc-guides/cvads.html).

  3. In your On-Premises environment’s Citrix Studio, under the Applications node, confirm that the desired applications belong to the matching Delivery Groups by selecting the desired app and then right-clicking on the app to go to the Properties as follows: Provisioning Method MCS

  4. Click the Groups node to confirm the groups the app in question belongs to: Provisioning Method MCS

  5. Back on the PowerShell console, run the Merge command and use the byDeliveryGroupName flag, which filters the Applications by Delivery Group name. Complete Syntax example: Merge-CvadAcToSite –Applications $true –ByDeliveryGroupName <DG_name> Provisioning Method MCS

  6. Press Return (Enter) on your keyboard to run the command and type yes to continue. Provisioning Method MCS

  7. Upon successful execution and completion, the output looks similar to the following: Provisioning Method MCS

  8. On your Cloud Studio console, go to the Applications node and refresh to make sure the apps are listed as expected. Select the applications and go to Application Properties > Groups to double-check.

  • Application Folders in Cloud Studio Before running the Migration tool

Provisioning Method MCS

  • Application Folders in Cloud Studio After running the Migration tool

Provisioning Method MCS

Once you’ve performed the previous actions, if you need to import policies associated with your MCS Machine Catalogs and your Delivery groups, follow these instructions:

  1. Run the Merge-CvadAcToSite -GroupPolicies $true command in the PowerShell console and type yes to continue, as shown in the following screenshot, and then press Return (Enter) on your keyboard: Policies for MCS

  2. Successful execution shows a similar output (Added values). The following screenshot also shows the result of a line for which there were no changes (No Change): Policies for MCS

  3. Upon execution, refresh the Cloud Studio window and access the Policies node on the left hand side. Policies for MCS

  4. Check the Policies Assigned to tab and compare it against your On-Premises policy assignment, as illustrated on the following example:

  • On-Premises Studio:

Policies for MCS

  • Cloud Studio:

Policies for MCS

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 PVS and 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 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 file using a text editor application, such as Notepad. The following screenshot shows the CustomerInfo.yml 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 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 file, between the “” (quotes): Importing Configuration

  5. Back on your Cloud portal, under 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 and then click the Create Client button. Note: This generates the Client ID and the Secret Key. Importing Configuration

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

  7. Paste the ID and Secret values onto the corresponding fields in the CustomerInfo.yml 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 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), open up the ZoneMapping.yml using Notepad or your preferred text editor. Note: The Primary 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 in your On-Premises environment, this value on the ZoneMapping.yml file doesn’t need to be changed: Zone Mapping

  3. Still on the ZoneMapping.yml file, the Name_Of_Your_Resource_Zone value must be replaced with your Cloud Resource Location name, which 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 on the following screenshot): Zone Mapping

  5. Paste this value on the ZoneMapping.yml file in lieu of the Name_Of_Your_Resouce_Zone value: Zone Mapping

  • Note: Multiple Zones in your On-Premises environment can also map to one Resource Location in the cloud. However there always needs to 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 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> Merging Configuration

  4. On 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: 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, in the file named History.Log.* All operation log files are placed in a backup folder.
  • All log file names begin with CitrixLog, then show the auto-config operation and the date and timestamp of the cmdlet execution.
  • Logs do not auto-delete.

For more information:

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

  2. You can also reach out via the Support Forum.

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

Proof of Concept: Automated Configuration Tool