Migration and management

If you have a Citrix Virtual Apps and Desktops Service configuration and you want to move it to another Citrix Virtual Apps and Desktops Service deployment 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.

Automated Configuration for Citrix Virtual Apps and Desktops

Automated Configuration for Citrix Virtual Apps and Desktops is a tool that allows you to automate moving your on-premises configuration to your Citrix Virtual Apps and Desktops Service deployment.

Automated Configuration also supports moving your configuration between Citrix Virtual Apps and Desktops Service deployments. You can also use Automated Configuration to manage your deployments.

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.

Download Automated Configuration

Download the Automated Configuration tool from Citrix Downloads. For more information, see Proof of Concept: Automated Configuration Tool.

Prerequisites for migrating your configuration

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.
• Citrix Virtual Apps and Desktops Service provisioned with an active resource location with Connector installed and domain-joined to the same domain as on-premises setup.
• Sites accessing Citrix Cloud must be allowed. For more information, see System and Connectivity Requirements.

Supported objects for migration

Automated Configuration supports the following components and are moved as part of the automated process.

• Tags
• 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 Scopes
  • Application Access Policy
  • Assignment Policy
  • Entitlement/Desktop Policy
  • Power Schedules
  • Session Lingering
  • Session Prelaunch
  • Reboot Schedules
  • Tags
• Application Groups
  • Admin Scopes
• Applications
  • Application Folders
  • Icons
  • Applications
  • Broker Configured FTAs
  • Tags
• Group Policies

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.
• Access Control must be added manually using the Remote POSH SDK.
• Delegated administration. Associating administrator scopes is supported.

Migrating from on-premises to cloud

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

Exporting your Citrix Virtual Apps and Desktops on-premises configuration

1. Install Automated Configuration on your delivery controller.
2. Open PowerShell as an administrator.

3. Run the following command to do a baseline export.

   Export-CvadAcToFile –All $true

Note:

Other available commands are described here.

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. For more information about logs and the information provided in them, see Logging.

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 a Citrix Provisioning catalog or host connections, you must input the corresponding info in the HostSecurity.yml and CvadAcSecurity.yml.

Running a baseline import

1. Run PowerShell as an administrator.

2. Run the following command to do a baseline import.

   Merge-CvadAcToSite -All $true

Note:

Other available commands are described here.

Verify the expected state with the new current state. When doing a Merge import, the expected state must be a subset of the new current state for the import to succeed.

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. For more information about logs and the information provided in them, see Logging.

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

Import order and component dependency

The following components are selectable in the Export, Import, Merge, New, Sync, and Restore commands. They are listed in their import order. Importing out of order might result in dependency failures and cause the import operation to fail.

1. Tags
2. Host Connections
3. Machine Catalogs
4. Delivery Groups
5. Application Groups
6. Applications
7. 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 for 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. Host Connections
   • Security Information in CvadAcSecurity.yml
3. Machine Catalogs
   • Machines present in Active Directory
   • Host Connections
   • Tags
4. Delivery Groups
   • Machines present in Active Directory
   • Users present in Active Directory
   • Machine Catalogs
   • Tags
5. Application Groups
   • Delivery Groups
   • Tags
6. Applications
   • Delivery Groups
   • Application Groups
   • Tags
7. Group Policies
   • Delivery Groups
   • Tags

Populating customer info file

Use of the CustomerInfo.yml file eliminates the need to add customer information as cmdlet parameters. Any of the customer information can be overridden by using cmdlet parameters.

The CustomerInfo.yml file can be created by using the New-CvadAcCustomerInfoFile cmdlet. New-CvadAcCustomerInfoFile has the following 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==

You can update the CustomerInfo.yml file by using the Set-CvadAcCustomerInfoFile cmdlet.

Note:

The cmdlet only changes the Customer ID, Client ID, or Secret key.

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

Generating the customer ID, client ID, and secret key

The following steps allow you to create the client ID and secret key that are required to import your configuration to Citrix Cloud.

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. On the Identity and Access Management page, click the API Access tab.

   

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

   

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

   

6. 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 zone mapping file

The on-premises zone is the equivalent of the cloud resource location. Unlike other site components, you cannot import the on-premises zone to a cloud resource location automatically. It must be mapped using the ZoneMapping.yml file. Import failures can occur if the zone name does not match an existing resource location name.

The ZoneMapping.yml file is manually created after exporting your on-premises configuration but before importing to the cloud and must reside 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.

The following is an example:

---

Primary: "My Primary Resource Location"
Zone2: "Second Resource Location"

Note:

A space must be between the colon and resource location name.

If the ZoneMapping.yml file is not found or the correct mapping is not present, and the cloud site has only one zone, that zone is automatically used to map to all on-premises zones.

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 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 a Citrix Provisioning catalog or host connections, you must input the corresponding info in the HostSecurity.yml and CvadAcSecurity.yml.

1. Install Automated Configuration.
2. Run PowerShell as an administrator.

3. Run the following command to do a baseline backup.

   Backup-CvadAcToFile –All $true

Note:

Other available commands are described here.

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. For more information about logs and the information provided in them, see Logging.

Restoring your configuration to Citrix Virtual Apps and Desktops Service

Note:

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 baseline restore

1. Run PowerShell as an administrator.

2. Run the following command to do a baseline restore.

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

Note:

Other available commands are described here.

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. For more information about logs and the information provided in them, see Logging.

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

Automated Configuration tool cmdlets

• Site management cmdlets

• Granular migration cmdlet parameters

• Filtering by object names

• Migration mode parameters

• Cloud-accessing parameters

