Migrate to cloud

If you have a Citrix Virtual Apps and Desktops on-premises configuration and you want to move it to a Citrix Virtual Apps and Desktops Service deployment, or you have a Citrix Virtual Apps and Desktops Service deployment that you want to move to another region, you want to back up and restore your configuration, or you have reached your resource limits, you can now migrate all or part of your configuration using the Automated Configuration tool.

Getting started with Automated Configuration

Automated Configuration for Citrix Virtual Apps and Desktops is a tool that allows you to automate migrating your Citrix Virtual Apps and Desktops Service deployment from:

• An on-premises site
• Another cloud site
• A cloud site backup

Automated Configuration exports your configuration information into a collection of .yml files that can then be optionally edited (for staging your migration) and imported into your Citrix Virtual Apps and Desktops Service deployment.

This section provides common details needed to perform the functions of Automated Configuration.

Download Automated Configuration

Download and install the Automated Configuration tool from Citrix Downloads.

Upgrading Automated Configuration

If you are upgrading from a previous version of Automated Configuration, you can make sure you have the latest version by following the steps below:

1. Double-click the Auto Config icon. A PowerShell window appears.

2. Run the following command to check your version number.

   Get-CvadAcStatus

3. Check your tool version against the version listed at Citrix Downloads. The latest version of the tool is located there.

Prerequisites for migrating your configuration

Users of Automated Configuration must be proficient with the following:

• Citrix Virtual Apps and Desktops setup and administration
• The YAML standard
• PowerShell

For exporting your configuration from Citrix Virtual Apps and Desktops:

• Citrix Virtual Apps and Desktops: current release and its immediate predecessor or Citrix Virtual Apps and Desktops, XenApp and XenDesktop LTSRs: all versions
• An on-premises delivery controller and at least a single on-premises VDA
• A machine with .NET Framework 4.7.2 or later
• A machine with the Citrix PowerShell SDK. This is automatically installed on the delivery controller. (To run on machine other than the on-premises delivery controller, the machine must be domain joined and Citrix Studio must be installed, as Studio installs the correct PowerShell snap-ins. The Studio installer can be found on the Citrix Virtual Apps and Desktops installation media.)

For importing your configuration into Citrix Virtual Apps and Desktops Service:

• A machine with access to Citrix Cloud. This does not have to be a delivery controller or a domain joined machine.
• Citrix Virtual Apps and Desktops Service provisioned.
• An active resource location with Connector installed and domain-joined to the same domain as the on-premises setup.
• Connectivity to sites accessing Citrix Cloud must be allowed and available. For more information, see Virtual Apps and Desktops service service connectivity.

Supported objects for migration

Automated Configuration supports the following components.

• Tags
• Delegated Admin
  • Scopes
  • Roles
• Host Connections
  • A Single Resource Pool
  • Admin Scopes
• Machine Catalogs
  • Admin Scopes
  • Machines
  • Remote PC Access, Physical, Pooled, Provisioned (except MCS), Assigned
• Delivery Groups
  • Access Policy
  • Admin Scope Association
  • Application Access Policy
  • Assignment Policy
  • Entitlement/Desktop Policy
  • Power Schedules
  • Session Lingering
  • Session Prelaunch
  • Reboot Schedules
  • Tags
• Application Groups
  • Admin Scope Association
  • Delivery Groups
  • Users and Groups
• Applications
  • Application Folders
  • Icons
  • Applications
  • Broker Configured FTAs
  • Tags
• Group Policies

Component dependency

When creating an on-premises site, the creation steps must be followed in a specific order, due to the dependencies on previous items. Automated Configuration works on the same principles.

The import process is designed to accurately perform updates, only perform needed updates, and verify that all updates have been correctly made.

Components must be imported in an order that creates dependencies in the order they are needed. The following list identifies selectable components in the Export, Import, Merge, New, Sync, and Restore commands. They are listed in their dependency order. Importing out of dependency order might result in failures and cause operations to fail.

1. Tags
2. Admin Roles and Scopes (includes Scopes and Roles, does not include administrators)
3. Host Connections
4. Machine Catalogs
5. Delivery Groups (includes StoreFront)
6. Application Groups
7. Applications (includes Application Folders)
8. Group Policies

Components must be imported in an order that creates dependencies in the order they are needed. Automated Configuration correctly orders components when importing, merging, or restoring multiple components in a single cmdlet execution.

When importing single components with multiple commands, it is necessary to order the components so dependencies are imported in the required order.

Individual imports can then be made for updates after a complete site configuration has been imported successfully.

Dependency details

The components and their dependencies are listed here. A component’s dependencies must be in place before it can be imported or merged. If a dependency is missing, it can cause the import or merge command to fail. The Fixups section of the log file shows missing dependencies if an import or merge fails.

1. Tags
   • No pre-dependencies
2. Delegated Admin
   • No pre-dependencies
3. Host Connections
   • Security Information in CvadAcSecurity.yml
4. Machine Catalogs
   • Machines present in Active Directory
   • Host Connections
   • Tags
5. Delivery Groups
   • Machines present in Active Directory
   • Users present in Active Directory
   • Machine Catalogs
   • Tags
6. Application Groups
   • Delivery Groups
   • Tags
7. Applications
   • Delivery Groups
   • Application Groups
   • Tags
8. Group Policies
   • Delivery Groups
   • Tags

Known limitations

• Machine catalogs provisioned through Machine Creation Services are not currently supported. You can still import other objects from your site. For more information on MCS, see Importing other objects when you have Machine Creation Services machine catalogs.
• Icons are not applied to machines or desktops.

Generating the customer ID, client ID, and secret key

The following steps allow you to retrieve the customer ID and create the client ID and secret key that are required to import your configuration to Citrix Cloud. All cmdlets accessing the cloud require these values.

To retrieve the Customer ID:

1. Sign into your Citrix Cloud account and select the customer.

   

2. Click the hamburger menu, then select Identity and Access Management in the drop-down menu.

   

3. The Customer ID is located on the Identity and Access Management page.

   

To retrieve the Client ID and Secret Key:

1. On the Identity and Access Management page, click the API Access tab.

   

2. Enter a name in the box. This name is used to differentiate between multiple client IDs and secret keys. Click Create Client to create the client ID and the secret key.

   

3. The following dialog appears after you successfully create the client ID and the secret key. Be sure to copy both values to a secure location or download the .csv file containing this information.

   

4. The client ID and the secret key are successfully created.

   

Place these values in a secure location and share only with trusted company members who need access to the tool or access the cloud Rest APIs. The client ID and secret key do not expire. If they are compromised, immediately remove them by using the Trash icon and create new ones.

Note:

The secret key cannot be retrieved if it is lost or forgotten; a new client ID and secret key must be created.

Populating customer info file

Using the CustomerInfo.yml file eliminates the need to provide customer information parameters with each cmdlet’s execution. Any of the customer information can be overridden by using cmdlet parameters.

Create the CustomerInfo.yml file by using the New-CvadAcCustomerInfoFile cmdlet. New-CvadAcCustomerInfoFile has the following required parameters.

• CustomerId – customer’s ID.
• ClientId – customer’s client ID created on Citrix Cloud.
• Secret – customer’s secret created on Citrix Cloud.

New-CvadAcCustomerInfoFile -CustomerId markhof123 -ClientId 6813EEA6-46CC-4F8A-BC71-539F2DAC5984 -Secret TwBLaaaaaaaaaaaaaaaaaw==

Update the CustomerInfo.yml file by using the Set-CvadAcCustomerInfoFile cmdlet.

Note:

The cmdlet only changes the Client ID.

Set-CvadAcCustomerInfoFile -ClientId C80487EE-7113-49F8-85DD-2CFE30CC398E

