HowTo: Add Active Directory Groups To Synchronize

In this post, we will be creating a simple PowerShell function which will add one or more Active Directory groups to a ProjectWise datasource. You will need to install the ‘ActiveDirectory’ PowerShell module. This is used to verify the group names to sychronize.

Install-Module ActiveDirectory -Force

All of the ProjectWise related cmdlets are available using the PWPS_DAB module. At the time of this post, I am using version 23.4.1. Take a look at the help for each of the cmdlets to become familiar with their functionality, available parameters, etc.

• Add-PWUserSynchronizationServiceSources

FUNCTION Definition

The following is the function wrapper which will contain the remainder of the code.

FUNCTION Add-MyADGroupToSync {
    <#
        .Synopsis
        Used to add an AD group(s) to be synchronized with the current ProjectWise datasource.
        .DESCRIPTION
        Used to add an AD group(s) to be synchronized with the current ProjectWise datasource.
        Requires a valid AD Group name.
        .EXAMPLE
        Adds a single AD group to be sync'd.
        Add-MyADGroupToSync -GroupName 'ProjectWise_Designers' -Verbose
        .EXAMPLE
        Adds two AD groups to be sync'd.
        Add-MyADGroupToSync -GroupName 'ProjectWise_Designers', 'ProjectWise_Managers' -Verbose
    #>

    [CmdletBinding()]
    param (...) # end param...

    BEGIN {...} # end BEGIN...

    PROCESS {...} # end PROCESS...

    END{...} # end END...
} # end FUNCTION Add-MyADGroupToSync...
Export-ModuleMember -Function Add-MyADGroupToSync

Parameters

First thing we need to do is create our parameter and value pairs. The help messages will explain the purpose for each parameter. You will see that I have incorporated “ValidateScript” to ensure the group(s) provided are valid. This way I do not have do any additional checks to determine if a specified ProjectWise folder exists, or the path to the log file we will generate exists, etc.

[CmdletBinding()]
param ( 
    # Name of AD Group(s) to add to be sync'd with the current PW datasource.
    [ValidateNotNullOrEmpty()] 
    [ValidateScript({ Get-ADGroup -FolderPath $_ -JustOne })]
    [Parameter(
        HelpMessage = "Name of AD Group(s) to add to be sync'd with the current PW datasource.",
        Mandatory = $true,
        Position = 0)]
    [string[]] $GroupName,

    # Domain name where AD Group(s) reside.
    [ValidateNotNullOrEmpty()]
    [Parameter(
        HelpMessage = "Domain name where AD Group(s) reside. Set a default if possible.",
        Mandatory = $false,
        Position = 1)]
    [string] $Domain = 'MyCompanyDomain'
) # end param...

---

Begin

I want to take a second and point out a couple of conventions that I use in my scripts. First, you may notice that I put a comment at the end of many of the blocks of code. Doing this makes it easier for me to determine where a block of code starts and ends. Comes in handy when troubleshooting a script.  I also add text ([BEGIN], [PROCESS], [END]) in the output messages (Write-Verbose, Write-Warning, Write-Error) corresponding to the section of the script I am in. Again, this makes it obvious where something occurs within the script.

BEGIN {  
    $CmdletName = $MyInvocation.MyCommand.Name
    $StartTime = Get-Date
    Write-Verbose -Message "[BEGIN] $StartTime - Entering '$CmdletName' Function..."
} # end BEGIN...

---

PROCESS

Now, we will proceed to the PROCESS code block. Here we will loop through the groups provided and add each to be sychronized with the active ProjectWise datasource.

PROCESS {
    Write-Verbose -Message "[PROCESS] There are $($GroupName.Count) group(s) to add."
    foreach($group in $GroupName){
        try{
            $return = Add-PWUserSynchronizationServiceSources -Domain $Domain -Groups $group -ErrorAction Stop
            Write-Verbose -Message "[PROCESS] Successfully added '$group' to be sync'd."
        } catch {
            Write-Warning -Message "[PROCESS] An error occurred while attempting to add '$group' to be sync'd. $($Error[0].Message)"
        }
    }
} # end PROCESS...

---

END

Lastly, we will proceed to the END block of code.

END {
    $EndTime = Get-Date
    Write-Verbose -Message "[END] It took $($EndTime - $StartTime) to complete the process."
    Write-Verbose -Message "[END] $EndTime - Exiting '$CmdletName' Function..."
} # end END...

---

Experiment with it and have fun. Hopefully, you find this useful. Please let me know if you have any questions or comments.  If you like this post, please click the Like button at the bottom of the page.