Public/Get-ServiceNowRecord.ps1

<#
.SYNOPSIS
    Retrieves records for the specified table
 
.DESCRIPTION
    Retrieve records from any table with the option to filter, sort, and choose fields.
    Given you know the table name, you shouldn't need any other 'Get-' function.
    Paging is supported with -First, -Skip, and -IncludeTotalCount.
 
.PARAMETER Table
    Name of the table to be queried, by either table name or class name
 
.PARAMETER Properties
    Limit the fields returned to this list
 
.PARAMETER Filter
    Array or multidimensional array of fields and values to filter on.
    Each array should be of the format @(field, comparison operator, value) separated by a join, either 'and', 'or', or 'group'.
    For a complete list of comparison operators, see $script:ServiceNowOperator and use Name in your filter.
    See the examples.
    Also, see https://docs.servicenow.com/bundle/quebec-platform-user-interface/page/use/common-ui-elements/reference/r_OpAvailableFiltersQueries.html
    for how to represent date values with javascript.
 
.PARAMETER Sort
    Array or multidimensional array of fields to sort on.
    Each array should be of the format @(field, asc/desc).
 
.PARAMETER DisplayValues
    Option to display values for reference fields.
    'false' will only retrieve the reference
    'true' will only retrieve the underlying value
    'all' will retrieve both. This is helpful when trying to translate values for a query.
 
.PARAMETER Connection
    Azure Automation Connection object containing username, password, and URL for the ServiceNow instance
 
.PARAMETER ServiceNowSession
    ServiceNow session created by New-ServiceNowSession. Will default to script-level variable $ServiceNowSession.
 
.EXAMPLE
    Get-ServiceNowRecord -Table incident -Filter @('state', '-eq', '1'), 'or', @('short_description','-like', 'powershell')
    Get incident records where state equals New or short description contains the word powershell
 
.EXAMPLE
    $filter = @('state', '-eq', '1'),
                'and',
              @('short_description','-like', 'powershell'),
                'group',
              @('state', '-eq', '2')
    PS > Get-ServiceNowRecord -Table incident -Filter $filter
    Get incident records where state equals New and short description contains the word powershell or state equals In Progress.
    The first 2 filters are combined and then or'd against the last.
 
.EXAMPLE
    Get-ServiceNowRecord -Table incident -Filter @('state', '-eq', '1') -Sort @('opened_at', 'desc'), @('state')
    Get incident records where state equals New and first sort by the field opened_at descending and then sort by the field state ascending
 
.EXAMPLE
    Get-ServiceNowRecord -Table 'change request' -Filter @('opened_at', '-ge', 'javascript:gs.daysAgoEnd(30)')
    Get change requests opened in the last 30 days. Use class name as opposed to table name.
 
.EXAMPLE
    Get-ServiceNowRecord -Table 'change request' -First 100 -IncludeTotalCount
    Get all change requests, paging 100 at a time.
 
.INPUTS
    None
 
.OUTPUTS
    System.Management.Automation.PSCustomObject
 
.LINK
    https://docs.servicenow.com/bundle/quebec-platform-user-interface/page/use/common-ui-elements/reference/r_OpAvailableFiltersQueries.html
#>

function Get-ServiceNowRecord {

    [OutputType([System.Management.Automation.PSCustomObject])]
    [CmdletBinding(DefaultParameterSetName = 'SessionFilter', SupportsPaging)]

    Param (
        [parameter(Mandatory)]
        [Alias('sys_class_name')]
        [string] $Table,

        [Parameter()]
        [Alias('Fields')]
        [string[]] $Properties,

        [parameter(ParameterSetName = 'AutomationFilter')]
        [parameter(ParameterSetName = 'SessionFilter')]
        [System.Collections.ArrayList] $Filter,

        [parameter(ParameterSetName = 'AutomationFilter')]
        [parameter(ParameterSetName = 'SessionFilter')]
        [ValidateNotNullOrEmpty()]
        [System.Collections.ArrayList] $Sort,

        [Parameter()]
        [ValidateSet('true', 'false', 'all')]
        [string] $DisplayValues = 'true',

        [Parameter(Mandatory, ParameterSetName = 'AutomationQuery')]
        [parameter(Mandatory, ParameterSetName = 'AutomationFilter')]
        [ValidateNotNullOrEmpty()]
        [hashtable] $Connection,

        [Parameter(ParameterSetName = 'SessionQuery')]
        [Parameter(ParameterSetName = 'SessionFilter')]
        [ValidateNotNullOrEmpty()]
        [hashtable] $ServiceNowSession = $script:ServiceNowSession
    )

    $result = Invoke-ServiceNowRestMethod @PSBoundParameters

    If ( $result -and -not $Properties) {
        $type = $script:ServiceNowTable | Where-Object {$_.Name -eq $Table -or $_.ClassName -eq $Table} | Select-Object -ExpandProperty Type
        if ($type) {
            $result | ForEach-Object { $_.PSObject.TypeNames.Insert(0, $type) }
        }
    }

    $result
}