Scripts/Get-BPAFolder.ps1
|
function Get-BPAFolder { <# .SYNOPSIS Gets AutoMate BPA folders. .DESCRIPTION Get-BPAFolder gets folders objects from AutoMate BPA. Get-BPAFolder can receive items on the pipeline and return related objects. .PARAMETER InputObject The object(s) to use in search for folders. .PARAMETER Name The name of the folder (case sensitive). Wildcard characters can be escaped using the ` character. If using escaped wildcards, the string must be wrapped in single quotes. For example: Get-BPAFolder -Name '`[Test`]' .PARAMETER ID The ID of the folder. .PARAMETER FilterSet The parameters to filter the search on. Supply hashtable(s) with the following properties: Property, Comparator, Value. Valid values for the Comparator are: =, !=, <, >, contains (default - no need to supply Comparator when using 'contains') .PARAMETER FilterSetMode If multiple filter sets are provided, FilterSetMode determines if the filter sets should be evaluated with an AND or an OR .PARAMETER Path The path containing the folder. .PARAMETER Parent Get folders that contain the specified folders. This parameter is only used when a folder is piped in. .PARAMETER Type The folder type: AGENTGROUPS, CONDITIONS, PROCESSAGENTS, PROCESSES, TASKAGENTS, TASKS, USERGROUPS, USERS, WORKFLOWS .PARAMETER SortProperty The object property to sort results on. Do not use BPAServer or TypeName, since those are custom properties added by this module, and not exposed in the API. .PARAMETER SortDescending If specified, this will sort the output on the specified SortProperty in descending order. Otherwise, ascending order is assumed. .PARAMETER BPAServer The AutoMate BPA management server. .INPUTS Agents related to the following objects can be retrieved by this function: Workflow Folder .EXAMPLE # Get folder "My Folder" Get-BPAFolder "My Folder" .EXAMPLE # Get folder containing workflow "My Workflow" Get-BPAWorkflow "My Workflow" | Get-BPAFolder .EXAMPLE # Get workflows in "My Folder" Get-BPAFolder "My Folder" -Type WORKFLOWS | Get-BPAWorkflow .EXAMPLE # Get folder "My Folder" by path Get-BPAFolder -Path "\PROCESSES" -Name "My Folder" .EXAMPLE # Get subfolders of "My Folder" Get-BPAFolder "My Folder" -Type PROCESSES | Get-BPAFolder .EXAMPLE # Get folders using filter sets Get-BPAFolder -FilterSet @{ Property = "Path"; Comparator = "contains"; Value = "WORKFLOWS"} .NOTES Author(s): : David Seibel Contributor(s) : Date Created : 08/24/2016 Date Modified : 06/08/2018 .LINK https://github.com/davidseibel/PoshBPA #> [CmdletBinding(DefaultParameterSetName = "All")] [OutputType([System.Object[]])] param( [Parameter(ValueFromPipeline = $true, ParameterSetName = "ByPipeline")] [ValidateNotNullOrEmpty()] $InputObject, [Parameter(Position = 0)] [ValidateNotNullOrEmpty()] [string]$Name, [Parameter(ParameterSetName = "ByID")] [ValidateNotNullOrEmpty()] [string]$ID, [Hashtable[]]$FilterSet, [ValidateSet("And","Or")] [string]$FilterSetMode = "And", [ValidateNotNullOrEmpty()] [string]$Path, [Parameter(ParameterSetName = "ByPipeline")] [switch]$Parent = $false, [Parameter(ParameterSetName = "ByPipeline")] [switch]$Recurse = $false, [ValidateSet("AGENTGROUPS","CONDITIONS","PROCESSAGENTS","PROCESSES","TASKAGENTS","TASKS","USERGROUPS","USERS","WORKFLOWS")] [ValidateNotNullOrEmpty()] [string]$Type, [ValidateNotNullOrEmpty()] [string[]]$SortProperty = @("Path","Name"), [switch]$SortDescending = $false, [ValidateNotNullOrEmpty()] [string]$BPAServer ) BEGIN { # If the server is specified, or only 1 server is connected, don't show it. Otherwise, show the server. if ($PSCmdlet.ParameterSetName -eq "ByID" -and (-not $PSBoundParameters.ContainsKey("BPAServer")) -and ($global:BPAConnectionInfo.Count -gt 1)) { throw "When searching by ID: 1) BPAServer must be specified, OR 2) only one server can be connected." } $splat = @{ RestMethod = "Get" BPAServer = $BPAServer } $result = @() $sortOptions = "sort_field=$($SortProperty[0])" if ($SortDescending.ToBool()) { $sortOptions += "&sort_order=DSC" } if ($Path -like "*?\") { $Path = $Path.TrimEnd("\") } } PROCESS { switch($PSCmdlet.ParameterSetName) { "All" { if ($PSBoundParameters.ContainsKey("Path") -and $PSBoundParameters.ContainsKey("Name")) { # If both Path and Name are provided if (-not [System.Management.Automation.WildcardPattern]::ContainsWildcardCharacters($Name)) { if ($Path -ne "\") { # The API doesn't return root folders $FilterSet += @{Property = "Path"; Comparator = "="; Value = $Path} $FilterSet += @{Property = "Name"; Comparator = "="; Value = $Name} } elseif (-not $PSBoundParameters.ContainsKey("FilterSet")) { $result += Get-BPAFolderRoot -BPAServer $BPAServer | Where-Object {$_.Path -eq $Path -and $_.Name -eq $Name} } else { Write-Warning "Root folders are not returned when using -FilterSet!" } } else { if ($Path -ne "\") { # The API doesn't return root folders $FilterSet += @{Property = "Path"; Comparator = "="; Value = $Path} } elseif (-not $PSBoundParameters.ContainsKey("FilterSet")) { $result += Get-BPAFolderRoot -BPAServer $BPAServer | Where-Object {$_.Path -eq $Path -and $_.Name -like $Name} } else { Write-Warning "Root folders are not returned when using -FilterSet!" } } } elseif ($PSBoundParameters.ContainsKey("Path")) { # If just path is provided if ($Path -ne "\") { # The API doesn't return root folders $FilterSet += @{Property = "Path"; Comparator = "="; Value = $Path} } elseif (-not $PSBoundParameters.ContainsKey("FilterSet")) { $result += Get-BPAFolderRoot -BPAServer $BPAServer | Where-Object {$_.Path -eq $Path} } else { Write-Warning "Root folders are not returned when using -FilterSet!" } } elseif ($PSBoundParameters.ContainsKey("Name")) { # If just name is provided if (-not [System.Management.Automation.WildcardPattern]::ContainsWildcardCharacters($Name)) { $FilterSet += @{Property = "Name"; Comparator = "="; Value = $Name} if (-not $PSBoundParameters.ContainsKey("FilterSet")) { $result += Get-BPAFolderRoot -BPAServer $BPAServer | Where-Object {$_.Name -eq $Name} } else { Write-Warning "Root folders are not returned when using -FilterSet!" } } elseif (-not $PSBoundParameters.ContainsKey("FilterSet")) { $result += Get-BPAFolderRoot -BPAServer $BPAServer | Where-Object {$_.Name -like $Name} } else { Write-Warning "Root folders are not returned when using -FilterSet!" } } elseif (-not $PSBoundParameters.ContainsKey("FilterSet")) { # If neither are provided $result += Get-BPAFolderRoot -BPAServer $BPAServer } if ($Path -ne "\") { # The API doesn't return root folders $splat += @{ Resource = Format-BPAUri -Path "folders/list" -FilterSet $FilterSet -FilterSetMode $FilterSetMode -SortProperty $SortProperty -SortDescending:$SortDescending.ToBool() } $result += Invoke-BPARestMethod @splat } } "ByID" { $tempResult = Get-BPAFolderRoot -BPAServer $BPAServer | Where-Object {$_.ID -eq $ID} if (-not $tempResult) { $splat += @{ Resource = "folders/$ID/get" } $result = Invoke-BPARestMethod @splat } else { $result = $tempResult } } "ByPipeline" { foreach ($obj in $InputObject) { $tempSplat = $splat if (-not $tempSplat.ContainsKey("BPAServer")) { $tempSplat += @{ BPAServer = $obj.BPAServer } } else { $tempSplat["BPAServer"] = $obj.BPAServer } switch ($obj.TypeName) { {($_ -in @("Workflow","Task","Process","Condition","Agent","AgentGroup","UserGroup"))} { # Get folders containing the provided object(s) $tempResult = Get-BPAFolderRoot | Where-Object {$_.ID -eq $obj.ParentID} if (-not $tempResult) { $tempFilterSet = $FilterSet + @{Property = "ID"; Comparator = "="; Value = $obj.ParentID} $tempSplat += @{ Resource = Format-BPAUri -Path "folders/list" -FilterSet $tempFilterSet -FilterSetMode $FilterSetMode -SortProperty $SortProperty -SortDescending:$SortDescending.ToBool() } $result += Invoke-BPARestMethod @tempSplat } else { $result += $tempResult } } "User" { # Get the folder containing the user by default if (-not $Type) { $Type = "USERS" } switch ($Type) { "USERS" { # Get folder containing the provided user(s) $tempFilterSet = $FilterSet + @{Property = "ID"; Comparator = "="; Value = $obj.ParentID} $tempSplat += @{ Resource = Format-BPAUri -Path "folders/list" -FilterSet $tempFilterSet -FilterSetMode $FilterSetMode -SortProperty $SortProperty -SortDescending:$SortDescending.ToBool() } $result += Invoke-BPARestMethod @tempSplat } "WORKFLOWS" { # Get the workflow folder for the specified user ID $tempResult = Get-BPAFolderRoot -BPAServer $obj.BPAServer | Where-Object {$_.ID -eq $obj.WorkflowFolderID} if (-not $tempResult) { $result += Get-BPAFolder -ID $obj.WorkflowFolderID -BPAServer $obj.BPAServer } else { $result += $tempResult } } "TASKS" { # Get the task folder for the specified user ID $tempResult = Get-BPAFolderRoot -BPAServer $obj.BPAServer | Where-Object {$_.ID -eq $obj.TaskFolderID} if (-not $tempResult) { $result += Get-BPAFolder -ID $obj.TaskFolderID -BPAServer $obj.BPAServer } else { $result += $tempResult } } "PROCESSES" { # Get the process folder for the specified user ID $tempResult = Get-BPAFolderRoot -BPAServer $obj.BPAServer | Where-Object {$_.ID -eq $obj.ProcessFolderID} if (-not $tempResult) { $result += Get-BPAFolder -ID $obj.ProcessFolderID -BPAServer $obj.BPAServer } else { $result += $tempResult } } "CONDITIONS" { # Get the condition folder for the specified user ID $tempResult = Get-BPAFolderRoot -BPAServer $obj.BPAServer | Where-Object {$_.ID -eq $obj.ConditionFolderID} if (-not $tempResult) { $result += Get-BPAFolder -ID $obj.ConditionFolderID -BPAServer $obj.BPAServer } else { $result += $tempResult } } } } "Folder" { if ($Parent) { $tempResult = Get-BPAFolderRoot -BPAServer $obj.BPAServer | Where-Object {$_.ID -eq $obj.ParentID} if (-not $tempResult) { # Get folders that contain the provided folders(s) $tempFilterSet = $FilterSet + @{Property = "ID"; Comparator = "="; Value = $obj.ParentID} $tempSplat += @{ Resource = Format-BPAUri -Path "folders/list" -FilterSet $tempFilterSet -FilterSetMode $FilterSetMode -SortProperty $SortProperty -SortDescending:$SortDescending.ToBool() } $result += Invoke-BPARestMethod @tempSplat } else { $result += $tempResult } } else { # Get folders contained within the provided folder(s) $tempFilterSet = $FilterSet + @{Property = "ParentID"; Comparator = "="; Value = $obj.ID} $tempSplat += @{ Resource = Format-BPAUri -Path "folders/list" -FilterSet $tempFilterSet -FilterSetMode $FilterSetMode -SortProperty $SortProperty -SortDescending:$SortDescending.ToBool() } $tempResult = Invoke-BPARestMethod @tempSplat if (($tempResult.Count -gt 0) -and $Recurse) { $tempResult += $tempResult | Get-BPAFolder -Recurse } $result += $tempResult } } default { $unsupportedType = $obj.GetType().FullName if ($_) { $unsupportedType = $_ } elseif (($null -ne $obj.Type) -and ($obj.Type -ne "")) { $unsupportedType = $obj.Type } Write-Error -Message "Unsupported input type '$unsupportedType' encountered!" -TargetObject $obj } } } } } } END { if ($Type) { # Filter folders to only the specified type $result = $result | Where-Object {($_.Path -like "\$Type*") -or ($_.Path -eq "\" -and $_.Name -eq $Type)} } if ($PSBoundParameters.ContainsKey("Name") -and [System.Management.Automation.WildcardPattern]::ContainsWildcardCharacters($Name)) { try { "" -like $Name | Out-Null } # Test wildcard string catch { throw } # Throw error if wildcard invalid $result = $result | Where-Object {$_.Name -like $Name} } # Workaround for bug 23381 - the API returns PROCESSS as the path instead of PROCESSES foreach ($r in $result) { if ($r.Path -like "\PROCESSS*") { $r.Path = $r.Path.Replace("PROCESSS","PROCESSES") } } # End workaround $SortProperty += "BPAServer", "ID" return $result | Sort-Object $SortProperty -Unique -Descending:$SortDescending.ToBool() } } |