The following is a sample CustomerInfo.yml file.

---
#  Created/Updated on 2020/01/29 16:46:47
CustomerId: "markhof123"
CustomerId: "markhof123"
ClientId: "6713FEA6-46CC-4F8A-BC71-539F2DDK5384"
Secret: "TwBLaaabbbaaaaaaaaaaw=="
LogFileName: "CitrixLog"
Environment: Production
AltRootUrl: ""
StopOnError: False
AlternateFolder: ""
Locale: "en-us"
Editor: “C:\Program Files\Notepad++\notepad++.exe”
Confirm: True
DisplayLog: True

Populating zone mapping file

An on-premises zone is the equivalent of the cloud resource location. Unlike other site components, you cannot import the on-premises zone to the cloud automatically. Instead, it must be manually mapped using the ZoneMapping.yml file. Import failures can occur if the zone name is not associated with an existing resource location name.

For on-premises sites having only one zone and cloud sites only one resource location, the Automated Configuration tool makes the correct association, eliminating the need to manually manage the ZoneMapping.yml file.

For on-premises sites having multiple zones or cloud sites having multiple resource locations, the ZoneMapping.yml file must be manually updated to reflect the correct mapping of on-premises zones to cloud resource locations. This must be done prior to attempting any import operation to the cloud.

The ZoneMapping.yml file is located in %HOMEPATH%\Documents\Citrix\AutoConfig. The content of the .yml file is a dictionary with the zone name as the key and the resource location name as the value.

As an example, an on-premises Citrix Virtual Apps and Desktops site with a primary zone called “Zone-1” and a secondary zone called “Zone-2” is migrated to a Citrix Virtual Apps and Desktops cloud deployment with two newly created cloud resource locations called “Cloud-RL-1” and “Cloud-RL-2”. In this instance, the ZoneMapping.yml would be configured as follows:

---
Zone-1: Cloud-RL-1

Zone-2: Cloud-RL-2

Note:

A space must be between the colon and resource location name. If spaces are used in the zone or resource location name, enclose the name with quotes.

Migrating from on-premises to cloud

Automated Configuration allows you to automate moving your on-premises configuration to a cloud site.

Migration high level view

Migration is the process of exporting data from a source followed by importing that same data into a target. This is what Automated Configuration does. For customers migrating to the cloud from an on-premises environment, the source is their on-premises site and the target their cloud site. In its simplest form, the first-time-use migration process is the following steps, with example cmdlets.

1. Download and install the Automated Configuration tool.
2. Export the on-premises data (Export-CvadAcToFile).
3. Obtain the needed security information to access your cloud site.
4. Create the customer info file containing the security information used by the Automated Configuration tool (New-CvadAcCustomerInfoFile).
5. Import the on-premises data into the cloud (Import-CvadAcToSite, Merge-CvadAcToSite, New-CvadAcToSite).

Successive migrations are even simpler.

1. Export the on-premises data (Export-CvadAcToFile).
2. Import the on-premises data into the cloud (Import-CvadAcToSite, Merge-CvadAcToSite, New-CvadAcToSite).

The above can even be reduced to one step.

1. Export and import (Sync-CvadAcSiteToSite).

Exporting your Citrix Virtual Apps and Desktops on-premises configuration

Important:

• You must have your CustomerInfo.yml file with your customer ID, client ID, and the secret key information included. For more information on how to retrieve your customer ID, client ID and secret key, see Generating the customer ID, client ID, and secret key. For information on how to add this information to the CustomerInfo.yml file, see Populating customer info file.
• The ZoneMapping.yml file must include information that maps your on-premises zone to Resource Locations in the cloud. For more information on how to map your zones, see Populating zone mapping file.
• If you have host connections, you must input the corresponding info in the CvadAcSecurity.yml file.

1. Install Automated Configuration.
2. Double-click the Auto Config icon. A PowerShell window appears.

3. Run the following command to export all components.

   Export-CvadAcToFile

After you run any cmdlet for the first the time, an export folder with the .yml configuration files and logs is created. The folder is at %HOMEPATH%\Documents\Citrix\AutoConfig. Each successive export creates a subfolder. The parent folder %HOMEPATH%\Documents\Citrix\AutoConfig always contains the exported files from the most recent export.

Note:

If Automated Configuration is not installed on the delivery controller, run import-module Citrix.AutoConfig.Commands before using the tool through PowerShell. This is not needed if you open Automated Configuration using the Auto Config icon.

If you encounter any errors or exceptions, see the Fixups section in the log file.

Importing your configuration to Citrix Virtual Apps and Desktops Service

Important:

• You must have your CustomerInfo.yml file with your customer ID, client ID, and the secret key information included. For more information on how to retrieve your customer ID, client ID and secret key, see Generating the customer ID, client ID, and secret key. For information on how to add this information to the CustomerInfo.yml file, see Populating customer info file.
• The ZoneMapping.yml file must include information that maps your on-premises zone to resource locations in the cloud. For more information on how to map your zones, see Populating zone mapping file.
• If you have host connections, you must input the corresponding info in the CvadAcSecurity.yml file.

Running an import

1. Double-click the Auto Config icon. A PowerShell window appears.

2. Run the following command to import all components.

   Merge-CvadAcToSite

Verify the expected state with the new current state. Various import options control whether the import results are identical or a subset of the on-premises site. See Derived state results by command for an explanation of the options and resultant state.

After you run the cmdlet, an export folder with the .yml configuration files and logs is created. The folder is at %HOMEPATH%\Documents\Citrix\AutoConfig.

If you encounter any errors or exceptions, see the Fixups section in the log file.

Note:

If Automated Configuration is not installed on the delivery controller, run import-module Citrix.AutoConfig.Commands before using the tool through PowerShell. This is not needed if you open Automated Configuration using the Auto Config icon.

To revert to your original Citrix Virtual Apps and Desktops Service configuration, see Backing up your Citrix Virtual Apps and Desktops Service configuration.

Import operation in detail

The import process is designed to accurately perform updates, only perform needed updates and verify that all updates have been correctly made. The steps followed in all import operations follow.

1. Read the exported .yml file (expected state).
2. Read the cloud (current state).
3. Back up the pre-import cloud state to .yml files (pre-backup can be restored if necessary).
4. Evaluate the differences between the expected and current state. This determines which updates to make.
5. Make the updates.
6. Reread the cloud (new current state).
7. Back up the post-import cloud state to .yml files (post-backup can be restored if necessary).
8. Compare the new current state with the expected state.
9. Report the results of the comparison.

Activating sites

Note:

This feature is available only on versions 2.0 and later. Check your version by using Get-CvadAcStatus within Automated Configuration.

The delivery controller in both on-premises and cloud sites control resources such as brokering desktops, applications, and rebooting machines. Problems occur when a common set of resources is controlled by two or more sites. Such a situation can occur when migrating from an on-premises site to a cloud site. It is possible for both the on-premises and cloud delivery controllers to manage the same set of resources. Such dual management can lead to resources becoming unavailable and unmanageable, and can be difficult to diagnose.

Site activation allows you to control where the active site is controlled.

Site activation is managed using the delivery group maintenance mode. Delivery groups are placed in maintenance mode when the site is inactive. Maintenance mode is removed from delivery groups for sites that are active.

• Set-CvadAdSiteActiveStateCloud
• Set-CvadAdSiteActiveStateOnPrem

All cmdlets support the IncludeByName and ExcludeByName filtering.

Import and transferring control to the cloud

The following is a high level description on how to import and transfer control from the on-prem site to the cloud site.

