Citrix Virtual Apps and Desktops

Automated configuration tool cmdlets for migration

December 24, 2024

Contributed by:

This page lists all the cmdlets and parameters supported by the tool for migration usecases.

All cmdlets take parameters having one of the following types.

String
List of strings
Boolean: $true or $false
SwitchParameter: presence of the parameter means $true; absence of the parameter means $false

Note:

SwitchParameter is the preferred method for true or false selections but booleans are still used in the tool due to legacy issues.

The following table is a summary of all cmdlets. See each individual section to find what parameters each cmdlet supports.

Category	Cmdlet	Description
On-premises to cloud migration	`Export-CvadAcToFile`	Export on-premises files to YAML files.
	`Import-CvadAcToSite`	Import YAML files to the cloud. Supports create, update, and delete operations.
	`Merge-CvadAcToSite`	Import YAML files to the cloud. Supports create and update operations.
	`New-CvadAcToSite`	Import YAML files to the cloud. Supports create and update operations.
	`Sync-CvadAcToSite`	Export and import in one step.
	Granular migration For components, use parameters with commands above. Examples: `MachineCatalogs`, `Tags`. For component names, use parameters with commands above. Examples: `IncludeByName`, `ExcludeByName`.	Selectively migrate only components or component names
Cloud to cloud cmdlets	`Backup-CvadAcToFile`	Backs up all the configuration from your cloud site.
	`Restore-CvadAcToSite`	Restores backup YAML files to the cloud site. This cloud site can be the same or different than the source cloud site.
	`Remove-CvadAcFromSite`	Remove component members from cloud.
	Granular migration For components, use parameters with commands above. Examples: `MachineCatalogs`, `Tags`. For component names, use parameters with commands above. Examples: `IncludeByName`, `ExcludeByName`.	Selectively migrate only components or component names
Other basic cmdlets	`Compare-CvadAcToSite`	Compares the on-premises .yml files with the cloud configuration.
Prerequisites-related cmdlets	`New-CvadAcCustomerInfoFile`	Create a customer info file.
Prerequisites-related cmdlets	`Set-CvadAcCustomerInfoFile`	Update an existing customer info file.
Support and troubleshooting cmdlets	`New-CvadAcZipInfoForSupport`	Zips all log and .yml files in a single zip file to send to Citrix for support.
	`Get-CvadAcStatus`	Use to test connectivity and to ensure that all prerequisites are met. Returns information about the tool like version number and connectivity with the cloud and connector status.
	`Test-CvadAcConnectionWithSite`	Test the connection with the cloud site.
	`Find-CvadAcConnector`	Locates existing connectors and determines their running state.
	`Get-CvadAcCustomerSites`	Returns the list of all the customer sites.
	`New-CvadAcTemplateToFile`	Creates a template file for selected components.
	`Show-CvadAcDocument`	Displays this documentation in the default browser.
	`Find-CvadAcInFile`	Find in file searches component YAML files looking for members matching one or more names that may contain wildcards.
Site activation cmdlets	`Set-CvadAcSiteActiveStateOnPrem`	Sets the on-premises site state to either active or inactive.
Site activation cmdlets	`Set-CvadAcSiteActiveStateCloud`	Sets the cloud site state to either active or inactive.
Merging multiple on-premises sites cmdlets	`New-CvadAcSiteMergingInfo`	Creates a site merging prefix/suffix info set.
	`Set-CvadAcSiteMergingInfo`	Updates an existing site merging prefix/suffix info set.
	`Remove-CvadAcSiteMergingInfo`	Removes an existing site merging prefix/suffix info set.

For more information on parameters and how to use them, see Granular migration parameters.

Basic cmdlets

On-premises to cloud cmdlets

Export-CvadAcToFile - Export on-premises files to YAML files.

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:

Name	Description	Type
Migrate by components	See Migrate by components	SwitchParameters
Filtering by object names	See Filtering by object names	List of strings
`TargetFolder`	Specifies the export destination folder.	String
`Locale`	Specifies the language of human-readable text that can be exported.	String
`Quiet`	Suppress logging to the console.	SwitchParameter
`AdminAddress`	Specifies the Delivery Controller’s DNS or IP address when the export is not being run on the Delivery Controller.	String
`CheckUserAndMachines`	Verifies if users and machines are in Active Directory. Users and machines that are not in Active Directory might result in import failures.	`$true` or `$false`
`ZipResults`	Zips backup up YAML files into a single zip file. The file is in the same folder as the backed up YAML files and has the same name as the folder.	SwitchParameter

