HowTo: Get-PWParentWorkArea FUNCTION

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.

I want to thank Robert McMillan for the inspiration for this post. He had created a process to get the Parent Rich Project of a specified folder or document. In this post, we will look at a function I’ve created which accepts a ProjectWise Document or ProjectWise Folder object and works its way back up the hierarchy until the Parent Work Area is found. If one is found, the Parent Work Area Folder object will be returned. 

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

• Get-PWFolders

Function

The following is the function definition and the help information.

FUNCTION Get-PWParentWorkArea {
    <#
        .SYNOPSIS
        Get-PWParentWorkArea returns the Parent Work Area / Rich Project folder.

        .DESCRIPTION
        Returns the Parent Work Area / Rich Project folder for the provided ProjectWise Document or Folder object within the folder hierarchy.

        .PARAMETER Document
        Starting ProjecWise Document object.

        .PARAMETER Folder
        Starting ProjectWise Folder object.

        .EXAMPLE
        Get-PWParentWorkArea -Document (Show-PWDocumentSelectionDialog)

        .EXAMPLE
        Get-PWParentWorkArea -Folder (Show-PWFolderBrowserDialog)
#>

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

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

END {...} # end END...

} # end FUNCTION Get-PWParentWorkArea...

Parameters

There are two parameters available: Document and Folder. Either a ProjectWise Document object or a ProjectWise Folder object must be included.

[CmdletBinding()]
Param (
    [ValidateNotNullOrEmpty()]
    [Parameter(
        ParameterSetName = 'Document',
        Mandatory = $true )]
    [PWPS_DAB.CommonTypes+ProjectWiseDocument] $Document,

    [ValidateNotNullOrEmpty()] 
    [Parameter( 
        ParameterSetName = 'Folder', 
        Mandatory = $true )] 
    [PWPS_DAB.CommonTypes+ProjectWiseFolder] $Folder

) # end Param...

BEGIN Code Block

In the BEGIN code block, we capture the date time the function was called and return some Verbose verbiage back to the console.

BEGIN{

    $CmdletName = $MyInvocation.InvocationName
    $DateStart = Get-Date

    Write-Verbose -Message "[BEGIN] '$DateStart' - Entering '$CmdletName' Function..."

} # end BEGIN...

PROCESS Code Block

The following shows the PROCESS code block which is the meat of the function. 

First, we determine the current object’s FolderID. This will either be the ProjectWise Folder object’s ProjectID or the ProjectWise Document object’s containing ProjectID.

Next, we determine if the current folder is a Work Area / Rich Project by looking for $true within the IsRichProject folder property. If it is, we bypass the do/until loop and return the Folder Object.

Otherwise, we start from the current folder and work our way up the folder tree within the do/until loop. Each time through the loop we set the FolderID equal to the previous folder’s ParentID and use the Get-PWFolders to select the ProjectWise Folder object. And again, we  determine if the current folder is a Work Area / Rich Project. 

Finally, if one of the folders is a Work Area / Rich Project, the ProjectWise Folder object is returned. Otherwise, a message is returned indicating one was not found.

PROCESS {
    # Empty string to pass error messages to for the try / catch.
    $Message = [string]::Empty
    try {

        $IsRichProject = $false

        if($Folder){
            $FolderID = $Folder.ProjectID
            $IsRichProject = $Folder.IsRichProject
        } else {
            $FolderID = $Document.ProjectID
        }

        if($IsRichProject -eq $false){
            do {
                # Using the -Verbose:$false will suppress all verbose output from the Get-PWFolders cmdlet. Thanks Robert. This is great.
                $Folder = Get-PWFolders -FolderID $FolderID -JustOne -Verbose:$false 

                $IsRichProject = $Folder.IsRichProject
                
                $FolderID = $Folder.ParentID
            } until (($IsRichProject -eq $true) -or ($FolderID -eq 0))

            if ( $IsRichProject -ne $true ) {
                $Message = 'No rich project found in folder tree.'
                throw $Message
            }
        }

        Write-Output $Folder

    } catch {
        Write-Warning -Message "[PROCESS] $Message"
    }

} # end PROCESS...

END Code Block

In the END code block, once again we capture the date time. This time we are capturing when the function was completed. We return some Verbose verbiage back to the console containing the amount of time it had taken to complete the process.

END {
    $DateEnd = Get-Date
    Write-Verbose -Message "[END] $($DateEnd - $DateStart) - Exiting '$CmdletName' Function..."
} # end END...

Summary

Again, the reason for this function is to return the ProjectWise Folder object for the nearest Work Area / Rich Project to the ProjectWise Folder object or Document object provided.

---

Experiment with it and have fun. And please, let me know if there is a topic you would like to see a post for. Or share a solution you have developed.

The following is a link to the complete psm1 file.

HowTo-GetParentWorkArea

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. And thank you for checking out my blog.