1. Export and import the on-premises site to the cloud. Make sure the –SiteActive parameter is not present on any of the import cmdlets. The on-premises site is active and the cloud site inactive. By default, cloud site delivery groups are in maintenance mode.
2. Verify the cloud content and configuration.
3. During off hours, set the on-premises site to inactive. The –SiteActive parameter must be absent. All on-premises site delivery groups are in maintenance mode.
   • Set-CvadAcSiteActiveStateOnPrem
4. Set the cloud site to active. The –SiteActive parameter must be present. No cloud site delivery groups are in maintenance mode.
   • Set-CvadAcSiteActiveStateCloud –SiteActive
5. Verify that the cloud site is active and the on-premises site is inactive.

Transferring control back to the on-premises site

To transfer control from the cloud site to the on-premises site:

1. During off hours, set the cloud site to inactive. All cloud site delivery groups are in maintenance mode.
   • Set-CvadAcSiteActiveStateCloud
2. Set the on-premises site to active. No on-prem site delivery groups are in maintenance mode.
   • Set-CvadAcSiteActiveStateOnPrem -SiteActive

Migrating from cloud to cloud

Automated Configuration allows you to automate moving your cloud configuration to another cloud site or allowing you to restore your own cloud site.

Moving your Citrix Virtual Apps and Desktops Service configuration can be beneficial for many reasons:

• Migrating from one region to another
• Syncing your site from test or stage to production
• Disaster recovery
• Reaching resource limits

Backing up your Citrix Virtual Apps and Desktops Service configuration

Note:

Before you begin, follow the Import steps in Prerequisites for migrating your configuration to migrate your configuration from one cloud to another.

Important:

• You must have your CustomerInfo.yml file with your customer ID, client ID, and the secret key information included. For more information on how to retrieve your customer ID, client ID and secret key, see Generating the customer ID, client ID, and secret key. For information on how to add this information to the CustomerInfo.yml file, see Populating customer info file.
• The ZoneMapping.yml file must include information that maps your resource locations in the cloud. For more information on how to map your zones, see Populating zone mapping file.
• If you have host connections, you must input the corresponding info in the CvadAcSecurity.yml file.

1. Install Automated Configuration.

   Note:

   For cloud-to-cloud migration, Automated Configuration can be installed on a machine having access to the internet that the administrator has direct access to.

2. Double-click the Auto Config icon. A PowerShell window appears.

3. Run the following command to do a backup.

   Backup-CvadAcToFile

After you run any cmdlet for the first the time, an export folder with the .yml configuration files and logs is created. The folder is at %HOMEPATH%\Documents\Citrix\AutoConfig.

If you encounter any errors or exceptions, see the Fixups section in the log file.

Restoring your configuration to Citrix Virtual Apps and Desktops Service

Note:

This section follows Backing up your Citrix Virtual Apps and Desktops Service configuration and the steps documented there. Follow those steps before beginning the restore.

Running a restore

1. Double-click the Auto Config icon. A PowerShell window appears.

2. Run the following command to do a restore.

   Restore-CvadAcToSite -RestoreFolder <folder path of the backup files>

Verify the expected state with the new current state.

After you run the cmdlet, an export folder with the .yml configuration files and logs is created. The folder is at %HOMEPATH%\Documents\Citrix\AutoConfig.

If you encounter any errors or exceptions, see the Fixups section in the log file.

Activiating sites

Site activation allows you to control where the active site is controlled. For more information on activating sites, see Activating sites.

Disaster recovery

The disaster recovery process protects you from unintentional cloud site configuration changes or corruption. While Automated Configuration makes backups each time a change is made, this backup reflects the state of the cloud site configuration before the changes. Protecting yourself requires that you periodically back up your cloud site configuration and saving it in a safe place. If an undesirable change or corruption takes place, the backup can be used to fix the change or corruption at either a granular or full site configuration level.

Backup

To back up, run the backup cmdlet: Backup-CvadAcToFile

While individual components can be selected when backing up, for disaster recovery, Citrix suggests backing up all components. Backups are placed in a uniquely named folder under the root folder: %HOMEPATH%\Documents\Citrix\AutoConfig/Backup_yyyy_mm_dd_hh_mm_ss

Restore

Restore can be done from any backup to restore either one or more component members, one or more components or the full cloud site configuration.

Restoring Component Members

Restoring one or more component members makes use of the IncludeByName feature. The Restore cmdlet is invoked with the RestoreFrom parameter along with the selected single component and the inclusion list.

To restore two group policies from a backup, follow this example:

Restore-CvadAcToSite -RestoreFrom %HOMEPATH%\Documents\Citrix\AutoConfig/Backup_yyyy_mm_dd_hh_mm_ss

-GroupPolicies $true -IncludeByName Policy1,Policy2

Restoring Entire Components

Restoring one component involves selecting one or more component parameters.

To restore the entire delivery group and machine catalog components, follow this example:

Restore-CvadAcToSite -RestoreFrom %HOMEPATH%\Documents\Citrix\AutoConfig/Backup_yyyy_mm_dd_hh_mm_ss

-DeliveryGroups $true -MachineCatalogs $true

Restoring the entire cloud site configuration

Restoring the full cloud site configuration means selecting all components to restore.

To restore the entire cloud site configuration, follow this example:

Restore-CvadAcToSite -RestoreFrom %HOMEPATH%\Documents\Citrix\AutoConfig/Backup_yyyy_mm_dd_hh_mm_ss

Merging multiple sites into a single site

Note:

This feature is available only on versions 2.0 and later. Check your version by using Get-CvadAcStatus within Automated Configuration.

Multi-site support 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

1. Prefixes and suffixes cannot contain any of the following special characters: \ , / ; : # . * ? = < > | ( ) " ' { } [ ]
2. Prefixes and suffixes can contain trailing spaces but not leading spaces.
3. Prefixes and suffixes must be double quoted to contain trailing spaces.
4. Prefixes and suffixes are applied at the time of import, merge, and add. The source .yml files are never modified.
5. 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.”
6. If a component name already begins with the prefix or suffix, no prefix or suffix is added. Component names cannot contain double identical prefixes of suffixes.
7. Prefixes and suffixes can be individually used or used in combination.
8. Use of a prefix or a suffix on a component is optional.

Note:

Web Studio 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 Site merging 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.

Direct file share

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: ""

File share reference using SiteMerging.yml

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.

Set-CvadAcSitePrefixes –SiteName East –SiteRootFolder \\share.central.net\AutoConfig\SiteEast -SitePrefixesFolder \\share.central.net\AutoConfig

Set-CvadAcSitePrefixes –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:

1. Merge the initial site to the cloud using the appropriate SiteName value.
2. Review the results in Studio (on-premises or web.)
3. 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.
4. If the initial merge is correct, merge the second site to the single cloud site.
5. Repeat steps 2 and 3.
6. If the second merge is correct, merge the third site to the single cloud site.
7. Repeat steps 2 and 3.
8. 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”

Automated Configuration tool cmdlets

• Site management cmdlets

• Customer info file cmdlets

• Support and troubleshooting cmdlets

• Site activation cmdlets

• Site merging cmdlets

• Component selection parameters

• Filtering by object names

• Migration parameters

• Cloud-accessing parameters

• Log display parameters

• Derived state results by command

• Cmdlet return values

• Help

Site management cmdlets

• Export-CvadAcToFile

  Exports configuration from your on-premises setup. This is the default export operation for Automated Configuration. No modifications are made to the on-premises site configuration. Exported files are placed in the directory %HOMEPATH%\Documents\Citrix\AutoConfig in a uniquely named Export subfolder. The folder %HOMEPATH%\Documents\Citrix\AutoConfig always contains the latest exported on-premises site configuration.

  Parameters:

  • See Component selection parameters
  • See Filtering by object names
  • TargetFolder - specifies the export destination folder.
  • Locale – specifies the language of human-readable text that can be exported.
  • Quiet - suppress logging to the console (available only on version 2.0 or later).
  • AdminAddress – specifies the delivery controller’s DNS or IP address when the export is not being run on the delivery controller.
  • CheckUserAndMachines – verifies if users and machines are in Active Directory. Users and machines that are not in Active Directory might result in import failures.

  Returns:

  • See Cmdlet return values

