help and other minor updates

Author: gdbarron

CHANGELOG.md

@@ -1,8 +1,11 @@
 ## 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.
+- 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 session variables.
-Be able to reference type names from this config per table, removing the need to have separate Get functions for every table.
+- 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 `Get-ServiceNowRequestItem` to `Get-ServiceNowRequestedItem` which is the actual name.  Function alias 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')]
@@ -89,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"
         }
@@ -168,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

@@ -7,7 +7,7 @@
     Given you know the table name, you shouldn't need any other 'Get-' function.
 
 .PARAMETER Table
-    Name of the table to be queried
+    Name of the table to be queried, by either table name or class name
 
 .PARAMETER Properties
     Limit the fields returned to this list
@@ -55,8 +55,8 @@
     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 incident -Filter @('opened_at', '-ge', 'javascript:gs.daysAgoEnd(30)')
-    Get incident records opened in the last 30 days
+    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
@@ -75,6 +75,7 @@ function Get-ServiceNowRecord {
     Param (
         [parameter(Mandatory)]
         [ValidateNotNullOrEmpty()]
+        [Alias('sys_class_name')]
         [string] $Table,
 
         [Parameter()]
@@ -108,7 +109,7 @@ function Get-ServiceNowRecord {
     $result = Invoke-ServiceNowRestMethod @PSBoundParameters
 
     If ( $result -and -not $Properties) {
-        $type = $script:ServiceNowTable | Where-Object {$_.Name -eq $Table} | Select-Object -ExpandProperty Type
+        $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) }
         }

ServiceNow/Public/New-ServiceNowSession.ps1

@@ -166,17 +166,30 @@ function New-ServiceNowSession {
         }
     }
 
-    # TODO
+    # Write-Verbose 'Retrieving list of classes for this instance.  This will take a few seconds...'
     # $cmdbParams = @{
     #     Table             = 'sys_db_object'
-    #     Query             = 'nameSTARTSWITHcmdb_ci'
+    #     # Query             = 'nameSTARTSWITHcmdb_ci'
     #     Properties        = 'name', 'sys_id', 'label'
-    #     First             = 10000
+    #     First             = 100000
     #     ServiceNowSession = $newSession
     # }
-    # $ci = Get-ServiceNowTable @cmdbParams -ErrorAction SilentlyContinue
-    # if ( $ci ) {
-    #     $newSession.Add('CmdbClasses', $ci)
+
+    # $class = Get-ServiceNowTable @cmdbParams -ErrorAction SilentlyContinue |
+    # Select-Object @{
+    #     'n' = 'Name'
+    #     'e' = { $_.name }
+    # },
+    # @{
+    #     'n' = 'SysId'
+    #     'e' = { $_.sys_id }
+    # },
+    # @{
+    #     'n' = 'ClassName'
+    #     'e' = { $_.label }
+    # }
+    # if ( $class ) {
+    #     $newSession.Add('Classes', $class)
     # }
 
     Write-Verbose ($newSession | ConvertTo-Json)

ServiceNow/ServiceNow.psd1

@@ -59,7 +59,7 @@ FormatsToProcess = @('ServiceNow.format.ps1xml')
 NestedModules = @()
 
 # Functions to export from this module
