lib/Tasks.ps1

function Get-TMTask {
    <#
    .SYNOPSIS
    Gets one or more Tasks from TransitionManager using optional filters
 
    .DESCRIPTION
    This function gets one or more Tasks from TransitionManager by Id, Number,
    Task Spec Id, Status, Asset Name, Asset Type, Action Name, or Category.
 
    .PARAMETER TMSession
    The name of the TM Session containing a TransitionManager connection
 
    .PARAMETER ProjectId
    The Id of the TransitionManager project. If this is not provided,
    the project from the TMSession will be used
 
    .PARAMETER EventName
    One or more Event Names to filter by
 
    .PARAMETER Id
    One or more Task Ids to filter by
 
    .PARAMETER TaskNumber
    One or more Task numbers to filter by
 
    .PARAMETER TaskSpecId
    One or more Task spec Ids to filter by
 
    .PARAMETER Status
    One or more Statuses to filter by
    Valid values are: Hold, Planned, Ready, Pending, Started, Completed, Terminated
 
    .PARAMETER AssetName
    One or more Asset names to filter by
 
    .PARAMETER AssetType
    One or more Asset types to filter by
 
    .PARAMETER AssetClass
    One or more Asset classes to filter by
    Valid values are: Device, Application, Storage, Database
 
    .PARAMETER ActionName
    One or more Action names to filter by
 
    .PARAMETER Category
    One or more Task categories to filter by
 
    .PARAMETER Title
    One or more Task Titles/Comments to filter by. Accepts wildcard characters
 
    .PARAMETER Team
    One or more Team names to filter by
 
    .PARAMETER Api
    Boolean indicating that REST API endpoints should be used in favor of web service endpoints
 
    .PARAMETER TMQL
    Boolean indicating that TMQL queries should be used in favor of web service and REST API endpoints
 
    .PARAMETER IncludeTaskDependencyDetails
    Switch indicating that, when using TMQL, the secondary query for Task Dependencies should be executed to provide
    more details about the Task's Predecessors and Successors
 
    .EXAMPLE
    Get-TMTask -TMSession $ProfileName -Status 'Completed', 'Ready' -Event 'TEST Event'
 
    .EXAMPLE
    Get-TMTask -TaskNumbers 12345, 165876, 30559
 
    .EXAMPLE
    # Get all Tasks from the 'TEST Event' Event that have a 'Server' type associated Asset and the 'HCX - Switchover' Action
    Get-TMTask -AssetType 'Server' -ActionName 'HCX - Switchover' -Event 'TEST Event'
 
    .OUTPUTS
    One or more TMTask objects representing the results of the filtered search
    #>

    [OutputType([TMTask[]])]
    [CmdletBinding(DefaultParameterSetName = 'ByTaskProperties')]
    param (
        [Parameter(Mandatory = $false, Position = 0)]
        [String]$TMSession = "Default",

        [Parameter(Mandatory = $false, Position = 1)]
        [AllowNull()]
        [Alias('Project')]
        [Nullable[Int]]$ProjectId = $TMSessions[$TMSession].UserContext.Project.Id,

        [Parameter(Mandatory = $false)]
        [Alias('Event', 'TMEvent')]
        [Object[]]$EventName,

        [Parameter(Mandatory = $true, ValueFromPipeline = $true, ParameterSetName = 'ById')]
        [Alias('TaskId')]
        [Int[]]$Id,

        [Parameter(Mandatory = $false, ParameterSetName = 'ByTaskProperties')]
        [Alias('Number')]
        [Int[]]$TaskNumber,

        [Parameter(Mandatory = $false, ParameterSetName = 'ByTaskProperties')]
        [Alias('TaskSpec')]
        [Int[]]$TaskSpecId,

        [Parameter(Mandatory = $false, ParameterSetName = 'ByTaskProperties')]
        [ArgumentCompleter({ [TMTask]::ValidStatuses })]
        [ValidateScript( { $_ -in [TMTask]::ValidStatuses } )]
        [Alias('TaskStatus')]
        [String[]]$Status,

        [Parameter(Mandatory = $false, ParameterSetName = 'ByTaskProperties')]
        [Alias('Asset')]
        [String[]]$AssetName,

        [Parameter(Mandatory = $false, ParameterSetName = 'ByTaskProperties')]
        [String[]]$AssetType,

        [Parameter(Mandatory = $false, ParameterSetName = 'ByTaskProperties')]
        [ValidateSet('Application', 'Device', 'Database', 'Storage')]
        [String[]]$AssetClass,

        [Parameter(Mandatory = $false, ParameterSetName = 'ByTaskProperties')]
        [Alias('TaskAction')]
        [String[]]$ActionName,

        [Parameter(Mandatory = $false, ParameterSetName = 'ByTaskProperties')]
        [Alias('TaskCategory')]
        [String[]]$Category,

        [Parameter(Mandatory = $false, ParameterSetName = 'ByTaskProperties')]
        [Alias('Comment', 'TaskTitle', 'TaskComment')]
        [String[]]$Title,

        [Parameter(Mandatory = $false, ParameterSetName = 'ByTaskProperties')]
        [Alias('Role')]
        [String[]]$Team,

        [Parameter(Mandatory = $false)]
        [Bool]$Api = $true,

        [Parameter(Mandatory = $false)]
        [Bool]$TMQL = $true,

        [Parameter(Mandatory = $false)]
        [Switch]$IncludeTaskDependencyDetails
    )


    begin {

        function Get-FilteredTasksAPI([Hashtable]$Filters) {
            $TaskList = [System.Collections.Generic.List[TMTask]]::new()

            Write-Verbose "Using REST API endpoint"
            Write-Verbose "Forming web request parameters"
            $RestSplat = @{
                Uri                  = "https://$($TMSessionConfig.TMServer)/tdstm/api/task?rows=1000&page=1"
                Method               = 'GET'
                WebSession           = $TMSessionConfig.TMRestSession
                StatusCodeVariable   = 'StatusCode'
                SkipHttpErrorCheck   = $true
                SkipCertificateCheck = $TMSessionConfig.AllowInsecureSSL
                Body                 = ($Filters | ConvertTo-Json -Depth 5 -Compress)
            }
            Write-Debug "Web Request Parameters:"
            Write-Debug ($RestSplat | ConvertTo-Json -Depth 5)
            Write-Verbose "Invoking REST method"
            $Response = Invoke-RestMethod @RestSplat

            Write-Debug "Status Code: $StatusCode"
            if ($StatusCode -in 200, 204) {
                Write-Verbose "Formatting response content"

                ## Assign the Rows variable based on what TM provides back
                if ($Response.PSObject.Properties.Name -contains 'rows') {
                    $Rows = $Response.rows
                } elseif ($Response.PSObject.Properties.Name -contains 'records') {
                    $Rows = $Response.records
                } elseif ($Response.PSObject.Properties.Name -contains 'tasks') {
                    $Rows = $Response.tasks
                }

                foreach ($Row in $Rows) {
                    try {
                        $TaskList.Add([TMTask]::new($Row))
                    } catch {
                        Write-Warning "Could not retrieve task # $($Row.TaskNumber): $($_.Exception.Message)"
                    }
                }

                if ($Response.total -gt 1) {
                    for ($i = 2; $i -le $Response.total; $i++) {
                        Write-Verbose "Forming web request parameters"
                        $RestSplat.Uri = "https://$($TMSessionConfig.TMServer)/tdstm/api/task?rows=1000&page=$i"
                        Write-Debug "Web Request Parameters:"
                        Write-Debug ($RestSplat | ConvertTo-Json -Depth 5)
                        Write-Verbose "Invoking REST method"
                        $Response = Invoke-RestMethod @RestSplat

                        Write-Debug "Status Code: $StatusCode"
                        if ($StatusCode -in 200, 204) {
                            Write-Verbose "Formatting response content"

                            ## Assign the Rows variable based on what TM provides back
                            if ($Response.PSObject.Properties.Name -contains 'rows') {
                                $Rows = $Response.rows
                            } elseif ($Response.PSObject.Properties.Name -contains 'records') {
                                $Rows = $Response.records
                            } elseif ($Response.PSObject.Properties.Name -contains 'tasks') {
                                $Rows = $Response.tasks
                            }

                            foreach ($Row in $Rows) {
                                try {
                                    $TaskList.Add([TMTask]::new($Row))
                                } catch {
                                    Write-Warning "Could not retrieve task # $($Row.TaskNumber): $($_.Exception.Message)"
                                }
                            }
                        } else {
                            Write-Error "The response status code $($StatusCode) does not indicate success: $([System.Net.HttpStatusCode] $StatusCode)"
                        }
                    }
                }
            } else {
                Write-Error "The response status code $($StatusCode) does not indicate success: $([System.Net.HttpStatusCode] $StatusCode)"
            }

            , $TaskList
        }


        function Get-FilteredTasksWS([Hashtable]$Filters) {
            $TaskList = [System.Collections.Generic.List[TMTask]]::new()

            Write-Verbose "Formatting filters"
            $FilterStrings = @()
            foreach ($Key in $Filters.Keys) {
                $FilterStrings += "$($Key)=$([System.Web.HttpUtility]::UrlEncode($Filters.$Key))"
            }
            Write-Debug "FilterStrings: $($FilterStrings -join "`n")"

            Write-Verbose "Using Web Services endpoint"
            Write-Verbose "Forming web request parameters"
            $WebRequestSplat = @{
                Uri                  = "https://$($TMSessionConfig.TMServer)/tdstm/ws/task?" + ($FilterStrings -join '&')
                Method               = "GET"
                WebSession           = $TMSessionConfig.TMWebSession
                SkipHttpErrorCheck   = $true
                SkipCertificateCheck = $TMSessionConfig.AllowInsecureSSL

            }
            Write-Debug "Web Request Parameters:"
            Write-Debug ($WebRequestSplat | ConvertTo-Json -Depth 5)
            Write-Verbose "Invoking web request"
            $Response = Invoke-WebRequest @WebRequestSplat

            Write-Debug "Status Code: $($Response.StatusCode)"
            if ($Response.StatusCode -in 200, 204) {
                Write-Verbose "Formatting response content"
                $ResponseContent = $Response.Content | ConvertFrom-Json -Depth 5
                if ($ResponseContent.status -match 'error') {
                    Write-Error "Could not get tasks: $($ResponseContent.errors)"
                } else {
                    foreach ($Row in $ResponseContent.data) {
                        try {
                            $TaskList.Add([TMTask]::new($Row))
                        } catch {
                            Write-Warning "Could not retrieve task # $($Row.TaskNumber): $($_.Exception.Message)"
                        }
                    }
                }
            } else {
                Write-Error "The response status code $($Response.StatusCode) does not indicate success"
            }

            , $TaskList
        }


        function Get-FilteredTasksTMQL([String[]]$Filters) {
            $TaskList = [System.Collections.Generic.List[TMTask]]::new()

            # Use a StringBuilder to build the query for TM
            Write-Verbose "Forming TMQL query"
            $Query = [System.Text.StringBuilder]::new()
            [void]$Query.AppendLine("find Task by \")
            [void]$Query.AppendLine($Filters[0] + " \")
            for ($i = 1; $i -lt $Filters.Count; $i++) {
                [void]$Query.AppendLine("and " + $Filters[$i] + " \")
            }
            [void]$Query.AppendLine([TMTask]::TMQLFetchString)

            # Query TM for the Tasks and convert them to TMTask objects
            Write-Verbose "Invoking the TMQL statement"
            Write-Debug "TMQL Query:`n`n$($Query.ToString())"
            (Invoke-TMQLStatement -TMSession $TMSession -Statement $Query.ToString()) | ForEach-Object {
                $TaskList.Add([TMTask]::new($_))
            }

            # Replace the Task Dependencies
            if ($IncludeTaskDependencyDetails) {
                foreach ($Task in $TaskList) {
                    $Task.Successors = $TaskDependencies | Where-Object { $_.TaskId -in $Task.Successors.TaskId }
                    $Task.Predecessors = $TaskDependencies | Where-Object { $_.TaskId -eq $Task.Id }
                }
            }

            , $TaskList
        }


        function Get-FilteredTaskDependenciesTMQL([String[]]$Filters) {
            $TaskDependencyList = [System.Collections.Generic.List[TMTaskDependency]]::new()

            # Use a StringBuilder to build the query for TM
            Write-Verbose "Forming TMQL query"
            $Query = [System.Text.StringBuilder]::new()
            [void]$Query.AppendLine("find TaskDependency by \")
            [void]$Query.AppendLine($Filters[0] + " \")
            for ($i = 1; $i -lt $Filters.Count; $i++) {
                [void]$Query.AppendLine("and " + $Filters[$i] + " \")
            }
            [void]$Query.AppendLine([TMTaskDependency]::TMQLFetchString)

            # Query TM for the Tasks and convert them to TMTask objects
            Write-Verbose "Invoking the TMQL statement"
            Write-Debug "TMQL Query:`n`n$($Query.ToString())"
            (Invoke-TMQLStatement -TMSession $TMSession -Statement $Query.ToString()) | ForEach-Object {
                $TaskDependencyList.Add(
                    [TMTaskDependency]::new(
                        $_.id,
                        $_.'assetComment.id',
                        $_.'assetComment.taskNumber',
                        $_.'assetComment.comment'
                    )
                )
            }

            , $TaskDependencyList
        }


        # Get the session configuration
        Write-Verbose "Checking for cached TMSession"
        $TMSessionConfig = $global:TMSessions[$TMSession]
        Write-Debug "TMSessionConfig:"
        Write-Debug ($TMSessionConfig | ConvertTo-Json -Depth 5)
        if (-not $TMSessionConfig) {
            throw "TMSession '$TMSession' not found. Use New-TMSession command before using features."
        }

        # Use the TM session if a project id is not provided
        $ProjectId ??= $TMSessionConfig.UserContext.Project.id

        $Tasks = [System.Collections.Generic.List[TMTask]]::new()

        # Create a list for post-request filters to be applied to the returned Tasks
        $TaskFilters = [System.Collections.Generic.List[ScriptBlock]]::new()

        # Gather a list of just the event names. Added for backwards compatibility
        if ($EventName -and ($EventName[0] -is [TMEvent])) {
            [String[]]$EventName = $EventName.Name
        }

        # Determine which endpoint to hit based on the TM version and REST session and set up the base filters
        # REST = TASK REST API
        # WS50 = Web Services using ATE
        # WS47 = Web Services without ATE
        # TMQL - TMQL REST API
        Write-Verbose "Determining TM endpoint to use and setting up filters"
        if ($TMQL) {
            $Endpoint = 'TMQL'
            $TaskDependencies = [System.Collections.Generic.List[TMTaskDependency]]::new()
            $RequestFilters = @( "'project.id' eq $ProjectId" )

            if ($PSCmdlet.ParameterSetName -eq 'ById' -and $IncludeTaskDependencyDetails) {
                $TaskDependencies.AddRange((Get-FilteredTaskDependenciesTMQL -Filters @("'assetComment.id' inList([$($Id -join ', ')])")))
                $TaskDependencies.AddRange((Get-FilteredTaskDependenciesTMQL -Filters @("'predecessor.id' inList([$($Id -join ', ')])")))
            } else {
                if ($EventName) {
                    if ($EventName.Count -eq 1) {
                        $RequestFilters += "'moveEvent.name' eq '$($EventName[0])'"
                        $TaskDependencyRequestFilters += "'assetComment.moveEvent.name' eq '$($EventName[0])'"
                    } else {
                        $RequestFilters += "'moveEvent.name' ate '$($EventName -join '|')'"
                        $TaskDependencyRequestFilters += "'assetComment.moveEvent.name' ate '$($EventName -join '|')'"
                        $TaskFilters.Add([ScriptBlock]::Create("`$_.Event.Name -in '$($EventName -join "', '")'"))
                    }
                } else {
                    $TaskDependencyRequestFilters = @( "'id' ne 0" )
                }

                if ($IncludeTaskDependencyDetails) {
                    $TaskDependencies.AddRange((Get-FilteredTaskDependenciesTMQL -Filters $TaskDependencyRequestFilters))
                }
            }

        } elseif ($Api) {
            $Endpoint = 'REST'
            $RequestFilters = @{
                project = $ProjectId
            }

            if ($EventName) {
                if ($TMSessionConfig.TMVersion -ge '6.0.1.2') {
                    $TaskFilters.Add([ScriptBlock]::Create("`$_.Event.Name -in '$($EventName -join "', '")'"))
                } else {
                    if ($EventName.Count -gt 1) {
                        Write-Warning "Filtering with multiple Event Names is only supported in TMQL. Only the first Event Name passed '$($EventName[0])' will be used"
                    }
                    $RequestFilters.event = @{name = $EventName[0] }
                }
            }

            ## Wrap the request with the right syntax for Newer API version requirements
        } else {
            $Endpoint = $TMSessionConfig.TMVersion -like '4.*' ? 'WS47' : 'WS50'
            $RequestFilters = @{
                projectId = $ProjectId
            }

            if ($EventName) {
                try {
                    $EventId = (Invoke-TMQLStatement -Statement "find Event by 'name' eq '$($EventName[0])' fetch 'id'").id
                    $RequestFilters.moveEvent = $EventId
                    if ($EventName.Count -gt 1) {
                        Write-Warning "Filtering with multiple Event Names is only supported in TMQL. Only the first Event Name passed '$($EventName[0])' will be used"
                    }
                } catch {
                    $TaskFilters.Add([ScriptBlock]::Create("{$_.Event.Name -in '$($EventName -join "', '")'}"))
                }
            }
        }
        Write-Debug "Endpoint: $Endpoint"
        Write-Debug "Initial Request Filters:`n$($RequestFilters | ConvertTo-Json)"
    }

    process {

        Write-Debug "Parameter Set: $($PSCmdlet.ParameterSetName)"
        if ($PSCmdlet.ParameterSetName -eq 'ById') {
            Write-Verbose "Requesting Tasks by Id"
            switch ($Endpoint) {
                'TMQL' {
                    Write-Verbose "Using TMQL endpoint"
                    $RequestFilters += "'id' inList([$($Id -join ', ')])"
                    $Tasks.AddRange((Get-FilteredTasksTMQL -Filters $RequestFilters))
                }
                'REST' {
                    Write-Verbose "Using REST API endpoint"
                    $Id | ForEach-Object {
                        Write-Verbose "Forming web request parameters"
                        $RestSplat = @{
                            Uri                  = "https://$($TMSessionConfig.TMServer)/tdstm/api/task/$($_)?project=$($ProjectId)"
                            Method               = 'GET'
                            WebSession           = $TMSessionConfig.TMRestSession
                            StatusCodeVariable   = 'StatusCode'
                            SkipHttpErrorCheck   = $true
                            SkipCertificateCheck = $TMSessionConfig.AllowInsecureSSL
                        }
                        Write-Debug "Web Request Parameters:"
                        Write-Debug ($RestSplat | ConvertTo-Json -Depth 5)
                        Write-Verbose "Invoking REST method"
                        $Response = Invoke-RestMethod @RestSplat

                        Write-Debug "Status Code: $StatusCode"
                        if ($StatusCode -in 200, 204) {
                            Write-Verbose "Formatting response content"
                            $Tasks.Add([TMTask]::new($Response))
                        } else {
                            Write-Error "The response status code $($StatusCode) does not indicate success: $([System.Net.HttpStatusCode] $StatusCode)"
                        }
                    }
                }
                { $_ -in 'WS50', 'WS47' } {
                    Write-Verbose "Using Web Services endpoint"

                    $Id | ForEach-Object {
                        Write-Verbose "Forming web request parameters"
                        $WebRequestSplat = @{
                            Uri                  = "https://$($TMSessionConfig.TMServer)/tdstm/assetEntity/showComment?id=$($_)"
                            Method               = 'GET'
                            WebSession           = $TMSessionConfig.TMWebSession
                            SkipHttpErrorCheck   = $true
                            SkipCertificateCheck = $TMSessionConfig.AllowInsecureSSL
                        }
                        Write-Debug "Web Request Parameters:"
                        Write-Debug ($WebRequestSplat | ConvertTo-Json -Depth 5)
                        Write-Verbose "Invoking web request"
                        $Response = Invoke-WebRequest @WebRequestSplat

                        Write-Debug "Status Code: $($Response.StatusCode)"
                        if ($Response.StatusCode -in 200, 204) {
                            Write-Verbose "Formatting response content"
                            $ResponseContent = $Response.Content | ConvertFrom-Json
                            $Tasks.Add([TMTask]::new($ResponseContent.assetComment))
                        } else {
                            Write-Error "The response status code $($Response.StatusCode) does not indicate success: $([System.Net.HttpStatusCode] $Response.StatusCode)"
                        }
                    }
                }
            }
        } else {
            Write-Verbose "Requesting Tasks by filter properties"

            # Add parameter values to the request and task filters
            Write-Verbose "Formatting request and post-request filters"
            if ($TaskNumber) {
                switch ($Endpoint) {
                    'TMQL' { $RequestFilters += "'taskNumber' ate '$($TaskNumber -join '|')'" }
                    'WS50' { $RequestFilters.taskNumber = $TaskNumber -join '|' }
                    { $_ -in 'REST', 'WS47' } {
                        if ($TaskNumber.Count -eq 1) {
                            $RequestFilters.taskNumber = $TaskNumber[0]
                        } else {
                            $TaskFilters.Add([ScriptBlock]::Create("`$_.TaskNumber -in $($TaskNumber -join ', ')"))
                        }
                    }
                }
            }

            if ($TaskSpecId) {
                switch ($Endpoint) {
                    'TMQL' { $RequestFilters += "'taskSpec' ate '$($TaskSpecId -join '|')'" }
                    'WS50' { $RequestFilters.taskSpec = $TaskSpecId -join '|' }
                    'REST' { Write-Error "Filtering by Task Spec ID cannot be performed against the REST API endpoint" }
                    'WS47' { $RequestFilters.taskSpec = $TaskSpecId[0] }
                }
            }

            if ($Status) {
                switch ($Endpoint) {
                    'TMQL' { $RequestFilters += "'status' ate '$($Status -join '|')'" }
                    'WS50' { $RequestFilters.status = $Status -join '|' }
                    { $_ -in 'REST', 'WS47' } {
                        if ($Status.Count -eq 1) {
                            $RequestFilters.status = $Status[0]
                        } else {
                            $TaskFilters.Add([ScriptBlock]::Create("`$_.Status -in '$($Status -join "', '")'"))
                        }
                    }
                }
            }

            if ($AssetName) {
                switch ($Endpoint) {
                    'TMQL' { $RequestFilters += "'assetEntity.Name' ate '$($AssetName -join '|')'" }
                    'WS50' { $RequestFilters.assetName = $AssetName -join '|' }
                    'REST' {
                        if ($AssetName.Count -eq 1) {
                            $RequestFilters.asset = @{name = $AssetName[0] }
                        } else {
                            $TaskFilters.Add([ScriptBlock]::Create("`$_.Asset.Name -in '$($AssetName -join "', '")'"))
                        }
                    }
                    'WS47' {
                        if ($AssetName.Count -eq 1) {
                            $RequestFilters.assetName = $AssetName[0]
                        } else {
                            $TaskFilters.Add([ScriptBlock]::Create("`$_.Asset.Name -in '$($AssetName -join "', '")'"))
                        }
                    }
                }
            }

            if ($AssetType) {
                switch ($Endpoint) {
                    'TMQL' { $RequestFilters += "'assetEntity.assetType' ate '$($AssetType -join '|')'" }
                    'WS50' { $RequestFilters.assetType = $AssetType -join '|' }
                    'REST' {
                        if ($AssetType.Count -eq 1) {
                            $RequestFilters.asset = @{type = $AssetType[0] }
                        } else {
                            $TaskFilters.Add([ScriptBlock]::Create("`$_.Asset.Type -in '$($AssetType -join "', '")'"))
                        }
                    }
                    'WS47' {
                        if ($AssetType.Count -eq 1) {
                            $RequestFilters.assetType = $AssetType[0]
                        } else {
                            $TaskFilters.Add([ScriptBlock]::Create("`$_.Asset.Type -in '$($AssetType -join "', '")'"))
                        }
                    }
                }
            }

            if ($AssetClass) {
                switch ($Endpoint) {
                    'TMQL' { $RequestFilters += "'assetEntity.Asset Class' ate '$($AssetClass -join '|')'" }
                    { $_ -in 'REST', 'WS50', 'WS47' } { $TaskFilters.Add([ScriptBlock]::Create("`$_.Asset.Class -in '$($AssetClass -join "', '")'")) }
                }
            }

            if ($ActionName) {
                switch ($Endpoint) {
                    'TMQL' { $RequestFilters += "'apiAction.name' ate '$($ActionName -join '|')'" }
                    'WS50' { $RequestFilters.apiAction = $ActionName -join '|' }
                    'REST' { $TaskFilters.Add([ScriptBlock]::Create("`$_.Action.Name -in '$($ActionName -join "', '")'")) }
                    'WS47' {
                        if ($ActionName.Count -eq 1) {
                            $RequestFilters.apiAction = $ActionName[0]
                        } else {
                            $TaskFilters.Add([ScriptBlock]::Create("`$_.Action.Name -in '$($ActionName -join "', '")'"))
                        }
                    }
                }
            }

            if ($Category) {
                switch ($Endpoint) {
                    'TMQL' { $RequestFilters += "'category' ate '$($Category -join '|')'" }
                    'WS50' { $RequestFilters.category = $Category -join '|' }
                    { $_ -in 'REST', 'WS47' } {
                        if ($Category.Count -eq 1) {
                            $RequestFilters.category = $Category[0]
                        } else {
                            $TaskFilters.Add([ScriptBlock]::Create("`$_.Category -in '$($Category -join "', '")'"))
                        }
                    }
                }
            }

            if ($Title) {
                switch ($Endpoint) {
                    'TMQL' { $RequestFilters += "'comment' ate '$($Title -join '|')'" }
                    'WS50' { $RequestFilters.comment = $Title -join '|' }
                    'REST' {
                        if ($Title.Count -eq 1) {
                            $RequestFilters.title = $Title[0]
                        } else {
                            $TaskFilters.Add([ScriptBlock]::Create("`$_.Title -match '$(($Title -join '|') -replace '(?<!\.)\*', '.*' -replace '%', '.*')'"))
                        }
                    }
                    'WS47' {
                        if ($Title.Count -eq 1) {
                            $RequestFilters.category = $Title[0]
                        } else {
                            $TaskFilters.Add([ScriptBlock]::Create("`$_.Title -match '$(($Title -join '|') -replace '(?<!\.)\*', '.*' -replace '%', '.*')'"))
                        }
                    }
                }
            }

            if ($Team) {
                switch ($Endpoint) {
                    'TMQL' { $RequestFilters += "'role' ate '$($Team -join '|')'" }
                    'WS50' { $RequestFilters.role = $Team -join '|' }
                    'REST' {
                        if ($Team.Count -eq 1) {
                            $RequestFilters.team = $Team[0]
                        } else {
                            $TaskFilters.Add([ScriptBlock]::Create("`$_.Team -in '$($Team -join "', '")'"))
                        }
                    }
                    'WS47' {
                        if ($Title.Count -eq 1) {
                            $RequestFilters.role = $Team[0]
                        } else {
                            $TaskFilters.Add([ScriptBlock]::Create("`$_.Team -in '$($Team -join "', '")'"))
                        }
                    }
                }
            }

            Write-Debug "Request Filters: $($RequestFilters -is [Hashtable] ? ($RequestFilters | ConvertTo-Json) : ($RequestFilters -join "`n"))"

            Write-Verbose "Requesting Tasks from TransitionManager"
            switch ($Endpoint) {
                'TMQL' {
                    $Tasks.AddRange((Get-FilteredTasksTMQL -Filters $RequestFilters))
                }
                'REST' {
                    $Tasks.AddRange((Get-FilteredTasksAPI -Filters $RequestFilters))
                }
                'WS50' {
                    $Tasks.AddRange((Get-FilteredTasksWS -Filters $RequestFilters))
                }
                'WS47' {
                    $Tasks.AddRange((Get-FilteredTasksWS -Filters $RequestFilters))
                }
            }
        }

        # Apply any necessary post-request filters to the tasks
        Write-Verbose "Applying additional filters to Tasks"
        Write-Debug "Task Filters:`n$($TaskFilters -join "`n")"
        if ($TaskFilters.Count -gt 0) {
            $FilteredTasks = $Tasks
            foreach ($Filter in $TaskFilters) {
                $FilteredTasks = $FilteredTasks | Where-Object -FilterScript $Filter
            }
            $Tasks = $FilteredTasks
        }

        # Web service and REST API don't return a TaskSpec
        if (($Tasks.Schema -contains 1) -and $TaskSpecId.Count -eq 1) {
            $Tasks | ForEach-Object { $_.TaskSpec = $TaskSpecId[0] }
        }

        $Tasks
    }
}