• Import-CvadAcToSite

  Imports all the on-premises files to the cloud. This command ensures the cloud end state is identical to the on-premises state. This option deletes any changes that exist in the cloud. Imported site configuration files are sourced from %HOMEPATH%\Documents\Citrix\AutoConfig. Use with caution.

  Parameters:

  • See Component selection parameters
  • See Filtering by object names
  • See Cloud-accessing parameters
  • SourceFolder - identifies a substitute root folder for %HOMEPATH%\Documents\Citrix\AutoConfig.
  • Locale – specifies the language of human-readable text that can be exported.
  • Quiet - suppress logging to the console (available only on version 2.0 or later).
  • DisplayLog – displays the log file at the completion of the cmdlet. Set to $false to suppress the log display.
  • Merge – When set to $true, only adds components to the cloud site. Components are not removed. Set to $false to remove components.
  • AddOnly – When set to $true, adds only new components, does not update or delete existing components. Set to $false to allow updates and deletions. Merge is ignored when this parameter is $true.

  Returns:

  • See Cmdlet return values

• Merge-CvadAcToSite

  Merges the on-premises files to the cloud, but does not delete any components in the cloud. This preserves changes already made in the cloud. If a component exists in Citrix Cloud with the same name, this command can modify that component. This is the default import operation for Automated Configuration. Merged site configuration files are sourced from %HOMEPATH%\Documents\Citrix\AutoConfig.

  Parameters:

  • See Component selection parameters
  • See Filtering by object names
  • See Cloud-accessing parameters
  • SourceFolder - identifies a substitute root folder for %HOMEPATH%\Documents\Citrix\AutoConfig.
  • Locale – specifies the language of human-readable text that can be exported.
  • Quiet - suppress logging to the console (available only on version 2.0 or later).
  • DisplayLog – displays the log file at the completion of the cmdlet. Set to $false to suppress the log display.
  • AddOnly – When set to $true, adds only new components, does not update or delete existing components. Set to $false to allow updates and deletions. Merge is ignored when this parameter is $true.

  Returns:

  • See Cmdlet return values

• Restore-CvadAcToSite

  Restores the cloud site to the previous configuration. Imported files are sourced from the folder specified in the -RestoreFolder parameter. This can be used for reverting to your previous configuration or for disaster recovery of your cloud site.

  Parameters:

  • See Component selection parameters
  • See Filtering by object names
  • See Cloud-accessing parameters
  • RestoreFolder - identifies the folder containing the .yml files to restore to the cloud site. This must be a fully qualified folder specification.
  • Locale – specifies the language of human-readable text that can be exported.
  • Quiet - suppress logging to the console (available only on version 2.0 or later).
  • DisplayLog – displays the log file at the completion of the cmdlet. Set to $false to suppress the log display.
  • Merge – When set to $true, only adds components to the cloud site. Components are not removed. Set to $false to remove components.
  • AddOnly – When set to $true, adds only new components, does not update or delete existing components. Set to $false to allow updates and deletions. Merge is ignored when this parameter is $true.

  Returns:

  • See Cmdlet return values

• New-CvadAcToSite

  Imports on-premises site configuration to the cloud but only adds new components. Existing cloud site components are neither updated nor deleted. Use this command if your existing cloud site components must remain unchanged.

  Parameters:

  • See Component selection parameters
  • See Filtering by object names
  • See Cloud-accessing parameters
  • SourceFolder - identifies a substitute root folder for %HOMEPATH%\Documents\Citrix\AutoConfig.
  • Locale – specifies the language of human-readable text that can be exported.
  • Quiet - suppress logging to the console (available only on version 2.0 or later).
  • DisplayLog – displays the log file at the completion of the cmdlet. Set to $false to suppress the log display.

  Returns:

  • See Cmdlet return values

• Sync-CvadAcToSite

  Sync performs both an export and import in one step.

  Parameters:

  • See Component selection parameters
  • See Filtering by object names
  • See Cloud-accessing parameters
  • SourceTargetFolder - specifies the export/import destination folder.
  • Locale – specifies the language of human-readable text that can be exported.
  • AdminAddress - specifies the delivery controller’s DNS or IP address when the export is not being run on the delivery controller.
  • Quiet - suppress logging to the console (available only on version 2.0 or later).
  • DisplayLog – displays the log file at the completion of the cmdlet. Set to $false to suppress the log display.
  • Merge – When set to $true, only adds components to the cloud site. Components are not removed. Set to $false to remove components.
  • AddOnly – When set to $true, adds only new components, does not update or delete existing components. Set to $false to allow updates and deletions. Merge is ignored when this parameter is $true.

  Returns:

  • See Cmdlet return values

• Backup-CvadAcToFile

  Exports your cloud configuration to .yml files. This backup can be used in a disaster recovery process to restore lost components.

  Parameters:

  • See Component selection parameters
  • See Cloud-accessing parameters
  • TargetFolder - specifies the export destination folder.
  • Locale – specifies the language of human-readable text that can be exported.
  • Quiet - suppress logging to the console (available only on version 2.0 or later).
  • DisplayLog – displays the log file at the completion of the cmdlet. Set to $false to suppress the log display.

  Returns:

  • See Cmdlet return values

• Compare-CvadAcToSite

  Compares the on-premises .yml files with the cloud configuration, producing a report of changes that are made by an Import, Merge, or Restore cmdlet.

  Parameters:

  • See Component selection parameters
  • See Filtering by object names
  • See Cloud-accessing parameters
  • SourceFolder - identifies a substitute root folder for %HOMEPATH%\Documents\Citrix\AutoConfig.
  • Locale – specifies the language of human-readable text that can be exported.
  • Quiet - suppress logging to the console (available only on version 2.0 or later).
  • DisplayLog – displays the log file at the completion of the cmdlet. Set to $false to suppress the log display.
  • Merge – When set to $true, only adds components to the cloud site. Components are not removed. Set to $false to remove components.
  • AddOnly – When set to $true, adds only new components, does not update or delete existing components. Set to $false to allow updates and deletions. Merge is ignored when this parameter is $true.

  Returns:

  • See Cmdlet return values

• Remove-CvadAcFromSite

  Can reset the entire site or remove member items from a component (For example, removing one machine catalog from the list of catalogs). This can be used when coupled with the IncludeByName parameter to selectively remove specific members.

  Parameters:

  • See Component selection parameters
  • See Filtering by object names
  • See Cloud-accessing parameters
  • Quiet - suppress logging to the console (available only on version 2.0 or later).
  • DisplayLog – displays the log file at the completion of the cmdlet. Set to $false to suppress the log display.

  Returns:

  • See Cmdlet return values

Customer info file cmdlets

• New-CvadAcCustomerInfoFile

  Create a customer info file. By default, the customer info file is located at %HOMEPATH%\Documents\Citrix\AutoConfig.

  Parameters:

  • CustomerId – customer’s ID (required).
  • ClientId – customer’s client ID created on Citrix Cloud (required).
  • Secret – customer’s secret key created on Citrix Cloud (required).
  • Environment – Production or ProductionGov environment.
  • LogFileName – Change the log file prefix from CitrixLog to something else.
  • StopOnError – Stops the operation upon first error.
  • AlternateRootFolder – Use the specified folder as the root folder instead of %HOMEPATH%\Documents\Citrix\AutoConfig.
  • Locale – use the specified local instead of the locale derived from the system the tool is run on.
  • Editor – use the specified editor to display the log at the completion of each cmdlet. Notepad.exe is the default editor. This parameter must include the fully qualified file specification to the editor and the editor must take the log file spec as its only parameter.

  Returns:

  • See Cmdlet return values

  Example:

  New-CvadAcCustomerInfoFile -CustomerId markhof123 -ClientId 6813EEA6-46CC-4F8A-BC71-539F2DAC5984 -Secret TwBLaaaaaaaaaaaaaaaaaw==

