Citrix Automated Configuration Tool (ACT) – Lessons Learned (Part 1)

As more and more customers are migrating their workload to Citrix Cloud, I have been involved in a number of projects where we are required to migrate multiple Citrix Virtual Apps and Desktop (CVAD) sites to a single Citrix DaaS instance.

Throughout this series, we will look at different scenarios you may encounter in your projects. Let’s start with the following scenario:

• Two CVAD sites aligned with two data centers, with no Zones defined.
  • CVAD_Site_1 in data centre 1
  • CVAD_Site_2 in data centre 2

For this scenario, the assumption is that a single CVAD site will be represented with a single Resource Location. If there is a need to have a CVAD site spread across multiple Resource Locations, please refer to Part 2 or Part 3 of this series.

This is the easiest scenario in the series, and it can be done in many different ways, however, most of the time the customer will have a naming convention that will be identical between these sites, so there will be conflicts if we just run ACT and import everything.

Here is what I have done on my projects:

• Have Citrix DaaS configured with resource locations defined. In our case, the resource locations are:
  • RL-DC1
  • RL-DC2
• Review the naming convention and come to an agreement on what prefixes/suffixes to use.
• Create a share(s) where you can export your CVAD sites. This is particularly important if there is a number of admins that will use the Citrix ACT tool.
• Review hosting connections and define if the hosting connection will be imported using the Citrix ACT tool, or pre-created in Citrix DaaS. If the latter, make sure that ALL naming connections are identical with the hosting connections on-premises. In this example, we will be importing hosting connections using the ACT tool.
• Dedicate a machine (VM or otherwise) that will be used for running the ACT tool. Important: Do not install Citrix Remote PowerShell SDKs on the machine where you are running the ACT tool.

First, let’s make sure to have shares created, and for the ease of running the tool this is what I would recommend for this scenario:

\\share\CVAD_Site_1
\\share\CVAD_Site_2

Next thing is to “prepare” sites for export. What this means is that we want to configure SiteMerging.yml file so we can use it for import. In this scenario, I am prefixing machine catalogs, group policies, and tags. The creation of this file is completely up to the customer, and you can choose other components to prefix. This could be done after the file creation, just by editing the file.

New-CvadAcSiteMergingInfo -SiteName $((get-brokersite -AdminAddress %FQDN_of_ CVAD_Site_1_delivery_controller%).name) -TargetFolder '\\share\ CVAD_Site_1' -MachineCatalogPrefix "Site1-" -GroupPolicyPrefix "Site1-" -TagPrefix "Site1-"

New-CvadAcSiteMergingInfo -SiteName $((get-brokersite -AdminAddress %FQDN_of_ CVAD_Site_2_delivery_controller%).name) -TargetFolder '\\share\ CVAD_Site_2' -MachineCatalogPrefix "Site2-" -GroupPolicyPrefix "Site2-" -TagPrefix "Site2-"

The result of running these commands is the creation of SiteMerging.yml file in both locations. The SiteMerging.yml file will look similar to this:

CVAD_Site_1:

      SiteRootFolder: ""

      AdminScopePrefix: ""

      AdminRolePrefix: ""

      ApplicationAdminPrefix: ""

      ApplicationFolderPrefix: ""

      ApplicationFolderRoot: ""

      ApplicationGroupPrefix: ""

      ApplicationUserPrefix: ""

      DeliveryGroupPrefix: ""

      GroupPolicyPrefix: "Site1-"

      HostConnectionPrefix: ""

      MachineCatalogPrefix: “Site1-”

      StoreFrontPrefix: ""

      TagPrefix: "Site1-"

      AdminScopeSuffix: ""

      AdminRoleSuffix: ""

      ApplicationAdminSuffix: ""

      ApplicationFolderSuffix: ""

      ApplicationGroupSuffix: ""

      ApplicationUserSuffix: ""

      DeliveryGroupSuffix: ""

      GroupPolicySuffix: ""

      HostConnectionSuffix: ""

      MachineCatalogSuffix: ""

      StoreFrontSuffix: ""

      TagSuffix: ""

The next thing is to make a copy of SiteMerging.yml file and rename that copy to SitePrefixes.yml. In the Citrix documentation, there is a section about these files, but it was a bit unclear, what I have done and what got me going is having these two files created. They are identical, just different names.

This got us merging files for both sites. The next thing is to export the CVAD site configurations. Run the following commands to export the CVAD sites:

Export-CvadAcToFile -AdminAddress %FQDN_of_CVAD_Site_1_delivery_controller% -SiteName $((get-brokersite -AdminAddress %FQDN_of_CVAD_Site_1_delivery_controller %).name) -TargetFolder '\\share\CVAD_Site_1

Export-CvadAcToFile -AdminAddress %FQDN_of_CVAD_Site_2_delivery_controller% -SiteName $((get-brokersite -AdminAddress %FQDN_of_CVAD_Site_2_delivery_controller %).name) -TargetFolder '\\share\CVAD_Site_2

