PSSnow

1.3.1

Private/Invoke-SNOWTableREAD.ps1

function Invoke-SNOWTableREAD {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory)]
        [hashtable]
        $Parameters,
        [Parameter(Mandatory)]
        [string]
        $Table,
        [Parameter()]
        [int]
        #Default pagination value
        $PaginationAmount = 1000
    )
    
    BEGIN {
        $EnablePagination = $True
        $BaseURL = "https://$($script:SNOWAuth.instance).service-now.com/api/now/v2/table/$Table"
        $DefaultParameterList = Import-DefaultParamSet -TemplateFunction "Get-SNOWObject" -AsStringArray -IncludeCommon
        $Parameters = Format-Hashtable -Hashtable $Parameters -KeysToLowerCase
        $QueryParameters = $Parameters.GetEnumerator() | Where-Object {$_.Key -notin $DefaultParameterList}

        $Results = [System.Collections.ArrayList]@()
    }
    
    PROCESS {
        #? Lookup type
        if($Parameters.ContainsKey('sys_id')){
            #Direct Record
            $URI = "$BaseURL/$($Parameters.sys_id)?"
        }elseif($Parameters.ContainsKey('number')){
            #For example, a RITM, Incident or Task number.
            $URI = "$BaseURL`?sysparm_query=number=$($Parameters.number)"
        }elseif($Parameters.ContainsKey('query')){
            #String queries that can be copied directly from SNOW
            $URI = "$BaseURL`?sysparm_query=$($Parameters.query)"
        }else{
            #Queries that are generated by the parameters supplied on the inherited function (if any)
            $URI = ConvertTo-QueryString -BaseURL $BaseURL -QueryParameters $QueryParameters
        }
        
        #? Additional query modifiers
        Switch ($Parameters.Keys){
            "fields"                { $URI = "$URI&sysparm_fields=$($Parameters.fields.ToLower() -join ',')" }
            "displayvalue"          { $URI = "$URI&sysparm_display_value=$($Parameters.displayvalue)" }
            "excludereferencelinks" { $URI = "$URI&sysparm_exclude_reference_link=$($Parameters.excludereferencelinks)" }
            "RestrictDomain"        { $URI = "$URI&sysparm_query_no_domain=$($Parameters.RestrictDomain.ToString().ToLower())" }
            "SysParmView"           { $URI = "$URI&sysparm_view=$($Parameters.SysParmView.ToString().ToLower())" }
            "limit" {
                if($Parameters.limit -le $PaginationAmount){
                    $EnablePagination = $False
                    $PaginationAmount = $Parameters.limit
                }
            }
            "offset" {
                $EnablePagination = $False
                $URI              = "$URI&sysparm_offset=$($Parameters.offset)"
            }
        }

        #? Always apply the limit (Default pagination or user defined)
        $URI = "$URI&sysparm_limit=$PaginationAmount"   

        #Not included properties:
        # sysparm_no_count - covered with Get-SNOWStats
        # sysparm_query_category - not sure what the use case would be for this, haven't included it
        # sysparm_suppress_pagination_header - Again, I can't see a use case so omitting for now

        #? API Call
        try{
            if($EnablePagination){
                if($Parameters.ContainsKey('limit')){
                    For($Offset = 0; $Offset -lt $Parameters.limit; $Offset+=$PaginationAmount){
                        if($PSVersionTable.PSEdition -eq "Core" -and $VerbosePreference -eq "Continue"){
                            Write-Verbose "$URI&sysparm_offset=$Offset"
                        }
                        #Last time I did similar with rel links in core, [https://github.com/ashscode] noticed they did not work so I haven't bothered to try replicate that method yet.
                        $Response = (Invoke-SNOWWebRequest -UseRestMethod -URI "$URI&sysparm_offset=$Offset" -Method GET).Result
                        [void]$Results.Add($Response)
                    }
                    $Results = @($Results | ForEach-Object {$_}) | Select-Object -first $Parameters.limit
                }else{
                    $Offset = 0
                    Do{
                        if($PSVersionTable.PSEdition -eq "Core" -and $VerbosePreference -eq "Continue"){
                            Write-Verbose "$URI&sysparm_offset=$Offset"
                        }
                        $Response = Invoke-SNOWWebRequest -URI "$URI&sysparm_offset=$Offset" -Method GET
                        [void]$Results.Add(($Response.content | ConvertFrom-Json).Result)
                        $Offset += $PaginationAmount
                    }While($Response.Headers.Link -like "*rel=`"next`"*")
                    $Results = @($Results | ForEach-Object {$_})
                }
            }else{
                if($PSVersionTable.PSEdition -eq "Core" -and $VerbosePreference -eq "Continue"){
                    Write-Verbose $URI
                }
                $Results = (Invoke-SNOWWebRequest -UseRestMethod -URI $URI -Method GET).Result
            }            

            Return $Results
        }catch{
            Write-Error "$($_.Exception.Message) [$URI]"
        }
    }
}