• Set-CvadAcCustomerInfoFile

  Update an existing customer info file. Only cmdlet specified parameters are changed, all unspecified parameter values in the CustomerInfo.yml file are unchanged.

  Parameters:

  • CustomerId – customer’s ID (required).
  • ClientId – customer’s client ID created on Citrix Cloud (required).
  • Secret – customer’s secret key created on Citrix Cloud (required).
  • Environment – Production or ProductionGov environment.
  • LogFileName – Change the log file prefix from CitrixLog to something else.
  • StopOnError – Stops the operation upon first error.
  • AlternateRootFolder – Use the specified folder as the root folder instead of %HOMEPATH%\Documents\Citrix\AutoConfig.
  • Locale – use the specified local instead of the locale derived from the system the tool is run on.
  • Editor – use the specified editor to display the log at the completion of each cmdlet. Notepad.exe is the default editor. This parameter must include the fully qualified file specification to the editor and the editor must take the log file spec as its only parameter.

  Returns:

  • See Cmdlet return values

Support and troubleshooting cmdlets

• New-CvadAcTemplateToFile

  Creates a template file for selected components, allowing you to manually create an import file.

  Parameters:

  • See Component selection parameters
  • TargetFolder - specifies the export destination folder.

  Returns:

  • See Cmdlet return values

• Show-CvadAcDocument - Displays this document in the default browser.

  Parameters:

  • None.

  Returns:

  • Display this webpage in the default web browser.

• Test-CvadAcConnectionWithSite

  Test the connection with the cloud site to verify the communication connection is working. This cmdlet uses the cloud accessing parameters or the CustomerInfo.yml file to specify the customer connection information.

  Parameters:

  • See Cloud-accessing parameters
  • SiteId - identifies the site to test for a valid connection.
  • Quiet - suppress logging to the console (available only on version 2.0 or later).

  Returns:

  • Test results are displayed on the command line.

• Find-CvadAcConnector

  Locates existing connectors and determines their running state. This cmdlet uses information from the CustomerInfo.yml file or the customer ID parameter to locate the customer’s connectors.

  Parameters:

  • CustomerInfoFileSpec - The file specification pointing to a customer information file to override the default location and name. This parameter is ignored when the CustomerId parameter is provided.
  • CustomerId – the customer’s ID, this parameter overrides the same value in the CustomerInfo.yml file.

  Returns:

  • Results are shown on the command line.

• New-CvadAcZipInfoForSupport

  Note:

  The New-CvadAcZipInfoForSupport cmdlet is available only on versions 2.0 and later. Check your version by using Get-CvadAcStatus within Automated Configuration.

  Zips all log and .yml files in a single zip file to send to Citrix for support. Customer sensitive information (CustomerInfo.yml and CvadAcSecurity.yml) is not included in the zip. The Icon.yml file is also excluded due to its size. The zip file is placed in %HOMEPATH%\Documents\Citrix\AutoConfig and named CvadAcSupport_yyyy_mm_dd_hh_mm_ss.zip, based on the date and timestamp. This zip file can also act as a backup.

  Parameters:

  • AlternateFolder - specifies an alternate folder to save the zip file to.
  • Quiet - suppress logging to the console (available only on version 2.0 or later).

  Returns:

  • Zip file with zip file name and location is displayed on the command prompt.

• Get-CvadAcCustomerSites

  Returns the list of all the customer sites. This cmdlet uses the cloud accessing parameters or the CustomerInfo.yml file to specify the customer connection information.

  Parameters:

  • See Cloud-accessing parameters

  Returns:

  • Displays a list of found customer site IDs.

• Get-CvadAcStatus

  Returns information about the tool and the environment it is running in, including the tool version, whether the user has site administrator privileges for exporting, whether customer information (Customer ID, Client ID, and Secret) is present, whether the site can be communicated with, whether the Provisioning Services enhanced feature is present, and whether one or more connectors are present.

  Parameters:

  • See Cloud-accessing parameters
  • SiteId - identifies the site to connect to (optional).
  • AdminAddress - is the DNS or IP address of the on-premises delivery controller used to verify the admins access level. This is required if the tool is not being run on a delivery controller.

  Returns:

  • Displays the results for each item.

Site activation cmdlets

Note:

This feature is available only on versions 2.0 and later. Check your version by using Get-CvadAcStatus within Automated Configuration.

• Set-CvadAcSiteActiveStateOnPrem

  Sets the on-premises site state to either active or inactive.

  Parameters:

  • See Cloud-accessing parameters
  • SiteActive – when present, sets the on-premises site to active removing the maintenance mode from all delivery groups. When this parameter is not present, maintenance mode is set on all delivery groups.
  • IncludeByName – a list specifying the names of delivery groups to include when setting the site active state to active. The ‘*’ and ‘?’ wildcards are supported in names.
  • ExcludeByName – a list specifying the names of delivery groups to exclude when setting the site active state to active. The ‘*’ and ‘?’ wildcards are supported in names.
  • Quiet - suppress logging to the console
  • DisplayLog – displays the log file at the completion of the cmdlet. Set to $false to suppress the log display.

  Returns:

  • See Cmdlet return values

• Set-CvadAcSiteActiveStateCloud

  Sets the cloud site state to either active or inactive.

  Parameters:

  • See Cloud-accessing parameters
  • SiteActive – when present, sets the on-premises site to active removing the maintenance mode from all delivery groups. When this parameter is not present, maintenance mode is set on all delivery groups.
  • IncludeByName – a list specifying the names of delivery groups to include when setting the site active state to active. The ‘*’ and ‘?’ wildcards are supported in names.
  • ExcludeByName – a list specifying the names of delivery groups to exclude when setting the site active state to active. The ‘*’ and ‘?’ wildcards are supported in names.
  • Quiet - suppress logging to the console
  • DisplayLog – displays the log file at the completion of the cmdlet. Set to $false to suppress the log display.

  Returns:

  • See Cmdlet return values

Site merging cmdlets

Note:

This feature is available only on versions 2.0 and later. Check your version by using Get-CvadAcStatus within Automated Configuration.

For more information on site merging and usage of these cmdlets, see Merging multiple sites into a single site.

• New-CvadAcSiteMergingInfo - Creates a site merging prefix/suffix info set. It is not necessary to know all prefixes or suffixes at the beginning. They can be updated with Set-CvadAcSiteMergingInfo or by manually editing the SiteMerging.yml file.
• Set-CvadAcSiteMergingInfo - Updates an existing site merging prefix/suffix info set.
• Remove-CvadAcSiteMergingInfo - Removes an existing site merging prefix/suffix info set.

Site merging parameters

