Merge pull request #61 from replicaJunction/master

Create function Get-ServiceNowRequestItem

Author: Rick-2CA

Readme.md

@@ -32,6 +32,12 @@ These changes should improve your ability to filter on the right, especially by
 
 Requires PowerShell 3.0 or above as this is when `Invoke-RestMethod` was introduced.
 
+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:
+
+* Out of the box tables should be accessible by granting the `ITIL` role.
+* Custom tables may require adjustments to the ACL.
+* The `Web_Service_Admin` role may also be an option.
+
 ## Usage
 
 Download the [latest release](https://github.com/Sam-Martin/servicenow-powershell/releases/latest) and  extract the .psm1 and .psd1 files to your PowerShell profile directory (i.e. the `Modules` directory under wherever `$profile` points to in your PS console) and run:

ServiceNow/Public/Get-ServiceNowRequestItem.ps1

@@ -0,0 +1,93 @@
+function Get-ServiceNowRequestItem {
+    param(
+        # Machine name of the field to order by
+        [parameter(mandatory = $false)]
+        [parameter(ParameterSetName = 'SpecifyConnectionFields')]
+        [parameter(ParameterSetName = 'UseConnectionObject')]
+        [parameter(ParameterSetName = 'SetGlobalAuth')]
+        [string]$OrderBy = 'opened_at',
+
+        # Direction of ordering (Desc/Asc)
+        [parameter(mandatory = $false)]
+        [parameter(ParameterSetName = 'SpecifyConnectionFields')]
+        [parameter(ParameterSetName = 'UseConnectionObject')]
+        [parameter(ParameterSetName = 'SetGlobalAuth')]
+        [ValidateSet("Desc", "Asc")]
+        [string]$OrderDirection = 'Desc',
+
+        # Maximum number of records to return
+        [parameter(mandatory = $false)]
+        [parameter(ParameterSetName = 'SpecifyConnectionFields')]
+        [parameter(ParameterSetName = 'UseConnectionObject')]
+        [parameter(ParameterSetName = 'SetGlobalAuth')]
+        [int]$Limit = 10,
+
+        # Hashtable containing machine field names and values returned must match exactly (will be combined with AND)
+        [parameter(mandatory = $false)]
+        [parameter(ParameterSetName = 'SpecifyConnectionFields')]
+        [parameter(ParameterSetName = 'UseConnectionObject')]
+        [parameter(ParameterSetName = 'SetGlobalAuth')]
+        [hashtable]$MatchExact = @{},
+
+        # Hashtable containing machine field names and values returned rows must contain (will be combined with AND)
+        [parameter(mandatory = $false)]
+        [parameter(ParameterSetName = 'SpecifyConnectionFields')]
+        [parameter(ParameterSetName = 'UseConnectionObject')]
+        [parameter(ParameterSetName = 'SetGlobalAuth')]
+        [hashtable]$MatchContains = @{},
+
+        # Whether or not to show human readable display values instead of machine values
+        [parameter(mandatory = $false)]
+        [parameter(ParameterSetName = 'SpecifyConnectionFields')]
+        [parameter(ParameterSetName = 'UseConnectionObject')]
+        [parameter(ParameterSetName = 'SetGlobalAuth')]
+        [ValidateSet("true", "false", "all")]
+        [string]$DisplayValues = 'true',
+
+        [Parameter(ParameterSetName = 'SpecifyConnectionFields', Mandatory = $True)]
+        [ValidateNotNullOrEmpty()]
+        [PSCredential]
+        $ServiceNowCredential,
+
+        [Parameter(ParameterSetName = 'SpecifyConnectionFields', Mandatory = $True)]
+        [ValidateNotNullOrEmpty()]
+        [string]
+        $ServiceNowURL,
+
+        [Parameter(ParameterSetName = 'UseConnectionObject', Mandatory = $True)]
+        [ValidateNotNullOrEmpty()]
+        [Hashtable]
+        $Connection
+    )
+
+    # Query Splat
+    $newServiceNowQuerySplat = @{
+        OrderBy        = $OrderBy
+        MatchExact     = $MatchExact
+        OrderDirection = $OrderDirection
+        MatchContains  = $MatchContains
+    }
+    $Query = New-ServiceNowQuery @newServiceNowQuerySplat
+
+    # Table Splat
+    $getServiceNowTableSplat = @{
+        Table         = 'sc_req_item'
+        Query         = $Query
+        Limit         = $Limit
+        DisplayValues = $DisplayValues
+    }
+
+    # Update the Table Splat if the parameters have values
+    if ($null -ne $PSBoundParameters.Connection) {
+        $getServiceNowTableSplat.Add('Connection', $Connection)
+    }
+    elseif ($null -ne $PSBoundParameters.ServiceNowCredential -and $null -ne $PSBoundParameters.ServiceNowURL) {
+        $getServiceNowTableSplat.Add('ServiceNowCredential', $ServiceNowCredential)
+        $getServiceNowTableSplat.Add('ServiceNowURL', $ServiceNowURL)
+    }
+
+    # Perform query and return each object in the format.ps1xml format
+    $Result = Get-ServiceNowTable @getServiceNowTableSplat
+    $Result | ForEach-Object {$_.PSObject.TypeNames.Insert(0, "ServiceNow.RequestItem")}
+    $Result
+}

ServiceNow/ServiceNow.psd1

@@ -66,7 +66,7 @@ FormatsToProcess = @('ServiceNow.format.ps1xml')
 NestedModules = @()
 
 # Functions to export from this module
-FunctionsToExport = @('Get-ServiceNowChangeRequest','Get-ServiceNowConfigurationItem','Get-ServiceNowIncident','Get-ServiceNowRequest','Get-ServiceNowTable','Get-ServiceNowTableEntry','Get-ServiceNowUser','Get-ServiceNowUserGroup','New-ServiceNowIncident','New-ServiceNowQuery','New-ServiceNowTableEntry','Remove-ServiceNowAuth','Remove-ServiceNowTableEntry','Set-ServiceNowAuth','Test-ServiceNowAuthIsSet','Update-ServiceNowChangeRequest','Update-ServiceNowIncident','Update-ServiceNowNumber','Update-ServiceNowTableEntry')
+FunctionsToExport = @('Get-ServiceNowChangeRequest','Get-ServiceNowConfigurationItem','Get-ServiceNowIncident','Get-ServiceNowRequest','Get-ServiceNowRequestItem','Get-ServiceNowTable','Get-ServiceNowTableEntry','Get-ServiceNowUser','Get-ServiceNowUserGroup','New-ServiceNowIncident','New-ServiceNowQuery','New-ServiceNowTableEntry','Remove-ServiceNowAuth','Remove-ServiceNowTableEntry','Set-ServiceNowAuth','Test-ServiceNowAuthIsSet','Update-ServiceNowChangeRequest','Update-ServiceNowIncident','Update-ServiceNowNumber','Update-ServiceNowTableEntry')
 
 # List of all modules packaged with this module
 # ModuleList = @()

Tests/ServiceNow.Tests.ps1

@@ -79,6 +79,10 @@ Describe "ServiceNow-Module" {
         ([array](Get-ServiceNowRequest)).count -gt 0 | Should -Match $true
     }
 
+    It "Get-ServiceNowRequestItem returns records" {
+        ([array](Get-ServiceNowRequestItem)).count -gt 0 | Should -Match $true
+    }
+
     It "Get-ServiceNowUserGroup works" {
         (Get-ServiceNowUserGroup).Count -gt 0 | Should -Match $true
     }