function Update-TMTask {
    <#
    .SYNOPSIS
    Updates a Task in TransitionManager
 
    .DESCRIPTION
    This function will update a Task in TransitionManager using a TMTask object that represents
    the desired changes
 
    .PARAMETER TMSession
    The name of the TM Session containing a TransitionManager connection
 
    .PARAMETER Task
    The TMTask object representing the required changes
 
    .PARAMETER Note
    A note to be added to the updated Task
 
    .PARAMETER Api
    Boolean indicating that REST API endpoints should be used in favor of web service endpoints
 
    .PARAMETER Passthru
    Switch indicating that the Task should be returned after being updated
 
    .EXAMPLE
    # Get an existing Task from TransitionManager
    $Task = Get-TMTask -TMSession TMAD50 -TaskNumber 1
 
    # Change the Action associated with the Task
    $Task.Action.Id = 175
 
    # Remove the user assignment
    $Task.AssignedTo.Id = 0
 
    # Set the Task's status to Pending
    $Task.Status = 'Pending'
 
    # Change the Asset associated with the Task
    $Task.Asset.Id = 232053
 
    # Use the updated TMTask object to commit the changes to TransitionManager
    Update-TMTask -TMSession TMAD50 -Task $Task
 
    .OUTPUTS
    If the Passthru switch was provided, then a TMTask object is returned. Otherwise, none
 
    .NOTES
    Below are the available Task properties that can be updated along with the associated
    TMTask property to be changed:
 
    Action: TMTask.Action.Id
    Asset: TMTask.Asset.Id
    Event: TMTask.Event.Id
    AssignedTo: TMTask.AssignedTo.Id
    Category: TMTask.Category
    Title: TMTask.Title
    HardAssigned: TMTask.HardAssigned
    InstructionsLink: TMTask.InstructionsLink
    PercentageComplete: TMTask.PercentageComplete
    Priority: TMTask.Priority
    Team: TMTask.Team
    Status: TMTask.Status
    SendNotification: TMTask.SendNotification
    Project: TMTask.Project.Id
    predecessors: TMTask.Predecessors
    successors: TMTask.Successors
    #>


    [CmdletBinding()]
    [Alias('Set-TMTask')]
    param(
        [Parameter(Mandatory = $false, Position = 0)]
        [String]$TMSession = "Default",

        [Parameter(Mandatory = $true,
            ValueFromPipeline = $true,
            ParameterSetName = 'ByObject')]
        [Alias('InputObject')]
        [TMTask]$Task,

        [Parameter(Mandatory = $false)]
        [String]$Status,

        [Parameter(Mandatory = $false)]
        [String]$Note,

        [Parameter(Mandatory = $false)]
        [Bool]$Api = $true,

        [Parameter(Mandatory = $false)]
        [Switch]$Passthru,

        [Parameter(Mandatory = $false)]
        [Switch]$UpdateTaskDependencies
    )


    begin {
        # Get the session configuration
        Write-Verbose "Checking for cached TMSession"
        $TMSessionConfig = $global:TMSessions[$TMSession]
        Write-Debug "TMSessionConfig:"
        Write-Debug ($TMSessionConfig | ConvertTo-Json -Depth 5)
        if (-not $TMSessionConfig) {
            throw "TMSession '$TMSession' not found. Use New-TMSession command before using features."
        }
    }

    process {
        if ($TMSessionConfig.TMRestSession -and $Api) {
            Write-Verbose "Using REST API endpoint"
            Write-Verbose "Forming web request parameters"
            $RestSplat = @{
                Uri                = "https://$($TMSessionConfig.TMServer)/tdstm/api/task/$($Task.Id)"
                Method             = 'PUT'
                WebSession         = $TMSessionConfig.TMRestSession
                SkipHttpErrorCheck = $true
                StatusCodeVariable = 'StatusCode'
                Body               = ($Task.GetApiUpdateObject($Note, $Status, $UpdateTaskDependencies.IsPresent) | ConvertTo-Json -Depth 3 -Compress)
            }

            Write-Debug "Web Request Parameters:"
            Write-Debug ($RestSplat | ConvertTo-Json -Depth 10)
            Write-Verbose "Invoking REST method"
            try {
                $Response = Invoke-RestMethod @RestSplat
                if ($StatusCode -in 200, 204) {
                    if ($Passthru) {
                        [TMTask]::new($Response)
                    }
                } elseif (-not [String]::IsNullOrWhiteSpace($Response)) {
                    throw $Response
                } else {
                    throw "The response status code $StatusCode does not indicate success."
                }
            } catch {
                throw "Error while updating task: $($_.Exception.Message)"
            }
        } else {
            Write-Verbose "Using web service endpoint"
            Write-Verbose "Forming web request parameters"
            $WebRequestSplat = @{
                Uri        = "https://$($TMSessionConfig.TMServer)/tdstm/ws/task/saveTask"
                Method     = 'POST'
                WebSession = $TMSessionConfig.TMWebSession
                Body       = ($Task.GetWSUpdateObject($UpdateTaskDependencies.IsPresent) | ConvertTo-Json -Compress)
            }
            Write-Debug "Web Request Parameters:"
            Write-Debug ($WebRequestSplat | ConvertTo-Json -Depth 10)
            Write-Verbose "Invoking web request"
            try {
                $Response = Invoke-WebRequest @WebRequestSplat
                Write-Debug "Response Content:"
                Write-Debug ($Response.Content | ConvertTo-Json -Depth 10)
                if ($Response.StatusCode -in 200, 204) {
                    if (-not [String]::IsNullOrWhiteSpace($Note)) {
                        Add-TMTaskNote -TMSession $TMSession -Id $Task.Id -Note $Note
                    }
                    if ($Passthru) {
                        try {
                            [TMTask]::new(($Response.Content | ConvertFrom-Json).data.assetComment)
                        } catch {
                            Write-Warning "Update was successful, but the updated Task could not be returned. Use Get-TMTask to retrieve the updated Task object."
                        }
                    }
                } else {
                    throw "Status code $($Response.StatusCode) does not indicate success"
                }
            } catch {
                throw "Error while updating task: $($_.Exception.Message)"
            }
        }
    }
}


