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

    Active Directory Organizational Unit Sync with ControlUp Console Tree

    • Dark
    • PDF

    Article Summary

    You can synchronize the Organizational Unit's (OU) structure of an Active Directory (AD) domain to the Organization Tree in the ControlUp Real-Time DX 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 Task on the ControlUp Monitor is used to automate the synchronization process in the background.

    Removed AD Dependency
    From version 9.0, you can deploy ControlUp Monitors on machines that are not joined to a local Active Directory (AD) domain. For details, see Removed AD Dependency for Monitors.

    Installation Guide

    1. Download the AD_Sync.ps1 and Build_CUTree.ps1 scripts from our Github repository.
    2. Copy both scripts onto the machine on a ControlUp Monitor machine. Both scripts need to be located in the same directory. 
    3. Create a Windows Task

    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 treeStringYes
    domainThe AD domain contains the OU - if it's not the current domain as specified in the OU parameterStringNo
    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 objectsSwitchNo
    LogFileLog script output to a text file. Can be used with the Preview parameter to log uncommitted changesSwitchNo
    SiteName of the Monitor site where machines are addedStringNo
    batchCreateFoldersCreate folders in batches rather than sequentiallySwitchNo
    forceForce the folder creation if the number of new folders is too largeSwitchNo

    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
    2. Save both scripts in a folder on the Monitor machine, for example C:\temp
    3. Create a Windows Task and 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 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.

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