• Support and troubleshooting cmdlets

• 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.
• 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.
• 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.
• 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.
• 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.
• Sync-CvadAcToSite - Sync performs both an export and import in one step.
• Backup-CvadAcToFile - Exports your cloud configuration to .yml files. This backup can be used for reverting to a previous configuration or for disaster recovery.
• 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.
• 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.

Granular migration cmdlet parameters

All cmdlets ending in ToSite, ToFile, and FromSite allow selection of one or more components to act upon. These parameters give you further granularity to migrate only selective components. Make a selection by using one or more of the following true/false options.

Note:

Selecting All causes the other parameters to be ignored. The All option is automatically selected when no components are selected.

• All
• Tags
• MachineCatalogs
• DeliveryGroups
• ApplicationGroups
• Applications
• GroupPolicies
• IncludeByName and ExcludeByName - See the following for more information on these parameters.

Filtering by object names

Include and Exclude

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.

Cmdlets supported including and excluding are:

• Export-CvadAcToFile
• Import-CvadAcToSite
• Merge-CvadAcToSite
• New-CvadAcToSite
• Restore-CvadAcToSite
• Sync-CvadAcSiteToSite
• Compare-CvadAcToSite
• Remove-CvadAcFromSite

IncludeByName and ExcludeByName take a list of component member names. Any name can contain one or more wildcards. Two types of wildcards are supported.

• Matches any number of characters
• Matches a single character

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*

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.

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. Cmdlets supported ByDeliveryGroupName:

• Export-CvadAcToFile
• Import-CvadAcToSite
• Merge-CvadAcToSite
• New-CvadAcToSite
• Restore-CvadAcToSite
• Sync-CvadAcSiteToSite
• Compare-CvadAcToSite

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 $true –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.

Migration modes 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 it occurs.
• Merge – Merges the file data to the cloud but does not delete any components. This option is enabled by default in the Merge cmdlet but is optional in Import and Sync.
• AddOnly – Only adds components, does not update or delete existing components. AddOnly is optional on all cmdlets except New, where it is enabled by default.
• 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.
• AdminAddress - Supported for export cmdlets, allowing to target any delivery controller to export from. The appropriate Citrix PowerShell SDKs must be installed on the machine running Automated Configuration as explained in Prerequisites for migrating your configuration. Host connections cannot be exported when the tool is run on a non-delivery controller machine.
• CheckAllMachines – Checks that all machines in machine catalogs are present in Active Directory. If a machine is not present then it is removed from the machine catalog and a note about the removal is added to the Fixups list in the log file. This has the benefit of avoiding machine catalog add failures due to non-present machines. CheckAllMachines defaults to true.

Cloud-accessing parameters

All cmdlets accessing the cloud, which are cmdlets ending with ToSite or FromSite and Get-CvadAcStatus, support the following extra parameters.

Note:

These parameters are not needed if they are added into the CustomerInfo.yml file.

• 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.
• SiteActive – Determines whether the cloud site is passive or active. The cloud site is passive when set to False and active when set to True. SiteActive defaults to False, setting the cloud site to passive.

Support and troubleshooting cmdlets

• New-CvadAcCustomerInfoFile - Creates a CustomerInfo.yml file which includes the CustomerId, ClientId, and Secret parameters.
• Set-CvadAcCustomerInfoFile - Allows you to edit the CustomerId, ClientId, and Secret parameters in a CustomerInfo.yml file.
• New-CvadAcTemplateToFile – Creates a template file for selected components, allowing you to manually create an import file.
• 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.
• 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.
• 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.
• Get-CvadAcStatus - Get Status 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, and whether one or more connectors are present.

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

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.

Get-Help Import-CvadAcToSite

Folders, backups, and logging

• Folders

• Backup

• Logging

• Diagnostic files

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.

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.

Any subfolder can be used to configure the cloud site. Automated Configuration does not delete or modify existing export subfolders.

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.

Backup

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 $true -MachineCatalogs $true

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 master 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 master history log is located in %HOMEPATH%\Documents\Citrix\AutoConfig, in the file named History.Log. Each cmdlet execution results in a master 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
• Master 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.

Additional information

• Importing objects with MCS machine catalogs

• Citrix Cloud Government

• Administrator scopes

• Host connections

• Automation

• Exporting from PCs other than the delivery controller

• Citrix Cloud data collection

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.

Administrator scopes

The export and import processes support administrator scopes. However, the import process can only associate the scope, not create it. Follow these steps to successfully export and import administrator scopes to the cloud site.

1. Export the on-premises site.
2. In the on-premises Citrix Studio, navigate to the Configuration > Adminstrators > Scopes tab and take note of all scopes that are present. There is no need to note their associations as these are created when the components are imported.
3. In the Citrix Cloud console, navigate to the Configuration > Adminstrators > Scopes tab and manually create each scope recorded from the previous step.
4. Import, Merge, Restore, New, or Sync the export from Step 1.
5. The manually created scopes are associated with the correct components.

If the administrator scopes are not manually created first, the import operation removes the scopes from the components. After the scopes are manually created, rerunning the import operation associates the scopes with the components.

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.

---

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 admin 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

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 Desktop installation media.

Note:

Host connections cannot be exported from a non-delivery controller machine.

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.

Troubleshooting and recommendations

• Dependency problems

• Common problems

• Recommendations

• More information

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

For quick troubleshooting, review the log file, specifically the Fixups section.

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.

More information

• Visit the Citrix Discussion forum for Automated Configuration.

• Watch Under the Hood of the Automated Configuration Tool for CVAD on YouTube.