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
Merge-CvadAcToSite
New-CvadAcToSite
Sync-CvadAcToSite
Granular migration For components, use parameters with commands above. Examples: MachineCatalogs, Tags. For component names, use parameters with commands above. Examples: IncludeByName, ExcludeByName.
Cloud to cloud cmdlets Backup-CvadAcToFile Backs up all the configuration from your cloud site.
Restore-CvadAcToSite
Remove-CvadAcFromSite
Granular migration For components, use parameters with commands above. Examples: MachineCatalogs, Tags. For component names, use parameters with commands above. Examples: IncludeByName, ExcludeByName.
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
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
Test-CvadAcConnectionWithSite
Find-CvadAcConnector
Get-CvadAcCustomerSites
New-CvadAcTemplateToFile
Show-CvadAcDocument
Find-CvadAcInFile
Site activation cmdlets Set-CvadAcSiteActiveStateOnPrem Sets the on-premises site state to either active or inactive.
Set-CvadAcSiteActiveStateCloud
Merging multiple on-premises sites cmdlets New-CvadAcSiteMergingInfo Creates a site merging prefix/suffix info set.
Set-CvadAcSiteMergingInfo
Remove-CvadAcSiteMergingInfo

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 an Import, Merge, or Restore 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 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:

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

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

Automated configuration tool cmdlets