function New-TMTask {
    <#
    .SYNOPSIS
    Creates a new Task in TransitionManager
 
    .DESCRIPTION
    This function will create a new Task in TransitionManager either by using the specified
    properties or by using a TMTask object
 
    .PARAMETER TMSession
    The name of the TM Session containing a TransitionManager connection
 
    .PARAMETER Task
    A TMTask object representing the new Task to be created
 
    .PARAMETER Title
    The title of the new Task
 
    .PARAMETER EventId
    The Id of the Event in which to place the new Task
 
    .PARAMETER ProjectId
    The Id of the TransitionManager project in which to place the new Task. If this is not provided,
    the project from the TMSession will be used
 
    .PARAMETER Status
    The status of the new Task
    Valid values are: Hold, Planned, Ready, Pending, Started, Completed, Terminated
 
    .PARAMETER Team
    The team to be assigned to the new Task
 
    .PARAMETER Priority
    The priority of the new Task
 
    .PARAMETER InstructionsLink
    The instructions link to place on the new Task
 
    .PARAMETER Duration
    The duration of the new task
 
    .PARAMETER SendNotification
    Indicates if the new Task should send notifications
 
    .PARAMETER Category
    The category of the new Task
 
    .PARAMETER AssignedToId
    The Id of the person that should be assigned to the new Task
 
    .PARAMETER AssetId
    The Id of the Asset to be associated with the new Task
 
    .PARAMETER ActionId
    The Id of the Action to be associated with the new Task
 
    .PARAMETER Predecessor
    One or more Task Ids that will be linked as a predecessor on the new Task
 
    .PARAMETER Successor
    One or more Task Ids that will be linked as a succecessor on the new Task
 
    .PARAMETER Note
    A note to be added to the new Task
 
    .PARAMETER Api
    Boolean indicating that REST API endpoints should be used in favor of web service endpoints
 
    .PARAMETER Passthru
    Switch indicating that the new Task should be returned after creation
 
    .EXAMPLE
    $NewTaskSplat = @{
        TMSession = "TMAD60"
        Title = "Test Task - w/ Dependencies"
        EventId = 460
        ProjectId = 6269
        Status = "Ready"
        Team = 'SYS_ADMIN'
        AssignedToId = 6246
        AssetId = 232053
        Successor = 369638, 411521
        Predecessor = 411702
        Note = "This was created via PowerShell"
        Passthru = $true
        ActionId = 178
    }
    New-TMTask @NewTaskSplat
 
    .EXAMPLE
    This example gets an existing task and then changes the associated Action
    and Title as well as removes all predecessors
 
    $Task = Get-TMTask -TMSession TMAD50 -Id $NewTask.id
    $Task.Action.Id = 177
    $Task.Title = "Copy of $($NewTask.TaskNumber)"
    $Task.Predecessors = @()
    New-TMTask -TMSession TMAD50 -Task $Task -Note "This task was created as a modified copy of $($Task.Id)"
 
 
    .OUTPUTS
    If the Passthru switch was provided, then a TMTask object is returned. Otherwise, none
    #>


    [CmdletBinding(DefaultParameterSetName = 'ByProperty')]
    param (
        [Parameter(Mandatory = $false, Position = 0)]
        [String]$TMSession = "Default",

        [Parameter(Mandatory = $true,
            ValueFromPipeline = $true,
            ParameterSetName = 'ByObject')]
        [Alias('InputObject')]
        [TMTask]$Task,

        [Parameter(Mandatory = $true,
            ParameterSetName = 'ByProperty')]
        [String]$Title,

        [Parameter(Mandatory = $true,
            ParameterSetName = 'ByProperty')]
        [Int]$EventId,

        [Parameter(Mandatory = $false,
            ParameterSetName = 'ByProperty')]
        [Nullable[Int]]$ProjectId,

        [Parameter(Mandatory = $false,
            ParameterSetName = 'ByProperty')]
        [ArgumentCompleter( { [TMTask]::ValidStatuses } )]
        [ValidateScript( { $_ -in [TMTask]::ValidStatuses } )]
        [String]$Status = 'Pending',

        [Parameter(Mandatory = $false,
            ParameterSetName = 'ByProperty')]
        [String]$Team,

        [Parameter(Mandatory = $false,
            ParameterSetName = 'ByProperty')]
        [ValidateRange(1, 5)]
        [Int]$Priority = 3,

        [Parameter(Mandatory = $false,
            ParameterSetName = 'ByProperty')]
        [String]$InstructionsLink,

        [Parameter(Mandatory = $false,
            ParameterSetName = 'ByProperty')]
        [Int]$Duration = 0,

        [Parameter(Mandatory = $false,
            ParameterSetName = 'ByProperty')]
        [Bool]$SendNotification = $false,

        [Parameter(Mandatory = $false,
            ParameterSetName = 'ByProperty')]
        [ArgumentCompleter( { [TMTask]::ValidCategories } )]
        [ValidateScript( { $_ -in [TMTask]::ValidCategories } )]
        [String]$Category = 'general',

        [Parameter(Mandatory = $false,
            ParameterSetName = 'ByProperty')]
        [Int]$AssignedToId,

        [Parameter(Mandatory = $false,
            ParameterSetName = 'ByProperty')]
        [Int]$AssetId,

        [Parameter(Mandatory = $false,
            ParameterSetName = 'ByProperty')]
        [Int]$ActionId,

        [Parameter(Mandatory = $false,
            ParameterSetName = 'ByProperty')]
        [Int[]]$Predecessor,

        [Parameter(Mandatory = $false,
            ParameterSetName = 'ByProperty')]
        [Int[]]$Successor,

        [Parameter(Mandatory = $false)]
        [String]$Note,

        [Parameter(Mandatory = $false)]
        [Bool]$Api = $true,

        [Parameter(Mandatory = $false)]
        [Switch]$Passthru
    )


    begin {

        # Get the session configuration
        Write-Verbose "Checking for cached TMSession"
        $TMSessionConfig = $global:TMSessions[$TMSession]
        Write-Debug "TMSessionConfig:"
        Write-Debug ($TMSessionConfig | ConvertTo-Json -Depth 5)
        if (-not $TMSessionConfig) {
            throw "TMSession '$TMSession' not found. Use New-TMSession command before using features."
        }

        # Use the TM session if a project id is not provided
        $ProjectId ??= $TMSessionConfig.UserContext.Project.id
    }

    process {
        if ($PSCmdlet.ParameterSetName -eq 'ByObject') {
            $Title = $Task.Title
            $EventId = $Task.Event.Id
            $ProjectId = $Task.Project.Id
            $Status = $Task.Status
            $Team = $Task.Team
            $Priority = $Task.Priority
            $InstructionsLink = $Task.InstructionsLink
            $Category = $Task.Category
            $AssignedToId = $Task.AssignedTo.Id
            $AssetId = $Task.Asset.Id
            $ActionId = $Task.Action.Id
            $Predecessor = $Task.Predecessors.TaskId
            $Successor = $Task.Successors.TaskId
            $SendNotification = $Task.SendNotification
            $Duration = $Task.Duration
        }

        if ($TMSessionConfig.TMRestSession -and $Api) {
            Write-Verbose "Using REST API endpoint"

            Write-Verbose "Forming web request body"
            $Body = @{
                title            = $Title
                event            = @{ id = $EventId }
                project          = $ProjectId
                status           = $Status
                priority         = $Priority
                category         = $Category
                action           = @{ id = $ActionId }
                role             = $Team
                duration         = $Duration
                instructionsLink = $InstructionsLink
                assignedTo       = $AssignedToId
                asset            = @{ id = $AssetId }
                note             = $Note
                sendNotification = $SendNotification ? 1 : 0
                predecessors     = @()
                successors       = @()
            }
            if ($null -ne $Predecessor) {
                $Predecessor | ForEach-Object {
                    $Body.predecessors += @{
                        id     = -1
                        taskId = $_
                    }
                }
            }
            if ($null -ne $Successor) {
                $Successor | ForEach-Object {
                    $Body.successors += @{
                        id     = -1
                        taskId = $_
                    }
                }
            }
            Write-Verbose "Forming web request parameters"
            $RestSplat = @{
                Uri        = "https://$($TMSessionConfig.TMServer)/tdstm/api/task"
                Method     = 'POST'
                WebSession = $TMSessionConfig.TMRestSession
                Body       = ($Body | ConvertTo-Json -Compress)
            }
            Write-Debug "Web Request Parameters:"
            Write-Debug ($RestSplat | ConvertTo-Json -Depth 10)
            Write-Verbose "Invoking REST method"
            try {
                $Response = Invoke-RestMethod @RestSplat
                if ($Passthru) {
                    [TMTask]::new($Response)
                }
            } catch {
                throw "Error while setting task status to $($Status): $($_.Exception.Message)"
            }
        } else {
            Write-Verbose "Using web service endpoint"
            $Body = @{
                comment          = $Title
                status           = $Status
                assignedTo       = $AssignedToId
                apiAction        = $ActionId
                apiActionId      = $ActionId
                category         = $Category
                assetEntity      = $AssetId
                moveEvent        = $EventId
                priority         = $Priority
                role             = $Team
                sendNotification = $SendNotification ? 1 : 0
                instructionsLink = $InstructionsLink
                duration         = $Duration
                durationScale    = "M"
                durationLocked   = 0
                manageDependency = 0
                taskDependency   = @()
                taskSuccessor    = @()
            }

            if ($null -ne $Predecessor) {
                $Predecessor | ForEach-Object {
                    $Body.taskDependency += "-1_$($_)"
                }
                $Body.manageDependency = 1
            }
            if ($null -ne $Successor) {
                $Successor | ForEach-Object {
                    $Body.taskSuccessor += "-1_$($_)"
                }
                $Body.manageDependency = 1
            }

            Write-Verbose "Forming web request parameters"
            $WebRequestSplat = @{
                Uri        = "https://$($TMSessionConfig.TMServer)/tdstm/ws/task/saveTask"
                Method     = 'POST'
                WebSession = $TMSessionConfig.TMWebSession
                Body       = ($Body | ConvertTo-Json -Compress)
            }
            Write-Debug "Web Request Parameters:"
            Write-Debug ($WebRequestSplat | ConvertTo-Json -Depth 10)
            Write-Verbose "Invoking web request"
            try {
                $Response = Invoke-WebRequest @WebRequestSplat
                Write-Debug "Response Content:"
                Write-Debug ($Response.Content | ConvertTo-Json -Depth 10)
                if ($Response.StatusCode -in 200, 204) {
                    if ($Passthru) {
                        try {
                            [TMTask]::new(($Response.Content | ConvertFrom-Json).data.assetComment)
                        } catch {
                            Write-Warning "Update was successful, but the updated Task could not be returned. Use Get-TMTask to retrieve the updated Task object."
                        }
                    }
                } else {
                    throw "Status code $($Response.StatusCode) does not indicate success"
                }
            } catch {
                throw "Error while setting task status to $($Status): $($_.Exception.Message)"
            }
        }
    }
}


