Migrate configuration to Citrix Cloud

Merging multiple sites into a single site

September 11, 2024

Contributed by:

Multi-site support for Automated Configuration provides a method to merge multiple on-premises sites into a single cloud site.

Multi-site support adds unique prefixes and suffixes to component names on a per on-premises-site basis, ensuring name uniqueness after multiple on-premises sites are merged to a single cloud site.

Prefixes and suffixes can be assigned for each of the following components on a per-on-premises-site basis.

AdminScope
AdminRole
ApplicationAdmin
ApplicationFolder
ApplicationGroup
ApplicationUser
DeliveryGroup
GroupPolicy
HostConnection
MachineCatalog
StoreFront
Tag

Application folders support prefixing, suffixing, and rerooting. Rerooting adds an extra top level folder to an application’s existing folder structure.

Prefixing and suffixing rules

Prefixes and suffixes cannot contain any of the following special characters: \ , / ; : # . * ? = < > | ( ) " ' { } [ ]
Prefixes and suffixes can contain trailing spaces but not leading spaces.
Prefixes and suffixes must be double quoted to contain trailing spaces.
Prefixes and suffixes are applied at the time of import, merge, and add. The source .yml files are never modified.
The prefix and suffix process automatically prefixes or suffixes dependent component names when applicable. For example, if machine catalog names are prefixed with “East,” delivery groups referencing them are also prefixed with “East.”
If a component name already begins with the prefix or suffix, no prefix or suffix is added. Component names cannot contain double identical prefixes or suffixes.
Prefixes and suffixes can be individually used or used in combination.
Use of a prefix or a suffix on a component is optional.

Note:

The Full Configuration interface displays components in alphabetical order.

Group by site

Use prefixing to visually group components from a single site. Each site is listed in its own group with prefixing alphabetically controlling the ordering of different site groups.

Group by name

Use suffixing to visually group like-named components from multiple sites. Like-named components from different sites visually alternate.

SitePrefixes.yml file

Site prefixing begins with the SiteMerging.yml file that contains the site prefix and suffix mapping for one or more on-premises sites. You can manage the SiteMerging.yml file manually, or by using the available cmdlets listed at the Merging multiple on-premises sites cmdlets section.

Exporting, importing, merging, and adding

Merging cannot begin until you have exported an on-premises site. To export an on-premises site, see Migrating from on-premises to cloud.

Central export target folder

The methods described in this section place multiple site exports into a central file share location. The SiteMerging.yml file, CustomerInfo.yml file, and all export files reside in that file share location, allowing you to do the import from one location independent of the on-premises sites.

Cloud accessing operations never reference the on-premises sites or Active Directory, therefore allowing you to do cloud-accessing operations from anywhere.

The export, import, merge, and new/add operations provide a parameter to target or source a folder other than the default folder, %HOMEPATH%\Documents\Citrix\AutoConfig. The following examples use a central file share located at \\share.central.net that the admin already has access to, having provided credentials as needed.

To target the export to a site-specific folder, use the –TargetFolder parameter:

From the East DDC:

mkdir \\share.central.net\AutoConfig\SiteEast

Export-CvadAcToFile –TargetFolder \\share.central.net\AutoConfig\SiteEast

From the West DDC:

mkdir \\share.central.net\AutoConfig\SiteWest

Export-CvadAcToFile –TargetFolder \\share.central.net\AutoConfig\SiteWest

After the exports are complete, create the CustomerInfo.yml and SiteMerging.yml files and place them in \\share.central.net\AutoConfig.

Note:

Do not use the SiteRootFolder parameter when creating the SitePrefixes.yml when using this direct file share reference method.

To import, merge, or add from the direct file share, you must decide from which machine you want to do the cloud accessing operation. Options include:

One of the on-premises DDCs where the tool is already installed.
The machine hosting the file share.
A different machine.

Automated Configuration must be installed on the machine accessing the cloud. Neither the on-premises PowerShell SDK, DDC, nor Active Directory are used, so the cloud accessing execution requirements are simpler than the export requirements.

To merge the East DDC to the cloud:

Merge-CvadAcToSite –SiteName East –SourceFolder \\share.central.net\AutoConfig\SiteEast -CustomerInfoFileSpec \\share.central.net\AutoConfig\CustomerInfo.yml

To merge the West DDC to the cloud:

Merge-CvadAcToSite –SiteName West –SourceFolder \\share.central.net\AutoConfig\SiteWest -CustomerInfoFileSpec \\share.central.net\AutoConfig\CustomerInfo.yml