Returns:

See Cmdlet return values

There are three ways of importing data into the cloud. Running specific cmdlets can result in one of the three combinations of actions on the cloud site:

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

Cmdlet	Add	Update	Delete
Import	X	X	X
Merge	X	X
New	X

Import-CvadAcToSite - Import YAML files to the cloud. Supports create, update and delete operations.

Imports all the on-premises files to the cloud. This command ensures that 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:

Name	Description	Type
Migrate by components	See Migrate by components.	SwitchParameters
Filtering by object names	See Filtering by object names.	List of strings
Cloud-accessing parameters	See Cloud-accessing parameters.	SwitchParameters
`SourceFolder`	Identifies a substitute root folder for %HOMEPATH%\Documents\Citrix\AutoConfig.	String
`Locale`	Specifies the language of human-readable text that can be exported.	String
`Quiet`	Suppress logging to the console.	SwitchParameter
`DisplayLog`	Displays the log file at the completion of the cmdlet. Set to `$false` to suppress the log display.	`$true` or `$false`
`Merge`	When set to `$true`, only adds components to the cloud site. Components are not removed. Set to `$false` to remove components.	`$true` or `$false`
`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`.	`$true` or `$false`
`MergePolicies`	Merge policy settings and filters. Merging occurs only when a policy being imported already exists in the cloud DDC. The result of merging policies is that the cloud DDC policies contain the settings and filters it already had in addition to any new settings and filters being imported. Note that when setting and filter collisions occur, the imported values take precedence.	SwitchParameter
`OnErrorAction`	See OnErrorAction parameter.	String

Returns:

See Cmdlet return values

Merge-CvadAcToSite - Import YAML files to the cloud. Supports create and update operations.

Merges the on-premises files to the cloud, but does not delete any components in the cloud or the on-premises site. 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:

Name	Description	Type
Migrate by components	See Migrate by components.	SwitchParameters
Filtering by object names	See Filtering by object names.	List of strings
Cloud-accessing parameters	See Cloud-accessing parameters.	SwitchParameters
`SourceFolder`	Identifies a substitute root folder for %HOMEPATH%\Documents\Citrix\AutoConfig.	String
`Locale`	Specifies the language of human-readable text that can be exported.	String
`Quiet`	Suppress logging to the console.	SwitchParameter
`DisplayLog`	Displays the log file at the completion of the cmdlet. Set to `$false` to suppress the log display.	`$true` or `$false`
`Merge`	When set to `$true`, only adds components to the cloud site. Components are not removed. Set to `$false` to remove components.	`$true` or `$false`
`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`.	`$true` or `$false`
`MergePolicies`	Merge policy settings and filters. Merging occurs only when a policy being imported already exists in the cloud DDC. The result of merging policies is that the cloud DDC policies contain the settings and filters it already had in addition to any new settings and filters being imported. Note that when setting and filter collisions occur, the imported values take precedence.	SwitchParameter
`OnErrorAction`	See OnErrorAction parameter.	String

Returns:

See Cmdlet return values

New-CvadAcToSite - Import YAML files to the cloud. Supports create and update operations.

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:

Name	Description	Type
Migrate by components	See Migrate by components.	SwitchParameters
Filtering by object names	See Filtering by object names.	List of strings
Cloud-accessing parameters	See Cloud-accessing parameters.	SwitchParameters
`SourceFolder`	Identifies a substitute root folder for %HOMEPATH%\Documents\Citrix\AutoConfig.	String
`Locale`	Specifies the language of human-readable text that can be exported.	String
`Quiet`	Suppress logging to the console.	SwitchParameter
`DisplayLog`	Displays the log file at the completion of the cmdlet. Set to `$false` to suppress the log display.	`$true` or `$false`
`OnErrorAction`	See OnErrorAction parameter.	String

Returns:

See Cmdlet return values

Sync-CvadAcToSite - Export and import in one step.

Sync performs both an export and import in one step. Use the SourceTargetFolder parameter to specify the export/import destination folder.

Parameters:

Name	Description	Type
Migrate by components	See Migrate by components	SwitchParameters
Filtering by object names	See Filtering by object names	List of strings
Cloud-accessing parameters	See Cloud-accessing parameters	SwitchParameters
`SourceTargetFolder`	Specifies the export/import destination folder.	String
`Locale`	Specifies the language of human-readable text that can be exported.	String
`AdminAddress`	Specifies the delivery controller’s DNS or IP address when the export is not being executed on the delivery controller.	String
`Quiet`	Suppress logging to the console.	SwitchParameter
`DisplayLog`	Displays the log file at the completion of the cmdlet. Set to `$false` to suppress the log display.	`$true` or `$false`
`Merge`	When set to `$true`, only adds components to the cloud site. Components are not removed. Set to `$false` to remove components.	`$true` or `$false`
`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`.	`$true` or `$false`
`MergePolicies`	Merge policy settings and filters. Merging occurs only when a policy being imported already exists in the cloud DDC. The result of merging policies is that the cloud DDC policies contain the settings and filters it already had in addition to any new settings and filters being imported. Note that when setting and filter collisions occur, the imported values take precedence.	SwitchParameter

Returns:

See Cmdlet return values

Cloud to cloud cmdlets

Backup-CvadAcToFile - Backs up all the configuration from your cloud site.

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

Parameters:

Name	Description	Type
Migrate by components	See Migrate by components	SwitchParameters
Cloud-accessing parameters	See Cloud-accessing parameters	SwitchParameters
`TargetFolder`	Specifies the export destination folder.	String
`Locale`	Specifies the language of human-readable text that can be exported.	String
`Quiet`	Suppress logging to the console.	SwitchParameter
`DisplayLog`	Displays the log file at the completion of the cmdlet. Set to `$false` to suppress the log display.	`$true` or `$false`
`ZipResults`	Zips backup up YAML files into a single zip file. The file is in the same folder as the backed up YAML files and has the same name as the folder.	SwitchParameter

Returns:

See Cmdlet return values

Restore-CvadAcToSite - Restores backup YAML files to the cloud site. This cloud site can be the same or different than the source cloud site.

Restores the cloud site to the previous configuration. Imported files are sourced from the folder specified using the -RestoreFolder parameter, which identifies the folder containing the .yml files to restore to the cloud site. This must be a fully qualified folder specification. This cmdlet can be used for reverting to your previous configuration or for backing up and restoring your cloud site. This command can add, delete, and update your cloud site.

Parameters:

Name	Description	Type
Migrate by components	See Migrate by components.	SwitchParameters
Filtering by object names	See Filtering by object names.	List of strings
Cloud-accessing parameters	See Cloud-accessing parameters.	SwitchParameters
`RestoreFolder`	Identifies the folder containing the .yml files to restore to the cloud site. This must be a fully qualified folder specification.	String
`Locale`	Specifies the language of human-readable text that can be exported.	String
`Quiet`	Suppress logging to the console.	SwitchParameter
`DisplayLog`	Displays the log file at the completion of the cmdlet. Set to `$false` to suppress the log display.	`$true` or `$false`
`Merge`	When set to `$true`, only adds components to the cloud site. Components are not removed. Set to `$false` to remove components.	`$true` or `$false`
`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`.	`$true` or `$false`
`MergePolicies`	Merge policy settings and filters. Merging occurs only when a policy being imported already exists in the cloud DDC. The result of merging policies is that the cloud DDC policies contain the settings and filters it already had in addition to any new settings and filters being imported. Note that when setting and filter collisions occur, the imported values take precedence.	SwitchParameter
`OnErrorAction`	See OnErrorAction parameter.	String

Returns:

See Cmdlet return values

Remove-CvadAcFromSite – Remove component members from cloud.

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:

Name	Description	Type
Migrate by components	See Migrate by components	SwitchParameters
Filtering by object names	See Filtering by object names	List of strings
Cloud-accessing parameters	See Cloud-accessing parameters	SwitchParameters
`Quiet`	Suppress logging to the console.	SwitchParameter
`DisplayLog`	Displays the log file at the completion of the cmdlet. Set to `$false` to suppress the log display.	`$true` or `$false`

Returns:

See Cmdlet return values

Other basic cmdlets

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:

Name	Description	Type
Migrate by components	See Migrate by components.	SwitchParameters
Filtering by object names	See Filtering by object names.	List of strings
Cloud-accessing parameters	See Cloud-accessing parameters.	SwitchParameters
`SourceFolder`	Identifies a substitute root folder for %HOMEPATH%\Documents\Citrix\AutoConfig.	String
`Locale`	Specifies the language of human-readable text that can be exported.	String
`Quiet`	Suppress logging to the console.	SwitchParameter
`DisplayLog`	Displays the log file at the completion of the cmdlet. Set to `$false` to suppress the log display.	`$true` or `$false`
`Merge`	When set to `$true`, only adds components to the cloud site. Components are not removed. Set to `$false` to remove components.	`$true` or `$false`
`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`.	`$true` or `$false`
`OnErrorAction`	See OnErrorAction parameter.	String

Returns:

See Cmdlet return values

Granular migration parameters

Migrate by components

The following components can be specified with cmdlets supporting them. The All option is automatically selected when no component parameters are specified. To avoid errors, we recommend that you migrate components in the following order:

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

Filtering by object names

Migrate by component names

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

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 MergeMachines being set to $true.

Merge Machines

MergeMachines, 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.

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

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

Parameters:

Name	Description	Required?	Type
`CustomerId`	Customer’s ID.	x	String
`ClientId`	Customer’s client ID created on Citrix Cloud. The CustomerId and Secret must be specified when using this parameter.	Conditionally	String
`Secret`	Customer’s secret key created on Citrix Cloud. The CustomerId and ClientId must be specified when using this parameter.	Conditionally	String
`Environment`	Production, ProductionGov, or ProductionJP environment.		Enumeration
`LogFileName`	Change the log file prefix from CitrixLog to something else.		String
`AltRootUrl`	Use only under the direction of Citrix.		String
`StopOnError`	Stops the operation upon first error.		`$true` or `$false`
`TargetFolder`	Use the specified folder as the root folder instead of %HOMEPATH%\Documents\Citrix\AutoConfig.		String
`Locale`	Use the specified local instead of the locale derived from the system the tool is run on.		String
`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.		String
`SecurityCsvFileSpec`	The fully qualified file specification pointing to the SecurityClient.csv file downloaded from Citrix Identity and Access Management. The CustomerId must be specified when using this parameter.		String

Returns:

See Cmdlet return values

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:

Name	Description	Type
`CustomerId`	Customer’s ID.	String
`ClientId`	Customer’s client ID created on Citrix Cloud.	String
`Secret`	Customer’s secret key created on Citrix Cloud.	String
`Environment`	Production, ProductionGov, or ProductionJP environment.	Enumeration
`LogFileName`	Change the log file prefix from CitrixLog to something else.	String
`StopOnError`	Stops the operation upon first error.	`$true` or `$false`
`TargetFolder`	Use the specified folder as the root folder instead of %HOMEPATH%\Documents\Citrix\AutoConfig.	String
`Locale`	Use the specified local instead of the locale derived from the system the tool is run on.	String
`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.	String
`SecurityCsvFileSpec`	The fully qualified file specification pointing to the SecurityClient.csv file downloaded from Citrix Identity and Access Management. The CustomerId must be specified when using this parameter.	String

Returns:

See Cmdlet return values

Along with the cloud accessing parameters, the following parameters can be used with the prerequisites-related cmdlets:

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.

Support and troubleshooting cmdlets

New-CvadAcZipInfoForSupport - 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:

Name	Description	Required?	Type
`TargetFolder`	Specifies a target folder to create and save the zip file.		String
`Quiet`	Suppress logging to the console.		SwitchParameter

Returns:

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

Get-CvadAcStatus - Use to test connectivity and to ensure all prerequisites are met. Returns information about the tool like version number and connectivity with the cloud and connector status.

Parameters:

Name	Description	Type
Cloud-accessing parameters	See Cloud-accessing parameters	SwitchParameters
`SiteId`	Identifies the site to connect to.	String
`AdminAddress`	This 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.	String

Returns:

Displays the results for each item.

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

Parameters:

Name	Description	Required?	Type
Cloud-accessing parameters	See Cloud-accessing parameters		SwitchParameters
`Quiet`	Suppress logging to the console.		SwitchParameter

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:

Name	Description	Required?	Type
`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.		String
`CustomerId`	The customer’s ID. This parameter overrides the same value in the CustomerInfo.yml file.		String

Returns:

Results are shown on the command line.

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.

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

Parameters:

Name	Description	Required?	Type
Migrate by components	See Migrate by components		SwitchParameters
`TargetFolder`	Specifies the export destination folder.		String

Returns:

See Cmdlet return values

Show-CvadAcDocument - Displays this documentation in the default browser.

Parameters:
- None.
Returns:
- Display this webpage in the default web browser.

Find-CvadAcInFile - Find in file searches component YAML files looking for members matching a one or more names that may contain wildcards. The result is a report of found members. Find in file can only search one component at a time. Find in file searches all YAML files in the current folder and all subfolders. Use FindSourceFolder to limit the number of files to search.

Parameters:

Name	Description	Type
Migrate by components	See Migrate by components. Note: The `-All` value is not valid.	SwitchParameters
`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.	List of strings
`Unique`	Report only unique-found members.	SwitchParameter
`IncludeYaml`	Include the member specific YAML.	SwitchParameter
`FindSourceFolder`	The folder find begins searching in.	String
`DisplayLog`	Displays the log file at the completion of the cmdlet. Set to `$false` to suppress the log display.	SwitchParameter
`Quiet`	Suppress logging to the console.	SwitchParameter

Return:

Creates a report containing found members for the specified component.

Site activation cmdlets

For more information on activating sites and the usage of these cmdlets, see Activating sites.

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

Parameters:

Name	Description	Type
Cloud-accessing parameters	See Cloud-accessing parameters	SwitchParameters
`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.	SwitchParameter
`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.	List of strings
`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.	List of strings
`Quiet`	Suppress logging to the console.	SwitchParameter
`DisplayLog`	Displays the log file at the completion of the cmdlet. Set to `$false` to suppress the log display.	`$true or $false`

Returns:

See Cmdlet return values

Set-CvadAcSiteActiveStateCloud - Sets the cloud site state to either active or inactive.

Parameters:

Name	Description	Type
Cloud-accessing parameters	See Cloud-accessing parameters	SwitchParameters
`SiteActive`	When present, sets the cloud 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.	SwitchParameter
`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.	List of strings
`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.	List of strings
`Quiet`	Suppress logging to the console.	SwitchParameter
`DisplayLog`	Displays the log file at the completion of the cmdlet. Set to `$false` to suppress the log display.	`$true or $false`

Returns:

See Cmdlet return values

Merging multiple on-premises sites cmdlets

For more information on site merging and usage of these cmdlets, see Merge 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. Parameters:

Name	Description	Required?	Type
`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.	x	String
Site merging parameters	See Site merging parameters		SwitchParameters
`Quiet`	Suppress logging to the console.		SwitchParameter

Returns:

None

Set-CvadAcSiteMergingInfo - Updates an existing site merging prefix/suffix info set.

Parameters:

Name	Description	Required?	Type
`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.	x	String
Site merging parameters	See Site merging parameters		SwitchParameters
`Quiet`	Suppress logging to the console.		SwitchParameter

Returns:

None

Remove-CvadAcSiteMergingInfo - Removes an existing site merging prefix/suffix info set.

Parameters:
- SiteName – identifies the set of site prefixes and suffixes. This is a string and is required.
Returns:
- None

Site merging parameters

The following parameters can be used when running the site merging cmdlets. All listed parameters are strings.

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

Generic parameters

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

Migration mode 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.
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.
SecurityFileFolder – This is the fully qualified folder containing the CustomerInfo.yml file which might point to a local folder or a network share folder that may be under authentication control. The tool will 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.
SiteActive – Specifies whether the imported site is active or inactive. By default, this parameter is set to $false meaning the imported site is inactive.

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

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

PowerShell 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

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

Was this helpful

Automated configuration tool cmdlets for migration

December 24, 2024

Contributed by:

December 24, 2024

Contributed by:

Automated configuration tool cmdlets for migration

Basic cmdlets

On-premises to cloud cmdlets

Cloud to cloud cmdlets

Other basic cmdlets

Granular migration parameters

Migrate by components

Filtering by object names

Migrate by component names

By Delivery Group Name

Exclude Disabled

By Machine Name

Merge Machines

Prerequisites-related cmdlets

Prerequisites-related parameters

Support and troubleshooting cmdlets

Site activation cmdlets

Merging multiple on-premises sites cmdlets

Site merging parameters

Generic parameters

Cloud accessing parameters

Migration mode parameters

Log display parameters

Cmdlet return values

ActionResult

CustomResult

PowerShell help

In this article