function Remove-TMTask {
    <#
    .SYNOPSIS
    Deletes a Task from TransitionManager
 
    .DESCRIPTION
    This function will delete one or more of the specified Tasks from TransitionManager
 
    .PARAMETER TMSession
    The name of the TM Session containing a TransitionManager connection
 
    .PARAMETER Id
    The Id of the task to be deleted
 
    .PARAMETER Api
    Boolean indicating that REST API endpoints should be used in favor of web service endpoints
 
    .EXAMPLE
    Remove-TMTask -Id 587434
 
    .EXAMPLE
    Get-TMTask -Id 129874, 458696 | Remove-TMTask
 
    .OUTPUTS
    None
    #>


    [CmdletBinding()]
    param (
        [Parameter(Mandatory = $false, Position = 0)]
        [String]$TMSession = "Default",

        [Parameter(Mandatory = $true,
            Position = 1,
            ValueFromPipeline = $true,
            ValueFromPipelineByPropertyName = $true)]
        [Int[]]$Id,

        [Parameter(Mandatory = $false)]
        [Bool]$Api = $false
    )

    begin {
        # Get the session configuration
        Write-Verbose "Checking for cached TMSession"
        $TMSessionConfig = $global:TMSessions[$TMSession]
        Write-Debug "TMSessionConfig:"
        Write-Debug ($TMSessionConfig | ConvertTo-Json -Depth 5)
        if (-not $TMSessionConfig) {
            throw "TMSession '$TMSession' not found. Use New-TMSession command before using features."
        }
    }

    process {
        if ($TMSessionConfig.TMRestSession -and $Api) {
            Write-Verbose "Using REST API endpoint"
            foreach ($TaskId in $Id) {
                Write-Verbose "Forming web request parameters"
                $RestSplat = @{
                    Uri        = "https://$($TMSessionConfig.TMServer)/tdstm/api/task/$($Id)"
                    Method     = 'DELETE'
                    WebSession = $TMSessionConfig.TMRestSession
                }
                Write-Debug "Web Request Parameters:"
                Write-Debug ($RestSplat | ConvertTo-Json -Depth 10)
                Write-Verbose "Invoking REST method"
                try {
                    $Response = Invoke-RestMethod @RestSplat
                    Write-Debug "Response:"
                    Write-Debug ($Response | ConvertTo-Json -Depth 10)
                } catch {
                    throw "Error while deleting task: $($_.Exception.Message)"
                }
            }
        } else {
            Write-Verbose "Using web service endpoint"
            Write-Verbose "Forming web request parameters"
            $WebRequestSplat = @{
                Uri        = "https://$($TMSessionConfig.TMServer)/tdstm/ws/asset/comment/$($Id)"
                Method     = 'DELETE'
                WebSession = $TMSessionConfig.TMWebSession
            }
            Write-Debug "Web Request Parameters:"
            Write-Debug ($WebRequestSplat | ConvertTo-Json -Depth 10)
            Write-Verbose "Invoking web request"
            try {
                $Response = Invoke-WebRequest @WebRequestSplat
                Write-Debug "Response Content:"
                Write-Debug ($Response.Content | ConvertTo-Json -Depth 10)
                if ($Response.StatusCode -notin 200, 204) {
                    throw "Status code $($Response.StatusCode) does not indicate success"
                }
            } catch {
                throw "Error while updating task: $($_.Exception.Message)"
            }
        }
    }
}


