• Auto-sync Environment Changes into ControlUp's Organizational Tree

    You can automatically keep the ControlUp organizational tree up-to-date with the ongoing changes in your environment topology. Our synchronization scripts are run automatically as a Windows scheduled task to read your topology and update ControlUp with added or removed machines. Those changes are automatically reflected in the ControlUp organizational tree and don't have to be made manually. You can continuously monitor the actual machines in your environment and remediate any issues, saving you time and resources. 

    • Our sync scripts are written in PowerShell and stored in our GitHub repository.
    • Depending on your VDI, you may have to run special credentials scripts to enable running the sync scripts. These are detailed in the articles covering each environment.
    • You set the Windows scheduled task to automatically run the sync script on the ControlUp monitor machine. This procedure is detailed below.


    The following is a list of available types of scripts to synchronize your environment. Click an environment to see further information and instructions on each. 

    VMware Horizon Sync Scripts

    VMware Horizon on Azure Cloud Sync Scripts

    Microsoft WVD

    Active Directory (article under construction)

    Citrix Virtual Apps and Desktops on-premises (CVAD or XenDesktop) (available soon)

    Citrix Cloud (early stages of development)


    Prerequisites for every sync script

    • The sync has to be performed on a machine which has the ControlUp monitor component installed. You can read about Adding a ControlUp Monitor.
    • User has to have ControlUp admin privileges on the ControlUp monitor machine.

    Schedule a Windows Task on the ControlUp Monitor

    To enable these scripts to continuously update the ControlUp organizational tree, you create a Windows Scheduled Task on the ControlUp monitor machine to periodically run the scripts.

    To create a scheduled task:

    The steps here are based on the latest Windows version. As this is third party software, we cannot guarantee the specific field names and steps but are giving you the most updated information as of the date we are publishing this article.

    1. Open the Task Scheduler from the Start menu and select Create Task... from the Actions menu and the Create Task screen appears.
    2. In the General tab, enter a Name for the new task to sync ControlUp with your environment and select Run whether user is logged on or not in the Security options.
    3. From the Triggers tab:
      • Add a new trigger, by clicking New..., and the New Trigger window appears.
      • From the Begin the task drop-down box, choose On a schedule and choose when to start the task in Task Scheduler, and set the Recur every box to 1 day.
        (The scheduled task can be run as often as every five minutes. The time you set also will be the time the task runs daily.)
    4. From the Actions tab:
      • Click New..., and select Start a program from the Action section.
      • From the Program/script section, choose “powershell.exe” (located in C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe)
      • Add the relevant arguments as described in the articles per environment.
    5. In the Conditions tab, you may keep the default selection or modify. 
    6. In the Settings tab, select the following:
      • Allow task to be run on demand
      • Stop the task if it runs longer than: (Recommended: 3 days)
      • If the running task does not end when requested, for it to stop
      • Do not start a new instance (from the drop down menu)
    7. Once all the details have been set, click OK, and the new task is created.
  • Horizon on Azure Sync to ControlUp
    Using our synchronization scripts, you can automatically populate the ControlUp organizational tree with your Horizon VDI running on the Azure cloud. Our sync script is run as a Windows scheduled task so that when you add or remove machines, those changes are automatically reflected in the organizational tree in ControlUp. You don't have to make any of those changes manually. When the script is run, your ControlUp organization reflects your current Horizon VDI for monitoring and remediation.
    • The sync script is written in PowerShell and stored in our GitHub repository.
    • You must run the credentials script twice for the dual authentication required by Horizon Cloud.
    • You set the Windows scheduled task to run the sync script on the ControlUp monitor machine. 


    • The sync has to be performed on a machine which has the ControlUp monitor component installed. You can read about Adding a ControlUp Monitor.
    • The ControlUp monitor must be version or higher.
    • The user running the scripts must have a local profile on the ControlUp monitor machine. Ensure that the same user logs onto the machine at some point before running the scripts.

    1. Access the scripts from our GitHub repository 

    You download the sync scripts from our GitHub repository of environment scripts which also includes synchronization scripts for other environments, including Horizon installed on-premises.
    1. Download the store.credentials.ps1 script.
    2. Download the Horizon_Azure_Sync.ps1 script.
    3. Copy these scripts to the machine running the ControlUp monitor.
    4. Optionally, in a PowerShell window, run this command to see the script's parameters, their descriptions, and default values:
        -get-help \<path to the file>\Horizon_Azure_Sync.ps1
    Here are the parameters in the sync script Horizon_Azure_Sync.ps1:
    Name Description
    FolderPath The target folder in the ControlUp organizational tree to save these objects.
    Preview Displays the expected results without committing any changes to the ControlUp environment.
    Delete Enables the script to execute removing objects from the ControlUp organizational tree. Use with the Preview parameter to see the proposed changes before committing them.
    LogFile Tells the script to log the output to a text file. Can be used with the Preview parameter to see the proposed changes.
    Site Specify a ControlUp Monitor site to assign the objects.
    Connection_servers A list of Connection Servers to contact for Horizon Pools, Farms and Computers to sync. Specify multiple Connection Servers in a comma separated list.

    Include only these specific Delivery Groups to be added to the ControlUp tree. Specify multiple Delivery Groups in a comma separated list.
    - If you do not enter a value here, all detected Delivery Groups are captured and updated in the ControlUp tree.

    - Wild cards values are supported. For example: specify "Epic*" to include both "Epic North" and "Epic South".

    - If you enter values for excludeDesktopPools, the 'exclude' supersedes any values entered here and will not 'include' them.


    Exclude specific delivery groups from being added to the ControlUp tree. Specify multiple Delivery Groups to exclude in a comma separated list.

    - Wild cards values are supported. For example: specify "*CGY" to exclude both "Epic CGY" and "Cerner CGY".

    - If you enter values for includeDesktopPools, this 'exclude' supersedes any values entered there and will not 'include' them.


    Configures the script to sync only the local Pod to ControlUp.


    Configures the script to sync only the local Site to ControlUp.

    2. Create the credentials files by running the Store_credentials.ps1 script

    The Horizon on Azure Cloud requires dual authentication. To run the scheduled task on the ControlUp monitor machine, you need both sets of credentials. Therefore you have to run the Store_credentials.ps1 script twice to create those credentials files to access both: 
    • The MyVMware site.
    • The Horizon Cloud Active Directory.
    To create the required credentials files:
    1. Access the ControlUp monitor machine as the user who will be running the scheduled task.
    2. On the monitor machine, go to the folder where you saved the Store_credentials.ps1 script.
    3. Run a PowerShell prompt.
    4. Run this command: 
      & '.\store credentials' -credential $null -credentialType HorizonCloudmyVMware
      Note: If you are not in the same folder as where the store_credentials.ps1 script is saved, you must give the full path after the '.'.

    5. When prompted, enter the User name and Password to access the MyVMware site.CredentialPromptMyVMware.jpg
    6. Run this command from the same folder as the script:
      & '.\store credentials' -credential $null -credentialType HorizonCloudDomain
    7. When prompted, enter the User name and Password as the domain\username used to access the Horizon Cloud site.

    Once you have run the script twice, two encrypted .xml files are created in this folder on the ControlUp monitor machine: C:\ProgramData\ControlUp\ScriptSupport.
    The names of those encrypted files include the user who ran these scripts and must be the same user to run the scheduled task. The user who ran the scripts and created these encrypted files is admingle.
    If you are running the scheduled task under a different account, you need to run the script again twice to set up new credentials files as these can be used only by the account that created them on the same machine they were created.
    3. Set up a Windows Scheduled Task

    Follow the steps in this article to create the Windows Scheduled Task.

    In the Windows Local Security Policy, ensure that this user’s role has Log on as a batch job properties.


    The credential tasks are set to run powershell.exe with these command lines for the create and delete tasks respectively:
    -ExecutionPolicy RemoteSigned -NoLogo -File "C:\CU Environment Sync Scripts\Horizon_Azure_Sync.ps1"  -folderPath "\Datacenter\Virtual Desktops\Horizon Cloud"  -logfile "C:\CU Environment Sync Scripts\HZ Azure Sync.log" -base "cloud-us-2"
    -ExecutionPolicy RemoteSigned -NoLogo -File "C:\CU Environment Sync Scripts\Horizon_Azure_Sync.ps1"  -folderPath "\Datacenter\Virtual Desktops\Horizon Cloud"  -logfile "C:\CU Environment Sync Scripts\HZ Azure Sync Deletes.log" -base "cloud-us-2" -Delete
    Required Arguments
    -folderpath is the path in the ControlUp console where you want the Horizon Cloud items to be created.
    -logfile is appended to with each run of the script.
    -base has to be the logged on URL for the Horizon Cloud location. 

    Tip: If you are unsure of the base of your Horizon Cloud, you can find it in the URL.
    Per the image below, the base would be cloud-us-2.base.jpg


  • Preparation of Horizon Scripts


    ControlUp 8.1 and above has the ability to monitor and manage VMware Horizon.

    ControlUp has created a number of Powershell scripts that can run either manually or automatically. However, some preliminary steps must be taken prior to using these scripts. This article guides you through the environment preparation process to use our Horizon scripts.

    Using Script Based Actions for VMware Horizon

    To use Script Based Actions (or SBA’s) for VMware Horizon certain elements must be in place. Every Horizon based SBA user needs a credential file created on the system in use. This includes the monitor if used for automated actions.

    Creating a Credentials File

    To create a credentials file the SBA called ‘Create credentials for Horizon View scripts’ must be invoked.

    To create a credentials file:

    1. Right click the machine that you want to create the credentials on and click Script Actions > More… > Create credentials for Horizon View scripts select the correct SBA, and the > Create credentials for Horizon View scripts popup appears.
    2. From the Credentials section enter/select the user to be granted to run the scripts.
    3. Create a new username and password and click OK, and the script is executed.
      Note: The username field is in domain/username format.

    VMware PowerCLI Installation and Configuration


    VMware PowerCLI can be installed with the Install and Configure VMware PowerCLI SBA. When this SBA is used PowerCLI is installed for all users on the system. This SBA installs PowerCLI from the PowerShell Gallery so that it can be installed manually, if needed.

    To install PowerCLI the latest version of the Nuget package provider is required and is installed by the SBA, as well.


    There are two main configurations that can be set for VMware PowerCLI:

    • Choosing whether you want to join the VMware Customer Experience Improvement Program (CEIP). More information about this program can be found here.
    • What action should be taken if the certificates for your various VMware components are not trusted. By default PowerCLI will stop working when the certificates are not signed properly so it is recommended to have it set to ‘warn’ to receive a warning or ‘ignore’ to ignore the fact that these certificates haven’t been signed.

    Both configuration items are handled in the Install and Configure VMware PowerCLI SBA as well. To ensure maximum security, by default, the CEIP program is not set. The Invalid Certificate action is set to warn when there are many certificates for Horizon environments in use that have been signed for the URLs that the users connect to and not to the various URLs of the connection servers themselves.

    To install and configure the VMware PowerCLI:

    1. Right click the system where you want to install PowerCLI and select Script Actions > More… > Install and configure VMware PowerCLI, and the Install and configure VMware PowerCLI popup appears.
    2. Select True or False for the CEIP configuration and Warn, Fail or Ignore for Invalid Certificate Action, and click OK and a confirmation screen appears to verify that the configuration is updated.
      Note: This may take a while depending on available resources. You can check how busy the system is by looking at the Powershell process.

    The Hv.Helper Module

    ControlUp’s Horizon scripts use the Hv.Helper Powershell module. This needs to be available on every machine running the ControlUp Console or Monitor and the Horizon scripts.
    As a shortcut, we offer a script that has the module embedded so you can simply install it on the required targets. You do NOT need to have the module installed on your Horizon View VMs.

    To install the Hv.Helper module:

    1. Right click the system where you want to install the Install Hv.Helper Module and select Script Actions > More… > Install Hv.Helper module for Horizon View scripts, and the Install Hv.Helper module for Horizon View scripts popup appears.
    2. By default, existing modules are not overwritten. To overwrite an existing version, change Overwrite existing… to True, and select OK and a confirmation screen appears to verify that the helper module is installed.

    If you prefer to download the Hv.Helper module, you can do so from Github: https://github.com/vmware/PowerCLI-Example-Scripts/tree/master/Modules/VMware.Hv.Helper


    It is important to note that automatic pass-through authentication for your Windows credentials is not possible. Every time a connection is made with the Horizon Connection Server you must explicitly pass credentials. To fix this, ControlUp has come up with a solution using PSCredential objects.

    A PSCredential object can be used to store the credentials for the user by creating the object, and setting to only work on the machine that the object was created on. Horizon View scripts look for a PSCredential object for running the scripts in the %PROGRAMDATA%\ControlUp\ScriptSupport folder. The object itself uses the following naming convention: %USERNAME%_HorizonView_Cred.xml

    To clarify, the object is stored as an encrypted XML file. It can only be decrypted and used by the user that created it on the system where it was created.

    To create this object on all the machines running Horizon scripts ControlUp created the script: Create credentials for Horizon View scripts. This script creates the PSCredential object for you and optionally installs the Vmware.Hv.Helper module as well.

    Using the Create credentials for Horizon View scripts

    Before preparing the machines with the PSCredential Object, you must determine what the PSCredential object is to be used for, because, as mentioned above, the object has a major dependency; it can only be used by the Windows account under which context it was created. If you run the scripts yourself, (manually OR with automation, where the monitor is using YOUR stored credentials), simply open the console and follow the instructions below.

    However, to keep things simple, it is recommended that the monitor uses a dedicated service account. With a service account you can use an extremely complicated password that can be set to never expire.

    You can also lock down the account so it will only have permission to perform very specific tasks. For example, if you use the service account to run automation scripts for Horizon, this account will not need a mailbox, home drive, etc. Once everything you don’t need is removed, except for the appropriate VMware permission, you can now create a stored credential for this account in the console to be used for the monitors. (https://support.controlup.com/hc/en-us/articles/207203265-Credentials-Store)

    Note: With either approach, the script must run using stored credentials, therefore it is recommended to ensure that you have the set of credentials you want to use in the store before running the script. You can use your own credentials or service account credentials.

    To run the Create credentials for Horizon View scripts:

    1. Open the Scripts pane from the Home tab in the console and find Create credentials for Horizon View scripts. Select the script and download it.
      Note: You can close the Scripts pane while the script is downloading. The download should only take a few minutes.
    2. In the console, select all the machines you wish to be prepared for the Horizon scripts.
    3. Right click and navigate to Scripts > More > Create credentials for Horizon View scripts, and the Create credentials for Horizon View scripts popup appears.
    4. From the the Credentials dropdown, select the stored credentials you wish to use and enter the username and password to be used to run the script and click OK and the script runs.
      Note: In this example the account used to run the script and the account used to authenticate to Horizon are not the same. Therefore, the script is run by the automation account (in this case the ‘general’ service account MyAutomationAccount) but will authenticate to Horizon using the dedicated HorizonViewAccount
      You can also give your automation account the required permissions in Horizon and use this account for Horizon authentication.
      Each approach has its pros and cons: By using two separate accounts you increase security, meaning not making the automation account a very powerful account that has permissions on every system, but maintaining two accounts does increase administration. This works the other way, too, using only one account is less secure but requires less administration.

    When running a Horizon script on these machines the script will look for the PSCredential object in the %PROGRAMDATA%\ControlUp\ScriptSupport folder and use it to authenticate to the Horizon Connection server.

    Note: If the account password stored in the PSCredential object is changed, you must run the ‘Create…’ script again as the password in the object is no longer valid. This is another example why it’s recommended to have a service account with a very complicated password that never changes.

    As always, if you have any questions, please do not hesitate to reach out to our support team at suuport@ControlUp.com