Now that we have sites exported, we need to populate the following files:

• CustomerInfo.yml
• ZoneMapping.yml
• CvadAcSecurity.yml

For the CustomerInfo.yml file the following information is needed:

CustomerId: ‘Your_Customer_ID’ 
ClientId: ‘Your_Client ID’
Secret: ‘Your_Secret’

Please follow the Migrate configuration to Citrix Cloud | Citrix DaaS Citrix article to obtain these values. Once you get this information, you can update the CustomerInfo.yml manually, or use the PowerShell to update the CustomerInfo.yml. Please note that CustomerInfo.yml must be updated in both locations.

For ZoneMapping.yml, you need to match the existing zone name (in most cases “Primary”, and the name of resource location). Edit ZoneMapping.yml in both locations to align your CVAD sites and resource locations. The ZoneMapping.yml for CVAD_Site_1 should look like this:

Primary: RL-DC1

Subsequently, for CVAD_Site_2 ZoneMapping.yml should look like:

Primary: RL-DC2

Lastly, we need to update the CvadAcSecurity.yml file. The content of the file depends on the type of hosting connection that is in place. In most cases (in my experience) the hosting is VMware vCenter. Once you open the CvadAcSecurity.yml file you will find all of the hosting connections listed, however, the password is not populated, and it has to be populated manually. If this is a security concern, create hosting connections in Citrix DaaS, with identical naming of connections and resources.

Now, we have prepared all of the files required for a successful merge. I don’t use the “Import” command, as the import may have some undesired results once we have multiple sites. Also, I merge the individual components, and the reason for it is that the troubleshooting is easier, and cleanup is faster if one of the components does not merge successfully. You can merge the whole site; this is just my preference.

When merging by components, make sure that the following order is required:

• All
• Tags
• AdminRoles
• AdminScopes
• HostConnections
• MachineCatalogs
• StoreFronts
• DeliveryGroups
• ApplicationGroups
• ApplicationFolders
• Applications
• GroupPolicies
• UserZonePreference

Execute the following commands to merge CVAD sites to Citrix DaaS. For CVAD_Site_1 here is the list of commands for migration by components:

Merge-CvadAcToSite -SiteName CVAD_Site_1 -SourceFolder \\share\CVAD_Site_1 -Tags
Merge-CvadAcToSite -SiteName CVAD_Site_1 -SourceFolder \\share\CVAD_Site_1 -AdminRoles
Merge-CvadAcToSite -SiteName CVAD_Site_1 -SourceFolder \\share\CVAD_Site_1 -AdminScopes
Merge-CvadAcToSite -SiteName CVAD_Site_1 -SourceFolder \\share\CVAD_Site_1 -HostConnections
Merge-CvadAcToSite -SiteName CVAD_Site_1 -SourceFolder \\share\CVAD_Site_1 -MachineCatalogs
Merge-CvadAcToSite -SiteName CVAD_Site_1 -SourceFolder \\share\CVAD_Site_1 -StoreFronts
Merge-CvadAcToSite -SiteName CVAD_Site_1 -SourceFolder \\share\CVAD_Site_1 -DeliveryGroups
Merge-CvadAcToSite -SiteName CVAD_Site_1 -SourceFolder \\share\CVAD_Site_1 -ApplicationGroups
Merge-CvadAcToSite -SiteName CVAD_Site_1 -SourceFolder \\share\CVAD_Site_1 -ApplicationFOlders
Merge-CvadAcToSite -SiteName CVAD_Site_1 -SourceFolder \\share\CVAD_Site_1 -Applications
Merge-CvadAcToSite -SiteName CVAD_Site_1 -SourceFolder \\share\CVAD_Site_1 -GroupPolicies
Merge-CvadAcToSite -SiteName CVAD_Site_1 -SourceFolder \\share\CVAD_Site_1 -UserZonePreferences

In this example, I have listed all of the components, so it is easier to copy/paste commands. Please note that you don’t need to execute commands for the components that are non-existent in on-premises CVAD sites. For example, if you don’t have any StoreFronts configured in your Citrix Studio, you don’t need to execute the command for StoreFronts.

If you want to import all settings and components at once, you can just run the following command:

Merge-CvadAcToSite -SiteName CVAD_Site_1 -SourceFolder \\share\CVAD_Site_1

Repeat these commands for CVAD_Site_2.

If there is a desire to filter by components name, then if you are using prefixes/suffixes for the object that is being migrated, you must include the prefix/suffix in the command as shown in the following example.

Merge-CvadAcToSite -SiteName CVAD_Site_1 -SourceFolder \\share\CVAD_Site_1 -MachineCatalogs -IncludeByName Site1-%machine_catalog_name%

Hope this helps you with the migration process. In Part 2 of this series, we will go over the migration of CVAD Sites that span data centres, with and without Zones defined.