-    FunctionsToExport = @('Get-ServiceNowRecord','New-ServiceNowSession','Add-ServiceNowAttachment','Get-ServiceNowAttachment','Get-ServiceNowAttachmentDetail','Get-ServiceNowChangeRequest','Get-ServiceNowConfigurationItem','Get-ServiceNowIncident','Get-ServiceNowRequest','Get-ServiceNowRequestItem','Get-ServiceNowTable','Get-ServiceNowTableEntry','Get-ServiceNowUser','Get-ServiceNowUserGroup','New-ServiceNowChangeRequest','New-ServiceNowIncident','New-ServiceNowQuery','New-ServiceNowTableEntry','Remove-ServiceNowAttachment','Remove-ServiceNowAuth','Remove-ServiceNowTableEntry','Set-ServiceNowAuth','Test-ServiceNowAuthIsSet','Update-ServiceNowChangeRequest','Update-ServiceNowIncident','Update-ServiceNowNumber','Update-ServiceNowRequestItem','Update-ServiceNowTableEntry')
+    FunctionsToExport = @('Get-ServiceNowRecord','New-ServiceNowSession','Add-ServiceNowAttachment','Get-ServiceNowAttachment','Get-ServiceNowAttachmentDetail','Get-ServiceNowChangeRequest','Get-ServiceNowConfigurationItem','Get-ServiceNowIncident','Get-ServiceNowRequest','Get-ServiceNowRequestedItem','Get-ServiceNowTable','Get-ServiceNowTableEntry','Get-ServiceNowUser','Get-ServiceNowUserGroup','New-ServiceNowChangeRequest','New-ServiceNowIncident','New-ServiceNowQuery','New-ServiceNowTableEntry','Remove-ServiceNowAttachment','Remove-ServiceNowAuth','Remove-ServiceNowTableEntry','Set-ServiceNowAuth','Test-ServiceNowAuthIsSet','Update-ServiceNowChangeRequest','Update-ServiceNowIncident','Update-ServiceNowNumber','Update-ServiceNowRequestItem','Update-ServiceNowTableEntry')
 
     # Variables to export from this module
     VariablesToExport = 'ServiceNowSession', 'ServiceNowOperator'

ServiceNow/ServiceNow.psm1

@@ -1,4 +1,3 @@
-#Requires -Version 3.0
 [cmdletbinding()]
 param()
 
@@ -26,4 +25,12 @@ foreach ($Folder in @('Private', 'Public')) {
 Export-ModuleMember -Function (Get-ChildItem -Path "$PSScriptRoot\Public\*.ps1").BaseName
 
 $Script:ServiceNowSession = @{}
-Export-ModuleMember -Variable ServiceNowSession
+Export-ModuleMember -Variable ServiceNowSession
+
+$aliases = @{
+    'Get-ServiceNowRequestItem' = 'Get-ServiceNowRequestedItem'
+}
+$aliases.GetEnumerator() | ForEach-Object {
+    Set-Alias -Name $_.Key -Value $_.Value
+}
+Export-ModuleMember -Alias *

ServiceNow/config/main.json

@@ -2,38 +2,43 @@
     "Tables": [
         {
             "Name": "incident",
-            "CommonName": "Incident",
+            "ClassName": "Incident",
             "Type": "ServiceNow.Incident"
         },
         {
             "Name": "change_request",
-            "CommonName": "Change Request",
+            "ClassName": "Change Request",
             "Type": "ServiceNow.ChangeRequest"
         },
         {
             "Name": "cmdb_ci",
-            "CommonName": "Configuration Item",
+            "ClassName": "Configuration Item",
             "Type": "ServiceNow.ConfigurationItem"
         },
         {
             "Name": "sc_request",
-            "CommonName": "Request",
+            "ClassName": "Request",
             "Type": "ServiceNow.Request"
         },
         {
             "Name": "sc_req_item",
-            "CommonName": "Request Item",
+            "ClassName": "Request Item",
             "Type": "ServiceNow.RequestItem"
         },
         {
             "Name": "sys_user",
-            "CommonName": "User",
+            "ClassName": "User",
             "Type": "ServiceNow.UserAndUserGroup"
         },
         {
             "Name": "sys_user_group",
-            "CommonName": "User Group",
+            "ClassName": "User Group",
             "Type": "ServiceNow.UserAndUserGroup"
+        },
+        {
+            "Name": "sc_task",
+            "ClassName": "Catalog Task",
+            "Type": "ServiceNow.CatalogTask"
         }
     ],
     "FilterOperators": [