HowTo: Update User’s Domain

Be sure to check out my Scripting4Crypto initiative. It’s a fun way to get into using cryptocurrencies all while getting your PowerShell needs met.

Recently, I realized there is not a cmdlet available to update the Domain (SecProvider) associated with a Windows type ProjectWise (PW) user account. This is not a common setting to have to update, however, it obviously occurs. In this post, I will show the solution I have come up with. We will be taking advantage of the pwwrapper assembly.

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

• Get-PWUsersByMatch
• Get-PWError
• Get-LastPWErrorId

Function

The following is the function definition and the help information.

FUNCTION Update-PWUserDomain {  
    <# 
        .SYNOPSIS 
        Used to update the Domain / SecProvider value. 

        .DESCRIPTION 
        Used to update the Domain / SecProvider value for the provided user. 

        .EXAMPLE 
        # Sets the assiocated Domain / SecProvider value for the provided user. 
        Update-PWUserDomain -UserName 'testPSUser' -Domain 'NewDomain' -Verbose
    #> 
    ... 
}

Parameters

There are two parameters available, UserName and Domain. Both are required. I am using the ValidateScript to ensure the username being passed is valid. If it is not, the function call will fail.

[CmdletBinding()]
param (
    [ValidateScript({Get-PWUsersByMatch -UserName $_})]
    [ValidateNotNullOrEmpty()]
    [Parameter(
        Mandatory = $true,
        HelpMessage = "Username of ProjectWise user to update."
    )]
    [string] $UserName,

    [ValidateNotNullOrEmpty()]
    [Parameter(
        Mandatory = $true,
        HelpMessage = "The new Domain / SecProvider value."
    )]
    [string] $Domain
) # end

Code

The following shows the meat of the function. I have included the BEGIN, PROCESS, and END code blocks even though not all are used. This is to maintain my own formatting. Obviously, you can exclude those if you like.

First, within the BEGIN block of code, we are getting the ProjectWise user object for the username provided. We’ve already ensured the username is valid, so there is no need to do any error handling. Because we are only updating the Domain / SecProvider value, there is no need to continue if the user type is NOT a Windows account.

Again, the purpose of this function is to update the associated Domain / SecProvider which we do not have a cmdlet for. So, we will need to call a function directly from the pwwrapper assembly. We need to ensure we ONLY update the Domain / SecProvider value, so, we will provide the function with all of the user’s existing values which we have available within the ProjectWise user object we retrieved in the BEGIN block of code.

One important caveat here, is that the ProjectWise user object lists the Type as Windows. We need to pass a value of ‘W’ to the function. 

The aaApi_ModifyUserExt function call will return a Boolean value which we can use to determine the message returned. If a false is returned, we will be presented with a warning message which should include the ProjectWise error information.

BEGIN {
    $Continue = $true

    # Get PWuser data.
    $pwUser = Get-PWUsersByMatch -UserName $UserName

    # If the PW user is not a windows user, exit cmdlet.
    if($pwUser.Type -ne 'Windows'){
        Write-Warning -Message "[BEGIN] Provided user is not a Windows user account type. Exiting."
        $Continue = $false
    }
} # end BEGIN...

PROCESS {
    if($Continue -eq $false){
        break
    }

    Write-Verbose -Message "[PROCESS] Setting domain to '$Domain' for user '$UserName'."

    if([pwwrapper]::aaApi_ModifyUserExt($pwUser.ID, "W", $Domain, $pwUser.Name, $null, $pwUser.Description, $pwUser.Email)) {
        Write-Verbose -Message "[PROCESS] Successfully updated the domain value."
    } else {
        # Get ProjectWise error information.
        $errorMessage = Get-PWError (Get-LastPWErrorId)
        Write-Warning -Message "[PROCESS] Failed to update the domain value. $errorMessage"
    }
} # end PROCESS...

END {
    # Nothing to do here.
} # end END...

Summary

I wanted to demonstrate a way to update the associated Domain / SecProvider with a user account. Using the pwwrapper assembly is one way to do this. However, be careful when calling functions directly from any assembly. There is no undo. So be use to develop / test your scripts in a safe environment. 

---

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.