Back to Posts

Copy your Active Directory OU structure to ControlUp

Missing some structure?

ControlUp’s organization tree offers a nice way of organizing your monitored computers, much like in many IT management systems. One limitation of this tree is the fact that it needs to be created and maintained manually. Usually, admins base their ControlUp organizational structure on the existing OU structure in Active Directory, which makes perfect sense. So wouldn’t it be nice if we could automagically take the Active Directory OU structure along with the computers in it, and replicate it into ControlUp? Now we can!

This post will explain the basics on ControlUp v7 PowerShell module and then provide a PowerShell script that syncs a given Active Directory OU structure into ControlUp. Here’s a video of the script in action:

Add Computer

The full PowerShell script can be found below, but first let’s explain briefly how it works.

ControlUp PowerShell Module

Starting with version 7.0, ControlUp includes a few PowerShell cmdlets which are meant to provide automation capabilities for manipulating the organizational tree. The following cmdlets are supported:

  • Add-CUComputer – adds a computer to your organization
  • Remove-CUComputer – removes a computer from your organization
  • Move-CUComputer – relocates a computer to a different folder in your organization
  • Add-CUFolder – creates a new folder in your organization
  • Remove-CUFolder – removes a folder from your organization

The above cmdlets are supported by means of a new PowerShell module (ControlUp.PowerShell.User.dll) which is deployed automatically when you install a ControlUp Monitor instance in your organization. A monitor instance is a mandatory prerequisite for using this module.

In order to use the cmdlets, perform the following steps:

  • Log on locally on your ControlUp Monitor computer or create a remote PowerShell session to that computer
  • Import the module by using the following command:
    • Import-Module “C:\Program Files\Smart-X\ControlUpMonitor\Version <x>\ControlUp.PowerShell.User.dll”
    • (<x> above corresponds to the current version of ControlUp)
  • Ensure the cmdlets are available by using the following command:
    • Get-Command -Module controlup*
    • You should see the five cmdlets
  • Read the help for the cmdlets by using the following commands:
    • Get-Help Add-CUComputer
    • Get-Help Remove-CUComputer
    • Get-Help Move-CUComputer
    • Get-Help Add-CUFolder
    • Get-Help Remove-CUFolder

Replicating Active Directory OU Structure

In many environments it makes sense for the ControlUp organization tree to reflect the structure of your Active Directory OUs in which computer accounts are currently located. For example, consider the following basic OU layout:

For the purpose of this demo, we’ll assume that the OU structure under Datacenter2 needs to be managed in ControlUp. I have created a PowerShell script which will create the same directory structure in ControlUp, populating it with computers as shown.

To achieve this task, we will use the ControlUp PowerShell module described above in tandem with the Active Directory PowerShell module. To install the Active Directory PowerShell Module, use the Server Manager to add the Remote Server Administration Tools feature (or specifically Active Directory module for Windows PowerShell).

So to summarize, here’s what you’ll need to run the script:

  • A ControlUp Monitor instance running v7 or later. You should execute the script locally on the monitor machine or using PowerShell remoting
  • Active Directory Module for PowerShell
  • The distinguished name of the root OU which you would like to copy into ControlUp (in the example pictured above that will be “OU=Datacenter2,DC=qa,DC=local”)

The script will basically cycle recursively through all child OUs of the specified root OU, add the OUs as ControlUp folders and then add the computer accounts as managed ControlUp computers. I’m sure many things can be improved about this script, and many other use cases are possible with those cmdlets. For example, this code can be adapted to retrieve the folder structure from different sources, e.g Citrix XenDesktop delivery groups or Vmware Horizon desktop pools.

Feel free to use the script below and comment. Until next time…

Full PowerShell script

2 thoughts on “Copy your Active Directory OU structure to ControlUp

  1. It would be ideal if you could auto add computers to a folder from the console GUI by filtering the OU’s to look for any new computers as not everybody AD structure is going to mirror controlup folder structure.

Leave a Reply

Your email address will not be published. Required fields are marked *