• SiteName –the name used to identify the set of prefixes/suffixes for a specific site. It can match the name of the actual site but does not need to. SiteName is a required parameter. Note: This is the only supported parameter for Remove-CvadAcSiteMergingInfo.
• Quiet - suppress logging to the console (available only on version 2.0 or later).
• AdminScopedPrefix – the prefix to apply to administrator scopes.
• ApplicationPrefix - the prefix to apply to applications.
• ApplicationFolderPrefix – the prefix to apply to application folders; ApplicationFolderPrefix can be combined with ApplicationFolderRoot.
• ApplicationFolderRoot – the new root folder to application folders. This creates an extra folder hierarchy. ApplicationFolderRoot can be combined with ApplicationFolderPrefix.
• ApplicationGroupPrefix – the prefix for application groups.
• ApplicationUserPrefix – the prefix to apply to the application name the user sees.
• ApplicationAdminPrefix – the prefix to apply to the application name the administrator sees.
• DeliveryGroupPrefix – the prefix to apply to delivery groups.
• GroupPolicyPrefix – the prefix to apply to policy names.
• HostConnectionPrefix – the prefix to apply to host connections.
• MachineCatalogPrefix – the prefix to apply to machine catalogs.
• StoreFrontPrefix – the prefix to apply to StoreFront names.
• TagPrefix – the prefix to apply to tags.
• AdminScopedSuffix – the suffix to apply to administrator scopes.
• ApplicationSuffix - the suffix to apply to applications.
• ApplicationFolderSuffix – the suffix to apply to application folders; ApplicationFolderSuffix can be combined with ApplicationFolderRoot.
• ApplicationGroupSuffix – the suffix for application groups.
• ApplicationUserSuffix – the suffix to apply to the application name the user sees.
• ApplicationAdminSuffix – the suffix to apply to the application name the administrator sees.
• DeliveryGroupSuffix – the suffix to apply to delivery groups.
• GroupPolicySuffix – the suffix to apply to policy names.
• HostConnectionSuffix – the suffix to apply to host connections.
• MachineCatalogSuffix – the suffix to apply to machine catalogs.
• StoreFrontSuffix – the suffix to apply to StoreFront names.
• TagSuffix – the suffix to apply to tags.
• SiteRootFolder – the fully qualified folder name to use for exports and imports; this can be a local folder or a file share.

Component selection parameters

The following components can be specified with cmdlets supporting them. For tool versions including 1.x, follow each parameter with $true. For tool versions 2.x or later, specify the parameter only. Selecting All causes the other parameters to be ignored. The All option is automatically selected when no component parameters are specified.

• All
• Tags
• AdminRolesScopes
• MachineCatalogs
• DeliveryGroups
• ApplicationGroups
• Applications
• GroupPolicies

Filtering by object names

Include and Exclude by name

The IncludeByName and ExcludeByName parameters enable including and excluding component members in cmdlets by name. Only one component (for example, delivery groups) can be chosen at a time in any of the supported cmdlets. If a component member is in both areas, exclude overrides any other parameter and an entry is made in the log fixup list identifying the component and member name that was excluded.

IncludeByName and ExcludeByName take a list of component member names. Any name can contain one or more wildcards. Two types of wildcards are supported. The list of component member names must be enclosed in single-quotes when any member name contains special characters.

• * Matches any number of characters
• ? Matches a single character

IncludeByName and ExcludeByName can also take a file containing a list of members where each member can be explicit or contain wildcards. Each line in the file can contain one member. Leading and trailing spaces are trimmed from the member name. The file name must be preceded by the @ sign and be surrounded by single quotes (a PowerShell requirement so the @ is not reinterpreted). Multiple files can be listed in addition to being mixed with member names.

One example of merging all delivery groups whose names begin with DgSite1 and contain Home2 would be written:

Merge-CvadAcToSite –DeliveryGroups $true –IncludeByName DgSite1*,*Home2*

By Delivery Group Name

ByDeliveryGroupName filters by the delivery group name for applications and application groups. This parameter is always an inclusion list identifying members to include based on their delivery group association.

ByDeliveryGroupName takes a list of delivery group names. Any name can contain one or more wildcards. Two types of wildcards are supported.

• * matches any number of characters
• ? matches a single character

The following example merges all applications that reference all delivery group names beginning with EastDg.

Merge-CvadAcToSite –Applications –ByDeliveryGroupName EastDg*

Exclude Disabled

ExcludeDisabled filters out from import operations all applications and application groups that are disabled. ExcludeDisabled defaults to false, meaning all applications and application groups are imported regardless of their enabled state.

By Machine Name

Note:

This feature is available only on versions 2.0 and later. Check your version by using Get-CvadAcStatus within Automated Configuration.

ByMachineName filters by the machine name for machine catalogs and delivery groups. This parameter is always an inclusion list identifying members to include based on their machine name association.

ByMachineName takes a list of machine names where any name can contain one or more wildcards. Two types of wildcards are supported.

• * matches any number of characters
• ? matches a single character

When exporting or importing and using ByMachineName and a machine name filter results in no machines in the machine catalog or delivery group, the machine catalog or delivery group is excluded from the export or import.

Note:

Use of ByMachineName in any import type cmdlet results in AddMachinesOnly being set to $true.

Add Machines Only

AddMachinesOnly, when set to $true, instructs the import operation to add machines only to the machine catalog or delivery group. Machines are not removed, allowing for incremental additive operations.

AddMachineOnly defaults to false meaning machines are removed if they are not present in the machine catalog or delivery group .yml file. AddMachinesOnly is set to $true when ByMachineName is used but can be overridden by setting AddMachinesOnly to false.

Migration parameters

Cmdlets modifying the cloud site configuration (Import, Restore, Merge, New, and Sync) support the following extra parameters to provide further flexibility.

• CheckMode – Performs the import operation but makes no changes. All expected changes are reported before the import completes. You can use this command to test your import before doing the actual import.
• BackupFirst – Backs up the cloud contents to .yml files before modifying the cloud configuration. This is enabled by default.
• Confirm – When true, prompts users to confirm that they want to make changes to the cloud site configuration. The Remove cmdlet shows a prompt due to its destructive nature. Set to false if no prompt is desired, such as running inside automated scripts. Confirm defaults to true.

Note:

The SecurityFileFolder, SiteName, and SiteActive cmdlets are available only on versions 2.0 and later. Check your version by using Get-CvadAcStatus within Automated Configuration.

• SecurityFileFolder – This is the fully qualified folder containing the CvadSecurity.yml file which might point to a local folder or a network share folder that is under authentication control. The tool does not prompt for credentials; access to the controlled resource must be obtained before running the tool.
• SiteName – Specifies the site merging prefix and suffix set to use when importing. See Merging multiple sites into a single site for more information.
• SiteActive – Specifies whether the imported site is active or inactive. By default, this parameter is set to $false meaning the imported site is inactive.

Cloud-accessing parameters

All cmdlets accessing the cloud support the following extra parameters.

Note:

The CustomerId, ClientId, and Secret can be placed in the CustomerInfo.yml file or specified with the cmdlet using the preceding parameters. When they are specified in both places, the cmdlet parameters take precedence.

• CustomerId – The customer ID used in the Rest APIs and is required to access all Rest APIs. Your customer ID is found in Citrix Cloud.
• ClientId – The clientID created on the Citrix Cloud Identity and Access Management website. This is required to obtain the bearer token needed for authentication for all Rest APIs.
• Secret – The secret key created on the Citrix Cloud Identity and Access Management website. This is required to obtain the bearer token needed for authentication for all Rest APIs.
• CustomerInfoFileSpec – The file specification pointing to a customer information file to override the default location and name.

Log display parameters

The Export, Import, Sync, Restore, Backup, Compare, and Remove cmdlets display the log file when the operation completes. You can suppress the display by setting the -DisplayLog parameter to $false. Notepad.exe is used by default to display the log file. You can specify a different editor in the CustomerInfo.yml file.

Editor: C:\Program Files\Notepad++\notepad++.exe

Derived state results by command

Derived state can result in one of the three combinations of actions on the cloud site:

• Add, Update, and Delete
• Add and Update only
• Add only

