Merge pull request #36 from X-Guardian/master

Modify DateTime field processing Depending Upon DisplayValues

Author: Rick-2CA

ServiceNow/Public/Get-ServiceNowChangeRequest.ps1

@@ -36,13 +36,13 @@ function Get-ServiceNowChangeRequest {
         [parameter(ParameterSetName='SetGlobalAuth')]
         [hashtable]$MatchContains=@{},
 
-        # Whether or not to show human readable display values instead of machine values
+        # Whether to return manipulated display values rather than actual database values.
         [parameter(mandatory=$false)]
         [parameter(ParameterSetName='SpecifyConnectionFields')]
         [parameter(ParameterSetName='UseConnectionObject')]
         [parameter(ParameterSetName='SetGlobalAuth')]
         [ValidateSet("true","false", "all")]
-        [string]$DisplayValues='true',
+        [string]$DisplayValues='false',
 
         [Parameter(ParameterSetName='SpecifyConnectionFields', Mandatory=$True)]
         [ValidateNotNullOrEmpty()]

ServiceNow/Public/Get-ServiceNowConfigurationItem.ps1

@@ -36,13 +36,13 @@ function Get-ServiceNowConfigurationItem {
         [parameter(ParameterSetName='SetGlobalAuth')]
         [hashtable]$MatchContains=@{},
 
-        # Whether or not to show human readable display values instead of machine values
+        # Whether to return manipulated display values rather than actual database values.
         [parameter(mandatory=$false)]
         [parameter(ParameterSetName='SpecifyConnectionFields')]
         [parameter(ParameterSetName='UseConnectionObject')]
         [parameter(ParameterSetName='SetGlobalAuth')]
         [ValidateSet("true","false", "all")]
-        [string]$DisplayValues='true',
+        [string]$DisplayValues='false',
 
         [Parameter(ParameterSetName='SpecifyConnectionFields', Mandatory=$True)]
         [ValidateNotNullOrEmpty()]

ServiceNow/Public/Get-ServiceNowIncident.ps1

@@ -36,13 +36,13 @@ function Get-ServiceNowIncident{
         [parameter(ParameterSetName='SetGlobalAuth')]
         [hashtable]$MatchContains=@{},
 
-        # Whether or not to show human readable display values instead of machine values
+        # Whether to return manipulated display values rather than actual database values.
         [parameter(mandatory=$false)]
         [parameter(ParameterSetName='SpecifyConnectionFields')]
         [parameter(ParameterSetName='UseConnectionObject')]
         [parameter(ParameterSetName='SetGlobalAuth')]
         [ValidateSet("true","false", "all")]
-        [string]$DisplayValues='true',
+        [string]$DisplayValues='false',
 
         # Credential used to authenticate to ServiceNow  
         [Parameter(ParameterSetName='SpecifyConnectionFields', Mandatory=$True)]

ServiceNow/Public/Get-ServiceNowTable.ps1

@@ -1,5 +1,18 @@
 function Get-ServiceNowTable {
-    [OutputType([Array])]
+<#
+.SYNOPSIS
+    Retrieves multiple records for the specified table
+.DESCRIPTION
+    The Get-ServiceNowTable function retrieves multiple records for the specified table
+.INPUTS
+    None
+.OUTPUTS
+    System.Management.Automation.PSCustomObject
+.LINK
+    Service-Now Kingston REST Table API: https://docs.servicenow.com/bundle/kingston-application-development/page/integrate/inbound-rest/concept/c_TableAPI.html
+    Service-Now Table API FAQ: https://hi.service-now.com/kb_view.do?sysparm_article=KB0534905
+#>
+[OutputType([Array])]
     Param (
         # Name of the table we're querying (e.g. incidents)
         [parameter(Mandatory)]
@@ -21,7 +34,7 @@ function Get-ServiceNowTable {
         [parameter(ParameterSetName = 'SetGlobalAuth')]
         [int]$Limit = 10,
 
-        # Whether or not to show human readable display values instead of machine values
+        # Whether to return manipulated display values rather than actual database values.
         [parameter(ParameterSetName = 'SpecifyConnectionFields')]
         [parameter(ParameterSetName = 'UseConnectionObject')]
         [parameter(ParameterSetName = 'SetGlobalAuth')]
@@ -59,6 +72,7 @@ function Get-ServiceNowTable {
     elseif ((Test-ServiceNowAuthIsSet)) {
         $ServiceNowCredential = $Global:ServiceNowCredentials
         $ServiceNowURL = $global:ServiceNowRESTURL
+        $ServiceNowDateFormat = $Global:ServiceNowDateFormat
     }
     else {
         throw "Exception:  You must do one of the following to authenticate: `n 1. Call the Set-ServiceNowAuth cmdlet `n 2. Pass in an Azure Automation connection object `n 3. Pass in an endpoint and credential"
@@ -75,28 +89,27 @@ function Get-ServiceNowTable {
     $Result = (Invoke-RestMethod -Uri $Uri -Credential $ServiceNowCredential -Body $Body -ContentType "application/json").Result
 
     # Convert specific fields to DateTime format
+    $DefaultServiceNowDateFormat = 'yyyy-MM-dd HH:mm:ss'
     $ConvertToDateField = @('closed_at', 'expected_start', 'follow_up', 'opened_at', 'sys_created_on', 'sys_updated_on', 'work_end', 'work_start')
     ForEach ($SNResult in $Result) {
         ForEach ($Property in $ConvertToDateField) {
             If (-not [string]::IsNullOrEmpty($SNResult.$Property)) {
-                Try {
-                    # Extract the default Date/Time formatting from the local computer's "Culture" settings, and then create the format to use when parsing the date/time from Service-Now
-                    $CultureDateTimeFormat = (Get-Culture).DateTimeFormat
-                    $DateFormat = $CultureDateTimeFormat.ShortDatePattern
-                    $TimeFormat = $CultureDateTimeFormat.LongTimePattern
-                    $DateTimeFormat = "$DateFormat $TimeFormat"
-                    $SNResult.$Property = [DateTime]::ParseExact($($SNResult.$Property), $DateTimeFormat, [System.Globalization.DateTimeFormatInfo]::InvariantInfo, [System.Globalization.DateTimeStyles]::None)
-                }
-                Catch {
+                If ($DisplayValues -eq $True) {
+                    # DateTime fields returned in the Service-Now instance system date format need converting to the local computers "culture" setting based upon the format specified
                     Try {
-                        # Universal Format
-                        $DateTimeFormat = 'yyyy-MM-dd HH:mm:ss'
-                        $SNResult.$Property = [DateTime]::ParseExact($($SNResult.$Property), $DateTimeFormat, [System.Globalization.DateTimeFormatInfo]::InvariantInfo, [System.Globalization.DateTimeStyles]::None)
+                        Write-Debug "Date Parsing field: $Property, value: $($SNResult.$Property) against global format $Global:ServiceNowDateFormat"
+                        $SNResult.$Property = [DateTime]::ParseExact($($SNResult.$Property), $Global:ServiceNowDateFormat, [System.Globalization.DateTimeFormatInfo]::InvariantInfo)
                     }
                     Catch {
-                        # If the local culture and universal formats both fail keep the property as a string (Do nothing)
+                        Throw "Problem parsing date-time field $Property with value $($SNResult.$Property) against format $Global:ServiceNowDateFormat. " +
+                              "Please verify the DateFormat parameter matches the glide.sys.date_format property of the Service-Now instance"
                     }
                 }
+                Else {
+                    # DateTime fields always returned as yyyy-MM-dd hh:mm:ss when sysparm_display_value is set to false
+                    Write-Debug "Date Parsing field: $Property, value: $($SNResult.$Property) against default format $DefaultServiceNowDateFormat"
+                    $SNResult.$Property = [DateTime]::ParseExact($($SNResult.$Property), $DefaultServiceNowDateFormat, [System.Globalization.DateTimeFormatInfo]::InvariantInfo) 
+                }
             }
         }
     }

ServiceNow/Public/Get-ServiceNowUser.ps1

@@ -36,13 +36,13 @@ function Get-ServiceNowUser{
         [parameter(ParameterSetName='SetGlobalAuth')]
         [hashtable]$MatchContains=@{},
 
-        # Whether or not to show human readable display values instead of machine values
+        # Whether to return manipulated display values rather than actual database values.
         [parameter(mandatory=$false)]
         [parameter(ParameterSetName='SpecifyConnectionFields')]
         [parameter(ParameterSetName='UseConnectionObject')]
         [parameter(ParameterSetName='SetGlobalAuth')]
         [ValidateSet("true","false", "all")]
-        [string]$DisplayValues='true',
+        [string]$DisplayValues='false',
 
         # Credential used to authenticate to ServiceNow  
         [Parameter(ParameterSetName='SpecifyConnectionFields', Mandatory=$True)]

ServiceNow/Public/Get-ServiceNowUserGroup.ps1

@@ -36,13 +36,13 @@ function Get-ServiceNowUserGroup{
         [parameter(ParameterSetName='SetGlobalAuth')]
         [hashtable]$MatchContains=@{},
 
-        # Whether or not to show human readable display values instead of machine values
+        # Whether to return manipulated display values rather than actual database values.
         [parameter(mandatory=$false)]
         [parameter(ParameterSetName='SpecifyConnectionFields')]
         [parameter(ParameterSetName='UseConnectionObject')]
         [parameter(ParameterSetName='SetGlobalAuth')]
         [ValidateSet("true","false", "all")]
-        [string]$DisplayValues='true',
+        [string]$DisplayValues='false',
 
         # Credential used to authenticate to ServiceNow  
         [Parameter(ParameterSetName='SpecifyConnectionFields', Mandatory=$True)]

ServiceNow/Public/Set-ServiceNowAuth.ps1

@@ -11,11 +11,20 @@ The URL of your Service-Now instance
 .PARAMETER Credentials
 Credentials to authenticate you to the Service-Now instance provided in the Url parameter
 
+.PARAMETER DateFormat
+The date format specified in the Service-Now Instance, sys_properties table, property glide.sys.data_format. This is required
+to correctly convert datetime fields to the local computer locale format when the DisplayValues parameter of the Get-* functions
+is set to true 
+
 .EXAMPLE
 Set-ServiceNowAuth -Url tenant.service-now.com
 
 .NOTES
 The URL should be the instance name portion of the FQDN for your instance. If you browse to https://yourinstance.service-now.com the URL required for the module is yourinstance.service-now.com
+
+.LINK
+    Service-Now Kingston Release REST API Reference: https://docs.servicenow.com/bundle/kingston-application-development/page/build/applications/concept/api-rest.html
+    Service-Now Table API FAQ: https://hi.service-now.com/kb_view.do?sysparm_article=KB0534905
 #>
 function Set-ServiceNowAuth {
     [CmdletBinding()]
@@ -36,10 +45,17 @@ function Set-ServiceNowAuth {
         [Parameter(Mandatory = $true)]
         [ValidateNotNullOrEmpty()]
         [System.Management.Automation.PSCredential]
-        $Credentials
+        $Credentials,
+
+        [parameter(mandatory = $false)]
+        [String]
+        $DateFormat = (Get-Culture).DateTimeFormat.ShortDatePattern+' '+(Get-Culture).DateTimeFormat.LongTimePattern
     )
+
     $Global:serviceNowUrl = 'https://' + $Url
     $Global:serviceNowRestUrl = $serviceNowUrl + '/api/now/v1'
     $Global:serviceNowCredentials = $Credentials
+    $Global:ServiceNowDateFormat = $DateFormat
+
     return $true
 }