Migrate a deployment to the cloud

If you have a Citrix Virtual Apps and Desktops on-premises deployment, you can now migrate all or part of your configuration onto Citrix Virtual Apps and Desktop Service.

Citrix Automated Configuration tool (preview)

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

The tool exports your on-premises 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.

Prerequisites for migrating your configuration

  • Download and install the Citrix Automated Configuration tool.
  • 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 DDC 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 DDC. (To run on machine other than the on-premises DDC, the machine must be domain joined and Citrix Studio must be installed, as it installs the correct PowerShell snap-ins. The Citrix 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.

Known limitations

  • Host connections are not fully supported. Host connection support must be enabled using a parameter in the CustomerInfo.yml file. For more information, see Host connections.
  • Machine catalogs provisioned through Machine Creation Services are not currently supported.
  • File type associations are not imported unless there is a soft- or hard-registered VDA.
  • Icons are not applied to machines or desktops.

Supported objects for migration

The following components are supported by the Citrix Automated Configuration tool and 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

Exporting your Citrix Virtual Apps and Desktops on-premises configuration

  1. Install the Citrix Automated Configuration tool.
  2. Click the Auto Config icon. A PowerShell window appears.
  3. Run the following command to do a baseline export.

Export-CvadAcToFile –All $true

Note:

Other available commands are described here.

After running 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 Logs.

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 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 Zone mapping file.
  • If you have a Provisioning Service catalog or host connections, you must input the corresponding info in the HostSecurity.yml and CvadAcSecurity.yml.

Running a baseline import

  1. Click the Auto Config icon. A PowerShell window appears.
  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 running 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 Logs.

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. The Citrix Automated Configuration tool 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.

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.

    customer ID image 1

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

    customer ID image 2

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

    customer ID image 3

  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.

    customer ID image 4

  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.

    customer ID image 5

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

    customer ID image 6

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.

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.

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

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.

Citrix Automated Configuration tool cmdlets

Site management cmdlets

  • Export-CvadAcToFile - Exports configuration from your on-premises setup. This is the default export operation for the Citrix Automated Configuration tool.
  • 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 the Citrix Automated Configuration tool.
  • 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. Use with caution.
  • 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 - Exports and imports in one step.
  • 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.
  • 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.
  • 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.

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.

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. Note: 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 DDC to export from. The appropriate Citrix PowerShell SDKs must be installed on the machine running the Citrix Automated Configuration tool as explained in Prerequisites for migrating your configuration. Host connections cannot be exported when the tool is run on a non-DDC 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 fixup 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, 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. For more information, see Generating the customer ID, client ID, and secret key.
  • 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. For more information, see Generating the customer ID, client ID, and secret key.
  • 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. For more information, see Generating the customer ID, client ID, and secret key.
  • CustomerInfoFileSpec – The file specification pointing to a customer information file to override the default location and name.

Support/troubleshooting cmdlets

  • Find-CvadAcConnector - Locates existing connectors and determines their running state. This cmdlet uses information from the customer info .yml file or the Customer ID parameter to locate the customer’s connectors.
  • 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 customer info .yml file to specify the customer connection information.
  • Initialize-CvadAcToSite - Resets the cloud site to its default state. Use with caution.
  • Get-CvadAcCustomerSites - Returns the list of all the customer sites. This cmdlet uses the cloud accessing parameters or the customer info .yml file to specify the customer connection information.
  • New-CvadAcTemplateToFile – Creates a template file for selected components, allowing you to manually create an import file.
  • Get-CvadAcStatus - Get Status returns the following information about the tool and the environment it is running in, including the tool version, whether the user has Site Admin 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.

Command Add, Update, Delete Add, Update Add
Import -Merge $false Default -AddOnly $true
Merge N/A Default -AddOnly $true
New N/A N/A Default
Sync -Merge $false Default -AddOnly $true
Restore -Merge $false Default -AddOnly $true

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

The Citrix Automated Configuration tool 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, the tool uses a preservation scheme to save this history of changes and provide a method to restore earlier states.

Folders

Default folder root location

All Citrix 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. The Citrix Automated Configuration tool 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. The Citrix Automated Configuration tool 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. The Citrix Automated Configuration tool 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.

Other information

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 Full Configuration 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 the tool but this capability must be manually enabled and then special security considerations must be taken.

To enable Host Connection export/import, add the following line to the CustomerInfo.yml file:

HostConnections: True

Note:

Be sure there is a space between the colon and True.

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 the Citrix Automated Configuration tool 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. The host connections and associated hypervisors can be manually created using the Cloud’s Full Configuration 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.

PVS Machine Catalog Support

The Citrix Automated Configuration tool provides support for PVS Machine Catalogs but requires extra security information to allow the cloud to contact the PVS server. An entry is made in the CvadAcSecurity.yml file for each PVS server found in the exported Machine Catalogs.

Each PVS server entry contains the Connection Type set to PVS, PVS server User Name with the domain prefix and Password all in clear text. Existing PVS server entries are not overlaid or removed during successive exports.

---
Pvs1Server:
ConnectionType: PVS
UserName: xd1\administrator
Password: adminPassword

Note:

The Service Account running the tool needs to be both Full Admin on the Site and Admin on PVS for it to work.

Automation

The Citrix 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 DDC

The Citrix Automated Configuration tool uses multiple Citrix PowerShell SDKs to export the on-premises site configuration to files. These SDKs are automatically installed on the DDC, enabling the tool to run on the DDC without extra actions. When running on non-DDC 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-DDC machine.

The Citrix Automated Configuration tool cannot be run on the Cloud Connector.

Troubleshooting and recommendations

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 the Citrix Automated Configuration tool at a time. Running multiple concurrent instances produces unpredictable results in the Cloud site. If this occurs, rerun one instance of the Citrix Automated Configuration tool to bring the site to the expected state.
  • Do not work in Web Studio or Full Configuration while running the Citrix Automated Configuration tool. Making changes in Web Studio or Full Configuration while running the tool can produce unpredictable results in the Cloud site. If this occurs, rerun one instance of the Citrix Automated Configuration tool 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.