Active Directory Organizational Unit Sync with ControlUp Console Tree
  • Dark
  • PDF

Active Directory Organizational Unit Sync with ControlUp Console Tree

  • Dark
  • PDF

You can synchronize the Organizational Unit's (OU) structure of an Active Directory (AD) domain to the Organization Tree in the ControlUp Console. This is especially useful when your environment is constantly changing, for example when workstations are added and removed. Use this AD sync script to synchronize any changes in a specific OU to the ControlUp Console. A Windows Scheduled Task on the ControlUp monitor machine is used to automate the synchronization process in the background.

Installation Guide

  1. Download the AD_Sync.ps1 and Build_CUTree.ps1 scripts from our Github repository.
  2. Copy both scripts onto the machine where the ControlUp monitor is installed. They have to be in the same directory.
  3. Create a Task Scheduler by following the instructions in this article.

AD Sync Script Description

The table below describes all input parameters that can be used to call the script. To use the script, you need to provide at least 2 input parameters (OU, folderPath) as described in this table.

Input Parameters


OUThe distinguished name of the Organizational Unit (OU).StringYes
folderPathFolders into which the AD structure is imported in the ControlUp organizational tree.StringYes
domainThe AD domain contains the OU - if it's not the current domain as specified in the OU parameter.StringNo
PreviewShows expected results without committing any changes to the ControlUp environment (works like the -WhatIf switch in PowerShell).SwitchNo
DeleteEnables the script to execute the removal of objects.SwitchNo
LogFileLog script output to a text file. Can be used with the Preview parameter to log uncommitted changes. SwitchNo
SiteName of the Monitor site to where machines are added.StringNo
batchCreateFoldersCreate folders in batches rather than sequentially.SwitchNo
forceForce the folder creation if the number of new folders is too large.SwitchNo

Use Case

Our goal is to reflect the workstations under the OU Workstations_Marketing in the ControlUp Console.

  1. Download the AD_Sync.ps1 and Build_CUTree.ps1 scripts from our Github repository.
    The best way to download scripts from Github is to click the Raw button and then copy & paste the scripts to the local computer.
  2. Save both scripts in the C:\temp directory on the Monitor machine.
  3. Create a Windows Task Schedule as described here.
    Use these arguments as input parameters for the script:
    C:\temp\AD_Sync.ps1 -OU 'OU=Workstations_Marketing,OU=Marketing,DC=bendomain,DC=local' -folderpath 'ParentFolder'

    You can always test the AD_Sync script without using a Task Scheduler. To do so, open Powershell as an administrator and execute the command below:

    .\AD_Sync.ps1 -OU "OU=Workstations_Marketing,OU=Marketing,DC=bendomain,DC=local" -folderPath 'ParentFolder' -ErrorAction SilentlyContinue


    The script looks for the OU "Workstations_Marketing " in the bendomain.local domain and add its objects to a "ParentFolder " folder in the ControlUp Console.

  4. Run the task that you created. Right-click the task and select Run. 4403173500689mceclip4.png
  5. The ParentFolder that was specified as an input parameter is shown in the ControlUp Console.

Using the -Site Parameter

This use case shows how to use the script to add OU objects to a dedicated ControlUp Monitor site. This is done by using the -Site switch.
Use the following arguments to call the script:

.\AD_Sync.ps1 -OU "OU=Workstations_Marketing,OU=Marketing,DC=bendomain,DC=local" -folderPath ParentFolder1 -Site "Default2"

This adds both workstations to the Default2 monitor site.


If the site parameter is not specified, the script automatically uses the Default site.

-LogFile Parameter

This parameter provides a logging functionality. The script output is logged to a text file that you specify in the parameter.

.\AD_Sync.ps1 -OU "OU=Workstations_Marketing,OU=Marketing,DC=bendomain,DC=local" -folderPath ParentFolder1 -LogFile ".\LogFileWithChanges.txt"

This command creates a new log file "LogFileText.txt" and commits changes to the ControlUp Console.

-Preview Parameter

The Preview parameter is used for test purposes. It's highly recommended to use this parameter when you don't want to commit any changes to the ControlUp console.

.\AD_Sync.ps1 -OU "OU=Workstations_Marketing,OU=Marketing,DC=bendomain,DC=local" -folderPath ParentFolder1 -LogFile ".\LogFileTest.txt" -Preview

The log file displays "Preview Mode", indicating that no changes were committed to the ControlUp console.

Was this article helpful?