The following is a sample SitePrefixes.yml file used in the previous example.

    East:
      SiteRootFolder: "" # Important: leave this empty
      AdminScopePrefix: "East_"
      AdminRolePrefix: "East_"
      ApplicationAdminPrefix: "East_"
      ApplicationFolderPrefix: "" # Note that a new parent root folder is used instead
      ApplicationFolderRoot: "East"
      ApplicationGroupPrefix: "East_"
      ApplicationUserPrefix: "East_"
      DeliveryGroupPrefix: "East_"
      GroupPolicyPrefix: "East_"
      HostConnectionPrefix: "East_"
      MachineCatalogPrefix: "East_"
      StoreFrontPrefix: "East_"
      TagPrefix: "East_"
      AdminScopeSuffix: "_east"
      AdminRoleSuffix: "_east"
      ApplicationAdminSuffix: "_east"
      ApplicationFolderSuffix: "_east"
      ApplicationGroupSuffix: "_east"
      ApplicationUserSuffix: "_east"
      DeliveryGroupSuffix: "_east"
      GroupPolicySuffix: "_east"
      HostConnectionSuffix: "_east"
      MachineCatalogSuffix: "_east"
      StoreFrontSuffix: "_east"
      TagSuffix: "_east"
    West:
      SiteRootFolder: "" # Important: leave this empty
      AdminScopePrefix: "Western "
      AdminRolePrefix: "Western "
      ApplicationAdminPrefix: "Western "
      ApplicationFolderPrefix: "" # Note that a new parent root folder is used instead
      ApplicationFolderRoot: "Western"
      ApplicationGroupPrefix: "Western "
      ApplicationUserPrefix: "Western "
      DeliveryGroupPrefix: "Western "
      GroupPolicyPrefix: "Western "
      HostConnectionPrefix: "Western "
      MachineCatalogPrefix: "Western "
      StoreFrontPrefix: "Western "
      TagPrefix: "Western "
      AdminScopeSuffix: ""
      AdminRoleSuffix: ""
      ApplicationAdminSuffix: ""
      ApplicationFolderSuffix: ""
      ApplicationGroupSuffix: ""
      ApplicationUserSuffix: ""
      DeliveryGroupSuffix: ""
      GroupPolicySuffix: ""
      HostConnectionSuffix: ""
      MachineCatalogSuffix: ""
      StoreFrontSuffix: ""
      TagSuffix: ""

This method uses the SiteRootFolder member of the site’s prefixes set. While more involved than the direct file share method, this method reduces the odds of targeting the wrong folder when exporting, importing, merging, or adding.

First, set the SiteRootFolder for each site in the SiteMerging.yml file. You must do this on the shared location.

New-CvadAcSiteMergingInfo –SiteName East –SiteRootFolder \\share.central.net\AutoConfig\SiteEast -SitePrefixesFolder \\share.central.net\AutoConfig

New-CvadAcSiteMergingInfo –SiteName West –SiteRootFolder SiteWest -SitePrefixesFolder \\share.central.net\AutoConfig

In this example, East is a fully qualified folder specification and West is a relative folder specification.

To target the export to a site-specific folder using the SiteMerging.yml file:

From the East DDC:

mkdir \\share.central.net\AutoConfig\SiteEast

Export-CvadAcToFile -SiteName East -CustomerInfoFileSpec \\share.central.net\AutoConfig\CustomerInfo.yml

From the West DDC:

mkdir \\share.central.net\AutoConfig\SiteWest

Export-CvadAcToFile -SiteName West -CustomerInfoFileSpec \\share.central.net\AutoConfig\CustomerInfo.yml

The export cmdlet uses the CustomerInfo.yml folder location to locate the SiteMerging.yml file. In the case of East, the SiteRootFolder is fully qualified. It is used as-is. In the case of West, the SiteRootFolder is not fully qualified. It is combined with the CustomerInfo.yml folder location to retrieve a fully qualified folder location for West.

To merge the East DDC to the cloud:

Merge-CvadAcToSite –SiteName East -CustomerInfoFileSpec \\share.central.net\AutoConfig\CustomerInfo.yml

To merge the West DDC to the cloud:

Merge-CvadAcToSite –SiteName West -CustomerInfoFileSpec \\share.central.net\AutoConfig\CustomerInfo.yml