function Set-TMTaskStatus {
    <#
    .SYNOPSIS
    Sets the status of a TransitionManager Task
 
    .DESCRIPTION
    This function will set/update the status of the specified Task in TransitionManager
 
    .PARAMETER TMSession
    The name of the TM Session containing a TransitionManager connection
 
    .PARAMETER Id
    The Id of Task on which the status will be set
 
    .PARAMETER Status
    The new status to set on the task
    Valid values are: Hold, Planned, Ready, Pending, Started, Completed, Terminated
 
    .PARAMETER ProjectId
    The Id of the TransitionManager project. If this is not provided,
    the project from the TMSession will be used
 
    .PARAMETER Api
    Boolean indicating that REST API endpoints should be used in favor of web service endpoints
 
    .EXAMPLE
    Set-TMTaskStatus -TMSession TMAD50 -Id 411521 -Status Ready
 
    .EXAMPLE
    Get-TMTask -TaskNumber 189, 2569 | Set-TMTaskStatus -Status Ready
 
    .OUTPUTS
    None
    #>


    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $false, Position = 0)]
        [String]$TMSession = "Default",

        [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)]
        [Alias('TaskId')]
        [Int]$Id,

        [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)]
        [ArgumentCompleter({ [TMTask]::ValidStatuses })]
        [ValidateScript( { $_ -in [TMTask]::ValidStatuses } )]
        [Alias('State')]
        [String]$Status,

        [Parameter(Mandatory = $false)]
        [AllowNull()]
        [Alias('Project')]
        [Nullable[Int]]$ProjectId,

        [Parameter(Mandatory = $false)]
        [Bool]$Api = $true
    )

    begin {
        # Get the session configuration
        Write-Verbose "Checking for cached TMSession"
        $TMSessionConfig = $global:TMSessions[$TMSession]
        Write-Debug "TMSessionConfig:"
        Write-Debug ($TMSessionConfig | ConvertTo-Json -Depth 5)
        if (-not $TMSessionConfig) {
            throw "TMSession '$TMSession' not found. Use New-TMSession command before using features."
        }

        # Use the TM session if a project id is not provided
        $ProjectId ??= $TMSessionConfig.UserContext.Project.id
    }

    process {
        if ($TMSessionConfig.TMRestSession -and $Api) {
            Write-Verbose "Using REST API endpoint"
            Write-Verbose "Forming web request parameters"
            $RestSplat = @{
                Uri        = "https://$($TMSessionConfig.TMServer)/tdstm/api/task/$($Id)/updateStatus?status=$Status&project=$ProjectId"
                Method     = 'POST'
                WebSession = $TMSessionConfig.TMRestSession
            }
            Write-Debug "Web Request Parameters:"
            Write-Debug ($RestSplat | ConvertTo-Json -Depth 10)
            Write-Verbose "Invoking REST method"
            try {
                $Response = Invoke-RestMethod @RestSplat
                Write-Debug "Response:"
                Write-Debug ($Response | ConvertTo-Json -Depth 10)
            } catch {
                throw "Error while setting task status to $($Status): $($_.Exception.Message)"
            }
        } else {
            Write-Verbose "Using web service endpoint"
            Write-Verbose "Forming web request parameters"
            $WebRequestSplat = @{
                Uri        = "https://$($TMSessionConfig.TMServer)/tdstm/assetEntity/updateComment"
                Method     = 'POST'
                WebSession = $TMSessionConfig.TMWebSession
                Body       = (@{
                        id     = $Id
                        status = $Status
                    } | ConvertTo-Json -Compress)
            }
            Write-Debug "Web Request Parameters:"
            Write-Debug ($WebRequestSplat | ConvertTo-Json -Depth 10)
            Write-Verbose "Invoking web request"
            try {
                $Response = Invoke-WebRequest @WebRequestSplat
                Write-Debug "Response Content:"
                Write-Debug ($Response.Content | ConvertTo-Json -Depth 10)
                if ($Response.StatusCode -notin 200, 204) {
                    throw "Status code $($Response.StatusCode) does not indicate success"
                }
            } catch {
                throw "Error while setting task status to $($Status): $($_.Exception.Message)"
            }
        }
    }
}


