11<#
22. SYNOPSIS
3- Retrieves records for the specified table
3+ Retrieves records for any and all tables
44
55. DESCRIPTION
6- Retrieve records from any table with the option to filter, sort, and choose fields.
7- Given you know the table name, you shouldn't need any other 'Get-' function.
6+ Retrieve records from any table with the option to filter, sort, choose fields, and more.
87 Paging is supported with -First, -Skip, and -IncludeTotalCount.
98
109. PARAMETER Table
1514 Either the record sys_id or number.
1615 If providing just an Id, not with Table, the Id prefix will be looked up to find the table name.
1716
18- . PARAMETER Name
17+ . PARAMETER ParentId
18+ The sys_id or number of the parent record.
19+ For example, to get catalog tasks for a requested item, provide the RITM number as ParentId.
20+
21+ . PARAMETER Description
22+ Filter results based on the 'description' field. The field will be different for each table.
23+ For many tables it will be short_description, but, for instance, the User table will be 'Name'.
24+ For unknown tables, the field will be 'short_description'.
25+ The comparison performed is a 'like'.
1926
2027. PARAMETER Property
21- Limit the fields returned to this list
28+ Return one or more specific fields
2229
2330. PARAMETER Filter
2431 Array or multidimensional array of fields and values to filter on.
5158 ServiceNow session created by New-ServiceNowSession. Will default to script-level variable $ServiceNowSession.
5259
5360. EXAMPLE
54- Get-ServiceNowRecord -Table incident -Filter @('state', '-eq', '1'), 'or', @('short_description','-like', 'powershell')
61+ Get-ServiceNowRecord RITM0010001
62+ Get a specific record by number
63+
64+ . EXAMPLE
65+ Get-ServiceNowRecord -Id RITM0010001 -Property 'short_description','sys_id'
66+ Get specific properties for a record
67+
68+ . EXAMPLE
69+ Get-ServiceNowRecord -Table 'Catalog Task' -ParentId 'RITM0010001'
70+ Get tasks for the parent requested item
71+
72+ . EXAMPLE
73+ Get-ServiceNowRecord -Table incident -Filter @('state', '-eq', '1') -Description 'powershell'
5574 Get incident records where state equals New or short description contains the word powershell
5675
5776. EXAMPLE
6180 '-group',
6281 @('state', '-eq', '2')
6382 PS > Get-ServiceNowRecord -Table incident -Filter $filter
64- Get incident records where state equals New and short description contains the word powershell or state equals In Progress.
83+ Get incident records where state is New and short description contains the word powershell or state is In Progress.
6584 The first 2 filters are combined and then or'd against the last.
6685
6786. EXAMPLE
8099 Get-ServiceNowRecord -Table 'change request' -IncludeCustomVariable -First 5
81100 Get the first 5 change requests and retrieve custom variable info
82101
102+ . EXAMPLE
103+ gsnr RITM0010001
104+ Get a specific record by number using the function alias
105+
83106. INPUTS
84107 None
85108
@@ -106,7 +129,10 @@ function Get-ServiceNowRecord {
106129 [string ] $Id ,
107130
108131 [Parameter ()]
109- [string ] $Name ,
132+ [string ] $ParentId ,
133+
134+ [Parameter ()]
135+ [string ] $Description ,
110136
111137 [Parameter ()]
112138 [Alias (' Fields' , ' Properties'
@@ -134,52 +160,84 @@ function Get-ServiceNowRecord {
134160 [hashtable ] $ServiceNowSession = $script :ServiceNowSession
135161 )
136162
137- # it's easier this way to pass everything to invoke-servicenowrestmethod given paging params, etc
138- $invokeParams = $PSBoundParameters
139- $invokeParams.Remove (' IncludeCustomVariable' | Out-Null
140- $invokeParams.Remove (' Id' | Out-Null
141- $invokeParams.Remove (' Name' | Out-Null
163+ $invokeParams = @ {
164+ Table = $Table
165+ Filter = $Filter
166+ Property = $Property
167+ Sort = $Sort
168+ DisplayValue = $DisplayValue
169+ First = $PSCmdlet.PagingParameters.First
170+ Skip = $PSCmdlet.PagingParameters.Skip
171+ IncludeTotalCount = $PSCmdlet.PagingParameters.IncludeTotalCount
172+ Connection = $Connection
173+ ServiceNowSession = $ServiceNowSession
174+ }
142175
143176 if ( $Id ) {
144177 if ( $Id -match ' [a-zA-Z0-9]{32}'
145- if ( $PSCmdlet.ParameterSetName -like ' * Id'
146- throw ' Providing sys_id for -Id requires a value for -Table. Alternatively, provide an Id with a prefix, eg. INC1234567.'
178+ if ( $PSCmdlet.ParameterSetName -eq ' Id'
179+ throw ' Providing sys_id for -Id requires a value for -Table. Alternatively, provide an Id with a prefix, eg. INC1234567, and the table will be automatically determined .'
147180 }
148181
149182 $idFilter = @ (' sys_id' , ' -eq' , $Id )
150183 }
151184 else {
152- if ( $PSCmdlet.ParameterSetName -like ' * Id'
185+ if ( $PSCmdlet.ParameterSetName -eq ' Id'
153186 # get table name from prefix if only Id was provided
154- $thisTable = $script :ServiceNowTable | Where-Object { $_.NumberPrefix -and $Id.ToLower ().StartsWith($_.NumberPrefix ) } | Select-Object - ExpandProperty Name
187+ $thisTable = $script :ServiceNowTable | Where-Object { $_.NumberPrefix -and $Id.ToLower ().StartsWith($_.NumberPrefix ) }
155188 if ( $thisTable ) {
156- $invokeParams.Table = $thisTable
189+ $invokeParams.Table = $thisTable.Name
157190 }
158191 else {
159- throw (' Prefix not found for Id '' {0}'' . Known prefixes are {1}.' -f $Id , ($ServiceNowTable.NumberPrefix.Where ( { $_ }) -join ' , '
192+ throw (' The prefix for Id '' {0}'' was not found and the appropriate table cannot be determined . Known prefixes are {1}. Please provide a value for -Table .' -f $Id , ($ServiceNowTable.NumberPrefix.Where ( { $_ }) -join ' , '
160193 }
161194 }
162195 $idFilter = @ (' number' , ' -eq' , $Id )
163196 }
164197
165- if ( $invokeParmas .Filter ) {
198+ if ( $invokeParams .Filter ) {
166199 $invokeParams.Filter = $invokeParams.Filter , ' and' , $idFilter
167200 }
168201 else {
169202 $invokeParams.Filter = $idFilter
170203 }
171204 }
205+ else {
206+ # table name was provided, get the config entry if there is one
207+ $thisTable = $script :ServiceNowTable | Where-Object { $_.Name.ToLower () -eq $Table.ToLower () -or $_.ClassName.ToLower () -eq $Table.ToLower () }
208+ }
172209
173- if ( $Name ) {
174- # determine the field we should compare for 'name' and add the filter
175- $thisNameField = $script :ServiceNowTable | Where-Object { $_.Name.ToLower () -eq $Table.ToLower () -or $_.ClassName.ToLower () -eq $Table.ToLower () } | Select-Object - ExpandProperty TableNameField
176- if ( $thisNameField ) {
177- if ( $invokeParmas.Filter ) {
178- $invokeParams.Filter = $invokeParams.Filter , ' and' , @ ($thisNameField , ' -like' , $Name )
179- }
180- else {
181- $invokeParams.Filter = @ ($thisNameField , ' -like' , $Name )
182- }
210+ if ( $ParentId ) {
211+ if ( $ParentId -match ' [a-zA-Z0-9]{32}'
212+ $parentIdFilter = @ (' parent.sys_id' , ' -eq' , $ParentId )
213+ }
214+ else {
215+ $parentIdFilter = @ (' parent.number' , ' -eq' , $ParentId )
216+ }
217+
218+ if ( $invokeParams.Filter ) {
219+ $invokeParams.Filter = $invokeParams.Filter , ' and' , $parentIdFilter
220+ }
221+ else {
222+ $invokeParams.Filter = $parentIdFilter
223+ }
224+ }
225+
226+ if ( $Description ) {
227+ # determine the field we should compare for 'description' and add the filter
228+ if ( $thisTable ) {
229+ $nameFilter = @ ($thisTable.DescriptionField , ' -like' , $Description )
230+ }
231+ else {
232+ Write-Warning (' We do not have a description field for table '' {0}'' ; short_description will be used' -f $Table )
233+ $nameFilter = @ (' short_description' , ' -like' , $Description )
234+ }
235+
236+ if ( $invokeParams.Filter ) {
237+ $invokeParams.Filter = $invokeParams.Filter , ' and' , $nameFilter
238+ }
239+ else {
240+ $invokeParams.Filter = $nameFilter
183241 }
184242 }
185243
@@ -193,6 +251,7 @@ function Get-ServiceNowRecord {
193251 }
194252 }
195253
254+ # should use Get-ServiceNowAttachment, but put this here for ease of access
196255 if ( $Table -eq ' attachment'
197256 $invokeParams.Remove (' Table' | Out-Null
198257 $invokeParams.UriLeaf = ' /attachment'
@@ -246,9 +305,8 @@ function Get-ServiceNowRecord {
246305
247306 # format the results
248307 if ( -not $Property ) {
249- $type = $script :ServiceNowTable | Where-Object { $_.Name -eq $Table -or $_.ClassName -eq $Table } | Select-Object - ExpandProperty Type
250- if ($type ) {
251- $result | ForEach-Object { $_.PSObject.TypeNames.Insert (0 , $type ) }
308+ if ($thisTable.Type ) {
309+ $result | ForEach-Object { $_.PSObject.TypeNames.Insert (0 , $thisTable.Type ) }
252310 }
253311 }
254312 $result
0 commit comments