The following is a sample SitePrefixes.yml file used in the previous example.

      East:
      SiteRootFolder: "\\\\share.central.net\\AutoConfig\\SiteEast"
      AdminScopePrefix: "East_"
      AdminRolePrefix: "East_"
      ApplicationAdminPrefix: "East_"
      ApplicationFolderPrefix: "" # Note that a new parent root folder is used instead
      ApplicationFolderRoot: "East"
      ApplicationGroupPrefix: "East_"
      ApplicationUserPrefix: "East_"
      DeliveryGroupPrefix: "East_"
      GroupPolicyPrefix: "East_"
      HostConnectionPrefix: "East_"
      MachineCatalogPrefix: "East_"
      StoreFrontPrefix: "East_"
      TagPrefix: "East_"
      AdminScopeSuffix: "_east"
      AdminRoleSuffix: "_east"
      ApplicationAdminSuffix: "_east"
      ApplicationFolderSuffix: "_east"
      ApplicationGroupSuffix: "_east"
      ApplicationUserSuffix: "_east"
      DeliveryGroupSuffix: "_east"
      GroupPolicySuffix: "_east"
      HostConnectionSuffix: "_east"
      MachineCatalogSuffix: "_east"
      StoreFrontSuffix: "_east"
      TagSuffix: "_east"
    West:
      SiteRootFolder: "\\\\share.central.net\\AutoConfig\\SiteWest"
      AdminScopePrefix: "Western "
      AdminRolePrefix: "Western "
      ApplicationAdminPrefix: "Western "
      ApplicationFolderPrefix: "" # Note that a new parent root folder is used instead
      ApplicationFolderRoot: "Western"
      ApplicationGroupPrefix: "Western "
      ApplicationUserPrefix: "Western "
      DeliveryGroupPrefix: "Western "
      GroupPolicyPrefix: "Western "
      HostConnectionPrefix: "Western "
      MachineCatalogPrefix: "Western "
      StoreFrontPrefix: "Western "
      TagPrefix: "Western "
      AdminScopeSuffix: ""
      AdminRoleSuffix: ""
      ApplicationAdminSuffix: ""
      ApplicationFolderSuffix: ""
      ApplicationGroupSuffix: ""
      ApplicationUserSuffix: ""
      DeliveryGroupSuffix: ""
      GroupPolicySuffix: ""
      HostConnectionSuffix: ""
      MachineCatalogSuffix: ""
      StoreFrontSuffix: ""
      TagSuffix: ""

If a central file share method is not used and the import, merge, or add is done from the individual DDCs, then create and replicate the SiteMerging.yml file on each DDC being migrated into the cloud. The default location is %HOMEPATH%\Documents\Citrix\AutoConfig. You must specify the –SiteName parameter to select the correct site prefixes.

Merging the sites

Citrix recommends performing the cloud operations in steps and to do a complete review of each result before doing the next cloud operation. For example, if merging three sites to a single cloud site:

Merge the initial site to the cloud using the appropriate SiteName value.
Review the results in the Full Configuration management interface.
If the results are incorrect, determine the issue and its cause, correct it, and then rerun the merge. If necessary, remove the cloud components and start from scratch by using Remove-CvadAcFromSite for the selected component and members. If the results are correct, continue.
If the initial merge is correct, merge the second site to the single cloud site.
Repeat steps 2 and 3.
If the second merge is correct, merge the third site to the single cloud site.
Repeat steps 2 and 3.
Review the resources from the user’s perspective and verify that the view is in the desired state.

Remove a component using the site prefix

You can selectively remove single site components by using the prefix on the –IncludeByName parameter of the Remove-CvadAcFromSite cmdlet. In the following example, the West DDC delivery groups are not correct. To remove the delivery groups for just the West site:

Remove-CvadAcFromSite –DeliveryGroups –IncludeByName “Western *”

To remove all West components, run the following cmdlets in order.

Remove-CvadAcFromSite –GroupPolicies –IncludeByName “Western *”

Remove-CvadAcFromSite –Applications –IncludeByName “Western *”

Remove-CvadAcFromSite – ApplicationGroups –IncludeByName “Western *”

Remove-CvadAcFromSite –DeliveryGroups –IncludeByName “Western *”

Remove-CvadAcFromSite –MachineCatalogs –IncludeByName “Western *”

Remove-CvadAcFromSite –HostConnections –IncludeByName “Western *”

Remove-CvadAcFromSite –Tags –IncludeByName “Western *”

To remove group policies of the East components, use the suffix:

Remove-CvadAcFromSite –GroupPolicies –IncludeByName “*_east”

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Merging multiple sites into a single site

September 11, 2024

Contributed by:

September 11, 2024

Contributed by:

Merging multiple sites into a single site

Prefixing and suffixing rules

Group by site

Group by name

SitePrefixes.yml file

Exporting, importing, merging, and adding

Central export target folder

Direct file share

File share reference using SiteMerging.yml

Merging the sites

Remove a component using the site prefix

In this article