function Add-TMTaskNote {
    <#
    .SYNOPSIS
    Adds a note to the specified Task
 
    .DESCRIPTION
    This function will add the specified note to a TransitionManager Task
 
    .PARAMETER TMSession
    The name of the TM Session containing a TransitionManager connection
 
    .PARAMETER Id
    The Id of the Task to which the note should be added
 
    .PARAMETER Note
    The note to be added
 
    .PARAMETER ProjectId
    The Id of the TransitionManager project. If this is not provided,
    the project from the TMSession will be used
 
    .PARAMETER Api
    Boolean indicating that REST API endpoints should be used in favor of web service endpoints
 
    .EXAMPLE
    Add-TMTaskNote -TMSession TMAD50 -Id 12356 -Note "This task was updated via PowerShell"
 
    .OUTPUTS
    None
    #>


    [CmdletBinding()]
    param (
        [Parameter(Mandatory = $false, Position = 0)]
        [String]$TMSession = "Default",

        [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)]
        [Alias('TaskId')]
        [Int]$Id,

        [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)]
        [String]$Note,

        [Parameter(Mandatory = $false)]
        [AllowNull()]
        [Alias('Project')]
        [Nullable[Int]]$ProjectId,

        [Parameter(Mandatory = $false)]
        [Bool]$Api = $false
    )

    begin {
        # Get the session configuration
        Write-Verbose "Checking for cached TMSession"
        $TMSessionConfig = $global:TMSessions[$TMSession]
        Write-Debug "TMSessionConfig:"
        Write-Debug ($TMSessionConfig | ConvertTo-Json -Depth 5)
        if (-not $TMSessionConfig) {
            throw "TMSession '$TMSession' not found. Use New-TMSession command before using features."
        }

        # Use the TM session if a project id is not provided
        $ProjectId ??= $TMSessionConfig.UserContext.Project.id
    }

    process {
        if ($TMSessionConfig.TMRestSession -and $Api) {
            Write-Verbose "Using REST API endpoint"
            Write-Verbose "Forming web request parameters"
            $RestSplat = @{
                Uri        = "https://$($TMSessionConfig.TMServer)/tdstm/api/task/$($Id)/addNote"
                Method     = 'POST'
                Body       = (@{
                        note    = $Note
                        project = $ProjectId
                    } | ConvertTo-Json)
                WebSession = $TMSessionConfig.TMRestSession
            }
            Write-Debug "Web Request Parameters:"
            Write-Debug ($RestSplat | ConvertTo-Json -Depth 10)
            Write-Verbose "Invoking REST method"
            try {
                $Response = Invoke-RestMethod @RestSplat
                Write-Debug "Response:"
                Write-Debug ($Response | ConvertTo-Json -Depth 10)
            } catch {
                throw "Error while adding task note: $($_.Exception.Message)"
            }
        } else {
            Write-Verbose "Using web service endpoint"
            Write-Verbose "Forming web request parameters"
            $WebRequestSplat = @{
                Uri        = "https://$($TMSessionConfig.TMServer)/tdstm/ws/task/$($Id)/addNote"
                Method     = 'POST'
                Body       = (@{
                        note = $Note
                    } | ConvertTo-Json)
                WebSession = $TMSessionConfig.TMWebSession
                ContentType = 'application/json'
            }
            Write-Debug "Web Request Parameters:"
            Write-Debug ($WebRequestSplat | ConvertTo-Json -Depth 10)
            Write-Verbose "Invoking web request"
            try {
                $Response = Invoke-WebRequest @WebRequestSplat
                Write-Debug "Response Content:"
                Write-Debug ($Response.Content | ConvertTo-Json -Depth 10)
                if ($Response.StatusCode -notin 200, 204) {
                    throw "Status code $($Response.StatusCode) does not indicate success"
                }
            } catch {
                throw "Error while adding task note: $($_.Exception.Message)"
            }
        }
    }
}