The following table shows the derived state for each cmdlet and optional parameters that can change the derived state behavior of the cmdlet.

Cmdlet return values

ActionResult

All cmdlets return the following value.

public class ActionResult
{
    public bool                         Overall_Success;
    public Dictionary<string, string>   Individual_Success;
    public object                       CustomResult;
}

Overall_Success returns a single boolean showing the overall success of the cmdlet across all selected components: true meaning successful and false meaning unsuccessful.

Individual_Success returns one or three values for each main component. A component’s result can be Success, Failure, or Skipped. Skipped indicates the component was not selected for execution by the cmdlet.

CustomResult is cmdlet specific.

CustomResult

Import, Merge, Restore, Sync, Compare, Compare File, and Remove return the following custom result information to a single instance of EvaluationResultData.

Note:

Export and Template cmdlets do not return a custom result.

    public class EvaluationResultData
    {
        public Dictionary<string, Dictionary<string, ActionResultValues >> EvaluationResults;
        public int                  Added;
        public int                  Updated;
        public int                  Deleted;
        public int                  NoChange;
        public int                  TotalChanged;
        public EvaluationResults     OverallResult;
        public string               CloudBackupFolder;
        public string               SourceBackupFolder;
    }
    Where:
    public enum ActionResultValues
    {
        Add,
        Update,
        Delete,
        Identical,
        DoNothing
    }
    public enum EvaluationResults
    {
        Success,
        Failure,
        Skipped
    }

EvaluationResults displays a list with one entry per selected component. The key is the component name and the value is a list of each component member and the action taken on that component member. Actions can be any one of the ActionResultValues values.

Added, Updated, Deleted, and NoChange indicate the total number of component members added, updated, deleted, or no action taken, in that order.

TotalChanged is the sum of Added, Updated, and Deleted.

OverallResult is a single boolean indicating the result of the cmdlet. True indicates total success across all components and false indicates failure in processing one or more components.

CloudBackupFolder is the fully qualified file specification of the cloud site configuration backup before the cmdlet performing any cloud-modifying actions.

SourceBackupFolder is the fully qualified file specification of the source file backup made after completion of the cmdlet. By default, these files are at %HOMEPATH%\Documents\Citrix\AutoConfig.

Help

• Get-Help - PowerShell help is available for each cmdlet. All parameters are documented with each cmdlet along with a brief explanation of the cmdlet. To access help for any cmdlet, type Get-Help in front of the cmdlet. For example, Get-Help Import-CvadAcToSite.

Additional information

• Importing objects with MCS machine catalogs

• Citrix Cloud Government

• Host connections

• Automation

• Exporting from PCs other than the delivery controller

• Citrix Cloud data collection

• Folders

• Backups

• Logging

• Diagnostic files

• Dependency problems

• Common problems

• Recommendations

• Resources

Importing other objects when you have Machine Creation Services machine catalogs

Currently, Automated Configuration does not support importing MCS machine catalogs or their corresponding delivery groups in an automated way. However, you can still import other configuration options such as applications and policies using Automated Configuration. You must create the machine catalog and delivery group using the same name as the on-premises setup. Follow the steps to prepare your environment, before proceeding to import the application settings:

1. In your Citrix Cloud portal, click the hamburger menu and go to My Services > Virtual Apps and Desktops Service > Manage. Create your MCS machine catalog as you normally would. Be sure to name your catalog exactly the same way your existing on-premises catalog is named.

2. Create the corresponding delivery group for the new catalog. Be sure you name it exactly after the corresponding on-premises delivery group.

3. In your on-premises environment’s Citrix Studio, in the Applications node, confirm the applications belong to the matching delivery groups by selecting the application, right-clicking the app, and going to Properties.

4. Click Groups to confirm the groups the app belongs to:

   

5. In PowerShell, run the Merge command and use the byDeliveryGroupName flag, which filters the applications by delivery group name.

   Merge-CvadAcToSite –Applications $true –ByDeliveryGroupName <DG_name>

   

6. Type Yes to continue.

   

7. On your Studio console in Citrix Cloud, go to Applications and refresh to make sure the apps are listed as expected. Select the applications and go to Application Properties > Groups to check.

Importing MCS-related policies

If you need to import policies associated with your MCS catalogs or groups, follow these instructions:

1. Run the Merge-CvadAcToSite -GroupPolicies $true command in PowerShell and type yes to continue.

   

   Successful execution displays a similar output to the preceding screenshot (Added values). The following screenshot shows the result of a line for which there were no changes (No change).

   

2. Refresh the Studio window in Citrix Cloud and click Policies on the left-hand side.

3. Check the Policies Assigned to tab and compare it with your on-premises policy assignment.

Moving to Citrix Cloud Government

The Citrix Cloud Government environment uses different access points to authenticate and allocate access tokens. This unique requirement applies to any Automated Configuration tool accessing the cloud. Perform the following steps to use Automated Configuration in Citrix Cloud Government environments.

1. In the %HOMEPATH%\Documents\Citrix\AutoConfig folder, edit CustomerInfo.yml.

2. Add the following line to CustomerInfo.yml (or change it, if already present.)

   Environment: "ProductionGov"

Automated Configuration is now able to be used on Citrix Cloud Government environments.

Host connections

Host connections and their associated hypervisors can be exported and imported using Automated Configuration.

Adding a hypervisor to a host connection requires security information specific to the type of hypervisor. This information cannot be exported from the on-premises site for security considerations. You must manually provide the information so that Automated Configuration can successfully import host connections and hypervisors to the cloud site.

The export process creates the HostSecurity.yml file in %HOMEPATH%\Documents\Citrix\AutoConfig containing placeholders for each security item needed for the specific hypervisor type. You must update the HostSecurity.yml file before importing into the cloud site. Administrator updates are retained over multiple exports with new security placeholders added as needed. Security items are never removed.

Note:

Be sure to double quote all values entered in the HostSecurity.yml file.

---

HostConn1:
ConnectionType: XenServer
UserName: root
PasswordKey: rootPassword
HostCon2:
ConnectionType: AWS
ApiKey: 78AB6083-EF60-4D26-B2L5-BZ35X00DA5CH
SecretKey: TwBLaaaaaaaaaaaaaaaaaw==
Region: East

Per-hypervisor security information

The following lists the security information required for each hypervisor type.

• XenServer, Hyper-V, VMware
  • User Name
  • Clear-text Password
• Microsoft Azure
  • Subscription ID
  • Application ID
  • Application Secret
• Amazon Web Services
  • Service Account ID
  • Application Secret
  • Region

Special security considerations

All security information is entered as clear text. If clear text is not recommended, the host connections and associated hypervisors can be manually created using Citrix Cloud’s Studio control panel. The host connections and hypervisor names must match to their on-premises counterparts exactly so that machine catalogs that use the host connections to be successfully imported.

Automation

Automated Configuration tool cmdlets can be run in automation scripts without administrator intervention by suppressing prompts and the display of the log results at cmdlet completion. You can also set parameters to do the same by using the CustomerInfo.yml file.

Add the following parameter to cloud modifying cmdlets to suppress the display of prompts.

-Confirm $false

Add the following parameter to cmdlets to suppress the display of log at the completion of the cmdlet.

-DisplayLog $false

Add the following parameter to cmdlets to suppress logging to the PowerShell command window.

-Quiet

As another method, the following parameters can be placed in the CustomerInfo.yml file.

Confirm: False

DisplayLog: False

Exporting from PCs other than the delivery controller

The Automated Configuration tool uses multiple Citrix PowerShell SDKs to export the on-premises site configuration to files. These SDKs are automatically installed on the delivery controller, enabling the tool to run on the delivery controller without extra actions. When running on non-delivery controller machines, it is necessary to install the set of Citrix PowerShell SDKs needed by the tool. This SDK set is part of Citrix Studio which can be installed from the Citrix Virtual Apps and Desktops installation media.

