Merge pull request #129 from Snow-Shell/advanced-filtering

Advanced filtering and sorting

Author: gdbarron

CHANGELOG.md

@@ -1,3 +1,12 @@
+## v2.2
+- Add advanced filtering and sorting.  Initially implemented with `New-ServiceNowQuery` and `Get-ServiceNowRecord`.  Filter with many different comparison operators as well as 'and', 'or', and 'group'ing.  Sort ascending or descending against multiple fields.  Comparison operators are the same as PowerShell for ease of use.  Please use the GitHub Discussions section to provide feedback, thoughts, etc.
+- Add `Get-ServiceNowRecord`.  This function implements the new advanced filtering and sorting.  As long as you know your table name, this can replace all other Get functions.
+- Enumerate implemented tables and advanced filtering operators in a json config to easily manage going forward; make available via script scoped variables.
+Be able to reference types from this config per table, removing the need to have separate Get functions for every table.
+- Add type for catalog task
+- Fix error when getting an empty result from the api and performing a type lookup
+- Rename `RequestItem` to `RequestedItem` which is the actual name.  Function aliases created.
+
 ## v2.1
 - Add proxy support to `New-ServiceNowSession`, [#97](https://github.com/Snow-Shell/servicenow-powershell/issues/97).
 

Readme.md

@@ -18,7 +18,7 @@ Building on the great work the community has done thus far, a lot of new updates
 
 ## Requirements
 
-Requires PowerShell 3.0 or above as this is when `Invoke-RestMethod` was introduced.
+Requires PowerShell 5.1 or above.
 
 Requires authorization in your ServiceNow tenant.  Due to the custom nature of ServiceNow your organization may have REST access restricted.  The following are some tips to ask for if you're having to go to your admin for access:
 
@@ -32,25 +32,52 @@ The ServiceNow module should be installed from the PowerShell Gallery with `inst
 
 ### Creating a new session
 
+Creating a new session will create a script scoped variable `$ServiceNowSession` which will be used by default in other functions.
+
+Basic authentication with just a credential...
 ```PowerShell
-New-ServiceNowSession -url InstanceName.service-now.com -Credentials (Get-Credential)
+$params @{
+    Url = 'instance.service-now.com'
+    Credential = $userCred
+}
+New-ServiceNowSession @params
 ```
 
-This example is using basic authentication, but OAuth is available as well; see the built-in help for `New-ServiceNowSession`.  All examples below assume a new session has already been created.
+Oauth authentication with user credential as well as application/client credential.  The application/client credential can be found in the System OAuth->Application Registry section of ServiceNow.
+```PowerShell
+$params @{
+    Url = 'instance.service-now.com'
+    Credential = $userCred
+    ClientCredential = $clientCred
+}
+New-ServiceNowSession @params
+```
 
-### Example - Retrieving an Incident Containing the Word 'PowerShell'
+All examples below assume a new session has already been created.
+
+### Getting incidents opened in the last 30 days
+```PowerShell
+$filter = @('opened_at', '-ge', 'javascript:gs.daysAgoEnd(30)')
+Get-ServiceNowRecord -Table incident -Filter $filter
+```
+
+### Retrieving an Incident Containing the Word 'PowerShell'
 
 ```PowerShell
 Get-ServiceNowIncident -MatchContains @{short_description='PowerShell'}
 ```
+or new with v2.2
+```PowerShell
+Get-ServiceNowRecord -Table incident -Filter @('short_description','-eq','PowerShell')
+```
 
-### Example - Update a Ticket
+### Update a Ticket
 
 ```PowerShell
 Get-ServiceNowIncident -Limit 1 -MatchContains @{short_description='PowerShell'} | Update-ServiceNowIncident -Values @{comments='Updated via PowerShell'}
 ```
 
-### Example - Creating a Incident with custom table entries
+### Creating an Incident with custom table entries
 
 ```PowerShell
 $IncidentParams = @{Caller = "UserName"

ServiceNow/Private/Invoke-ServiceNowRestMethod.ps1

@@ -23,6 +23,7 @@ function Invoke-ServiceNowRestMethod {
         # Name of the table we're querying (e.g. incidents)
         [parameter(Mandatory, ParameterSetName = 'Table')]
         [ValidateNotNullOrEmpty()]
+        [Alias('sys_class_name')]
         [string] $Table,
 
         [parameter(ParameterSetName = 'Table')]
@@ -39,6 +40,13 @@ function Invoke-ServiceNowRestMethod {
         [parameter()]
         [hashtable] $Values,
 
+        [parameter()]
+        [System.Collections.ArrayList] $Filter,
+
+        [parameter()]
+        [ValidateNotNullOrEmpty()]
+        [System.Collections.ArrayList] $Sort = @('opened_at', 'desc'),
+
         # sysparm_query param in the format of a ServiceNow encoded query string (see http://wiki.servicenow.com/index.php?title=Encoded_Query_Strings)
         [Parameter()]
         [string] $Query,
@@ -82,7 +90,15 @@ function Invoke-ServiceNowRestMethod {
     $params.ContentType = 'application/json'
 
     if ( $Table ) {
-        $params.Uri += "/table/$Table"
+        # table can either be the actual table name or class name
+        # look up the actual table name
+        $tableName = $script:ServiceNowTable | Where-Object { $_.Name -eq $Table -or $_.ClassName -eq $Table } | Select-Object -ExpandProperty Name
+        # if not in our lookup, just use the table name as provided
+        if ( -not $tableName ) {
+            $tableName = $Table
+        }
+
+        $params.Uri += "/table/$tableName"
         if ( $SysId ) {
             $params.Uri += "/$SysId"
         }
@@ -135,6 +151,8 @@ function Invoke-ServiceNowRestMethod {
         # Populate the query
         if ($Query) {
             $Body.sysparm_query = $Query
+        } else {
+            $body.sysparm_query = (New-ServiceNowQuery -Filter $Filter -Sort $Sort)
         }
 
         if ($Properties) {
@@ -159,7 +177,7 @@ function Invoke-ServiceNowRestMethod {
 
     switch ($Method) {
         'Get' {
-            if ( $response.result ) {
+            if ( $response.PSobject.Properties.Name -contains "result" ) {
 
                 $result = $response | Select-Object -ExpandProperty result
                 $ConvertToDateField = @('closed_at', 'expected_start', 'follow_up', 'opened_at', 'sys_created_on', 'sys_updated_on', 'work_end', 'work_start')

ServiceNow/Public/Get-ServiceNowRecord.ps1

@@ -0,0 +1,119 @@
+<#
+.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.
+
+.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.
+
+.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)]
+        [ValidateNotNullOrEmpty()]
+        [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
+}

…Now/Public/Get-ServiceNowRequestItem.ps1 …w/Public/Get-ServiceNowRequestedItem.ps1ServiceNow/Public/Get-ServiceNowRequestItem.ps1 renamed to ServiceNow/Public/Get-ServiceNowRequestedItem.ps1 ServiceNow/Public/Get-ServiceNowRequestItem.ps1 renamed to ServiceNow/Public/Get-ServiceNowRequestedItem.ps1

@@ -1,13 +1,13 @@
-function Get-ServiceNowRequestItem {
+function Get-ServiceNowRequestedItem {
 <#
     .SYNOPSIS
-        Query for Request Item (RITM) tickets.
+        Query for Requested Item (RITM) tickets.
 
     .DESCRIPTION
-        Query for Request Item (RITM) tickets from the sc_req_item table.
+        Query for Requested Item (RITM) tickets from the sc_req_item table.
 
     .EXAMPLE
-        Get-ServiceNowRequestItem -MatchExact @{number='RITM0000001'}
+        Get-ServiceNowRequestedItem -MatchExact @{number='RITM0000001'}
 
         Return the details for RITM0000001
 

ServiceNow/Public/Get-ServiceNowTableEntry.ps1

@@ -23,52 +23,52 @@ function Get-ServiceNowTableEntry {
     param(
         # Table containing the entry we're deleting
         [parameter(Mandatory)]
-        [string]$Table,
+        [string] $Table,
 
         # Machine name of the field to order by
         [parameter()]
-        [string]$OrderBy = 'opened_at',
+        [string] $OrderBy = 'opened_at',
 
         # Direction of ordering (Desc/Asc)
         [parameter()]
         [ValidateSet('Desc', 'Asc')]
-        [string]$OrderDirection = 'Desc',
+        [string] $OrderDirection = 'Desc',
 
         # Maximum number of records to return
         [parameter()]
-        [int]$Limit,
+        [int] $Limit,
 
         # Fields to return
         [Parameter()]
         [Alias('Fields')]
-        [string[]]$Properties,
+        [string[]] $Properties,
 
         # Hashtable containing machine field names and values returned must match exactly (will be combined with AND)
         [parameter()]
-        [hashtable]$MatchExact = @{},
+        [hashtable] $MatchExact = @{},
 
         # Hashtable containing machine field names and values returned rows must contain (will be combined with AND)
         [parameter()]
-        [hashtable]$MatchContains = @{},
+        [hashtable] $MatchContains = @{},
 
         # Whether or not to show human readable display values instead of machine values
         [parameter()]
         [ValidateSet('true', 'false', 'all')]
-        [string]$DisplayValues = 'true',
+        [string] $DisplayValues = 'true',
 
         [Parameter(ParameterSetName = 'SpecifyConnectionFields', Mandatory)]
         [ValidateNotNullOrEmpty()]
         [Alias('ServiceNowCredential')]
-        [PSCredential]$Credential,
+        [PSCredential] $Credential,
 
         [Parameter(ParameterSetName = 'SpecifyConnectionFields', Mandatory)]
         [ValidateScript( { $_ | Test-ServiceNowURL })]
         [Alias('Url')]
-        [string]$ServiceNowURL,
+        [string] $ServiceNowURL,
 
         [Parameter(ParameterSetName = 'UseConnectionObject', Mandatory)]
         [ValidateNotNullOrEmpty()]
-        [hashtable]$Connection,
+        [hashtable] $Connection,
 
         [Parameter(ParameterSetName = 'Session')]
         [ValidateNotNullOrEmpty()]