Automated configuration tool cmdlets
This page lists all the cmdlets and parameters supported by the tool.
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. |
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. |
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 Required? 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:
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 Required? 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:
-
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 Required? 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:
-
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 Required? 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:
-
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 Required? 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:
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 Required? 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:
-
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 Required? 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:
-
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 Required? 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:
Other basic cmdlets
-
Compare-CvadAcToSite
- Compares the on-premises .yml files with the cloud configuration, producing a report of changes that are made by anImport
,Merge
, orRestore
cmdlet.Parameters:
Name Description Required? 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:
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 inMergeMachines
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.
Prerequisites-related cmdlets
-
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:
-
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 Required? 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:
Prerequisites-related parameters
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 Required? 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:
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:
-
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. UseFindSourceFolder
to limit the number of files to search.Parameters:
Name Description Required? 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 Required? 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:
-
Set-CvadAcSiteActiveStateCloud
- Sets the cloud site state to either active or inactive.Parameters:
Name Description Required? 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:
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 withSet-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 withApplicationFolderRoot
. -
ApplicationFolderRoot
– the new root folder to application folders. This creates an extra folder hierarchy.ApplicationFolderRoot
can be combined withApplicationFolderPrefix
. -
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 withApplicationFolderRoot
. -
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. TheRemove
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
andTemplate
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