Note:

Automated Configuration cannot be run on the Cloud Connector.

Citrix Cloud data collection

For information on what information Citrix Cloud collects, see Citrix Cloud Services Customer Content and Log Handling.

Folders

Default folder root location

All Automated Configuration tool operations occur in the root folder or in subfolders inside it. The root folder is located in %HOMEPATH%\Documents\Citrix\AutoConfig.

Export

All exported files are placed in two folder locations, providing ease-of-use and a history of exports. Exports are always placed in the root folder. Copies are placed in a subfolder named Export with the date and time of the export.

The root folder always contains the most recent exported on-premises site configuration. Each Export subfolder contains the export done on the indicated date and time, which maintains a history of exports. You can use any Export subfolder to configure the cloud site. Automated Configuration does not delete or modify existing export subfolders.

Import/Merge/Sync/Compare

Import, Merge, and Compare operations always sourced from files located in the root folder. Each operation results in the creation of a subfolder to which files in the root folder are copied, providing a history of cloud site changing source files.

Restore

The Restore operation uses an existing subfolder to configure the cloud site. The source folder is specified on the required -RestoreFolder parameter. Unlike with other commands, no new subfolder is created because the Restore operation uses an existing subfolder. The restore folder can be the root folder but still must be specified on the -RestoreFolder parameter.

Backups

Automated Configuration initializes, updates, and backs up a cloud site configuration. When used over time, many different configurations can change on the cloud site. To facilitate long-term use and preserve history changes, Automated Configuration uses a preservation scheme to save this history of changes and provide a method to restore earlier states.

Cloud site configuration backups are always made to a subfolder named Backup with the data and time of the backup. Automated Configuration does not delete or modify existing export subfolders.

You can use the backups to restore specific components or your entire configuration. To restore the entire delivery group and machine catalog components, use the cmdlet:

Restore-CvadAcToSite -RestoreFrom %HOMEPATH%\Documents\Citrix\AutoConfig/Backup_yyyy_mm_dd_hh_mm_ss -DeliveryGroups -MachineCatalogs

Note:

The backup file information in the preceding cmdlet is based on your own backups.

To restore the entire cloud site configuration, use the cmdlet:

Restore-CvadAcToSite -RestoreFrom %HOMEPATH%\Documents\Citrix\AutoConfig/Backup_yyyy_mm_dd_hh_mm_ss

Note:

The backup file information in the preceding cmdlet is based on your own backups.

Changing the default root folder

The Export, Import, Merge, Sync, and Compare operations can change the default root folder by using the –AlternateFolder parameter. The creation and management of per-operation subfolders remains the same as previously described.

Files copied to subfolders

All files having an “.yml” extension are copied to operation subfolders except for the following:

• CustomerInfo.yml
• ZoneMapping.yml
• HostSecurity.yml

Automated fail-safe cloud site backups

A backup of the current cloud site configuration is made before running operations that change the configuration. This includes Import, Merge, Sync, and Restore parameters. The backup is always in a subfolder beneath the operational subfolder.

In the case of Restore, the backup folder is a subfolder of the folder specified on the -RestoreFrom parameter.

Logging

Running any cmdlet results in a created log file and an entry in the main history log file. 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.

The main history log is located in %HOMEPATH%\Documents\Citrix\AutoConfig, in the file named History.Log. Each cmdlet execution results in a main log entry containing the date, operation, result, backup, and log file locations of the execution.

Logging details

Each log file includes the following:

• The name of the operation and whether check mode is enabled
• The start and end date and time
• Multiple entries for each component’s actions and success/failure notifications
• Summary of actions taken including various counts of created objects
• Suggested fixes where applicable
• Backup folder location where applicable
• Main log location
• Duration

Diagnostic files

Diagnostic files assist you in determining and resolving problems. The following files are created when their operation is run. They are located in the action-specific subfolder under %HOMEPATH%\Documents\Citrix\AutoConfig. Include these files when providing information for problem resolution support.

Export

PoshSdk_yyyy_mm_dd_hh_mm_ss.ps1

This file enumerates all Broker PowerShell SDK calls made to export the site configuration to files.

Import, Merge, Restore, Sync, Backup, Compare

Transaction_yyyy_mm_dd_hh_mm_ss.txt

This file documents each Rest API call and related information.

RestApiContent_yyyy_mm_dd_hh_mm_ss.txt

This file contains the all Add, Update, and Delete Rest API content.

Problems resulting from dependencies

Imports and merges might fail due to missing dependencies. Some common problems are:

1. Group Policies are missing delivery group filters. The usual causes are delivery groups that have not been imported.
2. Applications fail to import or merge. The usual cause is missing delivery groups or application groups that have not been imported.
3. Application groups are missing a RestrictToTag. The usual causes are tags that have not been imported.
4. Host connections fail. The usual cause is missing security information in the CvadAcSecurity.yml file.
5. Machine catalogs fail. The usual cause is host connections that were not imported.
6. Machines missing from machine catalogs and delivery groups. The usual cause is machines that were not found in Active Directory.
7. Users missing from delivery groups. The usual cause is users that were not found in Active Directory.

Common problems

The cloud site is empty

An empty site indicates that a successful import/merge/restore operation has not completed. If an operation was attempted, review the logs from the operation.

The cloud site has more items than expected

This can happen if enhancements were made to the cloud site configuration and a Merge operation was run. It can also happen if the cloud site configuration had previous values and an import/merge/restore operation had issues. Try rerunning the operation.

The cloud site has fewer items than expected

This can happen if enhancements were made to the cloud site configuration and an Import operation with the Merge parameter set to $false, resulting in an identical derived state. The original state is backed up in the Automated Fail-Safe Cloud Site Backup folder associated with the import operation. To correct:

1. Restore the Automated Fail-Safe Cloud Site Backup using the Restore operation setting the RestoreFolder parameter to the Automated Fail-Safe Cloud Site Backup folder.

2. Use the Merge operation instead of the Import operation.

Cloud site edits after import have been lost

This can occur if an Import operation was done with the –Merge parameter set to $false, resulting in an identical derived state import. The original state is backed up in the Automated Fail-Safe Cloud Site Backup folder associated with the import operation. To correct:

1. Restore the Automated Fail-Safe Cloud Site Backup using the Restore operation setting the RestoreFolder parameter to the Automated Fail-Safe Cloud Site Backup folder.

2. Use the Merge operation instead of the Import operation.

The cloud site does not match the current on-premises site

This can occur when a Merge operation was done resulting in a merged derived state instead of an Import with the Merge parameter set to $false resulting in an identical derived state. Repeat using Import with the Merge parameter set to $false.

Recommendations

• Do not run more than one instance of Automated Configuration at a time. Running multiple concurrent instances produces unpredictable results in the cloud site. If this occurs, rerun one instance of Automated Configuration to bring the site to the expected state.
• Do not work in Web Studio or Full Configuration while running Automated Configuration. Making changes in Web Studio or Full Configuration while running Automated Configuration can produce unpredictable results in the cloud site. If this occurs, rerun one instance of Automated Configuration to bring the site to the expected state.
• Always visually verify the merge/import/restore results in Web Studio or Full Configuration to ensure the cloud site meets expectations.

Resources

• For more detailed and up-to-date troubleshooting and support information, see Knowledge Center article CTX277730.

• For more information on Automated Configuration, see Proof of Concept: Automated Configuration Tool.

• Visit the Citrix Discussion forum for Automated Configuration.

• Watch Under the Hood of the Automated Configuration Tool for Citrix Virtual Apps and Desktops on YouTube.