1.8.0 - Formatting on Update-ServiceNowRequestItem & Added Pester Test

Author: Rick-2CA

ServiceNow/Public/Update-ServiceNowRequestItem.ps1

@@ -1,49 +1,82 @@
 function Update-ServiceNowRequestItem {
-    Param
-    (   # sys_id of the caller of the Request Item (use Get-ServiceNowUser to retrieve this)
-        [parameter(mandatory=$true)]        
-        [parameter(ParameterSetName='SpecifyConnectionFields', mandatory=$true)]
-        [parameter(ParameterSetName='UseConnectionObject', mandatory=$true)]
-        [parameter(ParameterSetName='SetGlobalAuth', mandatory=$true)]       
+    <#
+    .SYNOPSIS
+    Update an existing request item (RITM)
+
+    .DESCRIPTION
+    Update an existing request item (RITM)
+
+    .EXAMPLE
+    Update-ServiceNowRequestItem -SysId $SysId -Values @{property='value'}
+
+    Updates a ticket number with a value providing no return output.
+
+    .EXAMPLE
+    Update-ServiceNowRequestItem -SysId $SysId -Values @{property='value'} -PassThru
+
+    Updates a ticket number with a value providing return output.
+
+    .NOTES
+
+    #>
+
+    [System.Diagnostics.CodeAnalysis.SuppressMessage('PSAvoidUsingConvertToSecureStringWithPlainText','')]
+    [System.Diagnostics.CodeAnalysis.SuppressMessage('PSAvoidGlobalVars','')]
+
+    [OutputType([void],[System.Management.Automation.PSCustomObject])]
+    [CmdletBinding(DefaultParameterSetName,SupportsShouldProcess=$true)]
+    Param (
+        # sys_id of the ticket to update
+        [Parameter(mandatory=$true)]
         [string]$SysId,
 
-         # Hashtable of values to use as the record's properties        
-        [parameter(mandatory=$true)]        
+         # Hashtable of values to use as the record's properties
+        [Parameter(mandatory=$true)]
         [hashtable]$Values,
 
-         # Credential used to authenticate to ServiceNow  
+         # Credential used to authenticate to ServiceNow
         [Parameter(ParameterSetName='SpecifyConnectionFields', Mandatory=$True)]
         [ValidateNotNullOrEmpty()]
-        [PSCredential]$ServiceNowCredential, 
+        [Alias('ServiceNowCredential')]
+        [PSCredential]$Credential,
 
         # The URL for the ServiceNow instance being used (eg: instancename.service-now.com)
         [Parameter(ParameterSetName='SpecifyConnectionFields', Mandatory=$True)]
         [ValidateNotNullOrEmpty()]
-        [string]$ServiceNowURL, 
+        [string]$ServiceNowURL,
 
         #Azure Automation Connection object containing username, password, and URL for the ServiceNow instance
-        [Parameter(ParameterSetName='UseConnectionObject', Mandatory=$True)] 
+        [Parameter(ParameterSetName='UseConnectionObject', Mandatory=$True)]
         [ValidateNotNullOrEmpty()]
-        [Hashtable]$Connection
-    )                      
+        [Hashtable]$Connection,
+
+        # Switch to allow the results to be passed back
+        [Parameter(Mandatory=$false)]
+        [switch]$PassThru
+    )
 
     $updateServiceNowTableEntrySplat = @{
-        SysId = $SysId
-        Table = 'sc_req_item'
+        SysId  = $SysId
+        Table  = 'sc_req_item'
         Values = $Values
     }
-    
+
     # Update the splat if the parameters have values
-    if ($null -ne $PSBoundParameters.Connection)
-    {     
+    If ($null -ne $PSBoundParameters.Connection) {
         $updateServiceNowTableEntrySplat.Add('Connection',$Connection)
     }
-    elseif ($null -ne $PSBoundParameters.ServiceNowCredential -and $null -ne $PSBoundParameters.ServiceNowURL) 
-    {
+    ElseIf ($null -ne $PSBoundParameters.Credential -and $null -ne $PSBoundParameters.ServiceNowURL) {
          $updateServiceNowTableEntrySplat.Add('ServiceNowCredential',$ServiceNowCredential)
          $updateServiceNowTableEntrySplat.Add('ServiceNowURL',$ServiceNowURL)
     }
-       
-    Update-ServiceNowTableEntry @updateServiceNowTableEntrySplat
-}
 
+    If ($PSCmdlet.ShouldProcess("$Table/$SysID",$MyInvocation.MyCommand)) {
+        # Send REST call
+        $Result = Update-ServiceNowTableEntry @updateServiceNowTableEntrySplat
+
+        # Option to return results
+        If ($PSBoundParameters.ContainsKey('Passthru')) {
+            $Result
+        }
+    }
+}

ServiceNow/ServiceNow.psd1

@@ -12,7 +12,7 @@
 RootModule = 'ServiceNow.psm1'
 
 # Version number of this module.
-ModuleVersion = '1.7.1'
+ModuleVersion = '1.8.0'
 
 # ID used to uniquely identify this module
 GUID = 'b90d67da-f8d0-4406-ad74-89d169cd0633'
@@ -130,6 +130,8 @@ PrivateData = @{
 
 
 
+
+
 
 
 

Tests/ServiceNow.Tests.ps1

@@ -253,6 +253,45 @@ Describe "ServiceNow-Module" {
         $TestTicket.description | Should -Be 'Updated by Pester test Update-ServiceNowNumber with SpecifyConnectionFields works'
     }
 
+    It "Update-ServiceNowRequestItem No PassThru works" {
+        # Due to a lack of ServiceNow request (REQ) commands this test only works consistently in a developer instance
+        $TestTicket = Get-ServiceNowRequestItem -MatchExact @{number='RITM0000001';short_description='Apple iPad 3';state=1} -ErrorAction SilentlyContinue
+        $TestTicket.number | Should -Be 'RITM0000001' -Because 'This test only works in a ServiceNow developer instance for RITM0000001'
+
+        $Values = @{
+            'description' = 'Updated by Pester test Update-ServiceNowRequestItem No PassThru works'
+        }
+
+        $CommandOutput = Update-ServiceNowRequestItem -SysId $TestTicket.sys_id -Values $Values
+
+        $TestTicket = Get-ServiceNowRequestItem -MatchExact @{sys_id=$TestTicket.sys_id}
+        $TestTicket.description | Should -Be 'Updated by Pester test Update-ServiceNowRequestItem No PassThru works'
+        $CommandOutput | Should -BeNullOrEmpty
+    }
+
+    It "Update-ServiceNowRequestItem with SpecifyConnectionFields and PassThru works" {
+        # Due to a lack of ServiceNow request (REQ) commands this test only works consistently in a developer instance
+        $TestTicket = Get-ServiceNowRequestItem -MatchExact @{number='RITM0000001';short_description='Apple iPad 3';state=1} -ErrorAction SilentlyContinue
+        $TestTicket.number | Should -Be 'RITM0000001' -Because 'This test only works in a ServiceNow developer instance for RITM0000001'
+
+        $Values = @{
+            'description' = 'Updated by Pester test Update-ServiceNowRequestItem with SpecifyConnectionFields works'
+        }
+
+        $updateServiceNowRequestItemSplat = @{
+            SysID         = $TestTicket.sys_id
+            Values        = $Values
+            Credential    = $Credential
+            ServiceNowURL = $Defaults.ServiceNowURL
+            PassThru      = $true
+        }
+        $CommandOutput = Update-ServiceNowRequestItem @updateServiceNowRequestItemSplat
+
+        $TestTicket = Get-ServiceNowRequestItem -MatchExact @{sys_id=$TestTicket.sys_id}
+        $TestTicket.description | Should -Be 'Updated by Pester test Update-ServiceNowRequestItem with SpecifyConnectionFields works'
+        $CommandOutput | Should -Not -BeNullOrEmpty
+    }
+
     # Remove Functions
     It "Remove-ServiceNowTable works" {
         $TestTicket = Get-ServiceNowIncident -First 1
@@ -270,6 +309,6 @@ Describe "ServiceNow-Module" {
     }
 
     It "Remove-ServiceNowAuth works" {
-        Remove-ServiceNowAuth | Should be $true
+        Remove-ServiceNowAuth | Should -Be $true
     }
 }