Public/New-ServiceNowIncident.ps1
|
<#
.SYNOPSIS Generates a new ServiceNow Incident .DESCRIPTION Generates a new ServiceNow Incident using predefined or custom fields by invoking the ServiceNow API .EXAMPLE Generate a basic Incident attributed to the caller "UserName" with descriptions, categories, assignment groups and CMDB items set. New-ServiceNowIncident -Caller "UserName" -ShortDescription = "New PS Incident" -Description = "This incident was created from Powershell" -AssignmentGroup "ServiceDesk" -Comment "Inline Comment" -Category "Office" -Subcategory "Outlook" -ConfigurationItem UserPC1 .EXAMPLE Generate an Incident by "Splatting" all fields used in the 1st example plus some additional custom ServiceNow fields (These must exist in your ServiceNow Instance): $IncidentParams = @{Caller = "UserName" ShortDescription = "New PS Incident" Description = "This incident was created from Powershell" AssignmentGroup "ServiceDesk" Comment "Inline Comment" Category "Office" Subcategory "Outlook" ConfigurationItem UserPC1 CustomField = @{u_custom1 = "Custom Field Entry" u_another_custom = "Related Test"} } New-ServiceNowIncident @Params #> function New-ServiceNowIncident { [CmdletBinding(DefaultParameterSetName = 'Session', SupportsShouldProcess)] Param( # sys_id of the caller of the incident (user Get-ServiceNowUser to retrieve this) [parameter(Mandatory)] [string] $Caller, # Short description of the incident [parameter(Mandatory)] [string] $ShortDescription, # Long description of the incident [parameter()] [string] $Description, # sys_id of the assignment group (use Get-ServiceNowUserGroup to retrieve this) [parameter()] [string] $AssignmentGroup, # Comment to include in the ticket [parameter()] [string] $Comment, # Category of the incident (e.g. 'Network') [parameter()] [string] $Category, # Subcategory of the incident (e.g. 'Network') [parameter()] [string] $Subcategory, # sys_id of the configuration item of the incident [parameter()] [string] $ConfigurationItem, # custom fields as hashtable [parameter()] [Alias('CustomFields')] [hashtable] $CustomField, # Credential used to authenticate to ServiceNow [Parameter(ParameterSetName = 'SpecifyConnectionFields', Mandatory)] [ValidateNotNullOrEmpty()] [Alias('ServiceNowCredential')] [PSCredential] $Credential, # The URL for the ServiceNow instance being used (eg: instancename.service-now.com) [Parameter(ParameterSetName = 'SpecifyConnectionFields', Mandatory)] [ValidateNotNullOrEmpty()] [string] $ServiceNowURL, #Azure Automation Connection object containing username, password, and URL for the ServiceNow instance [Parameter(ParameterSetName = 'UseConnectionObject', Mandatory)] [ValidateNotNullOrEmpty()] [Hashtable] $Connection, [Parameter(ParameterSetName = 'Session')] [ValidateNotNullOrEmpty()] [hashtable] $ServiceNowSession = $script:ServiceNowSession, [Parameter()] [switch] $PassThru ) begin {} process { # Create a hash table of any defined parameters (not CustomField) that have values $DefinedIncidentParameters = @('AssignmentGroup', 'Caller', 'Category', 'Comment', 'ConfigurationItem', 'Description', 'ShortDescription', 'Subcategory') $TableEntryValues = @{} ForEach ($Parameter in $DefinedIncidentParameters) { If ($null -ne $PSBoundParameters.$Parameter) { # Turn the defined parameter name into the ServiceNow attribute name $KeyToAdd = Switch ($Parameter) { AssignmentGroup { 'assignment_group'; break } Caller { 'caller_id'; break } Category { 'category'; break } Comment { 'comments'; break } ConfigurationItem { 'cmdb_ci'; break } Description { 'description'; break } ShortDescription { 'short_description'; break } Subcategory { 'subcategory'; break } } $TableEntryValues.Add($KeyToAdd, $PSBoundParameters.$Parameter) } } # Add CustomField hash pairs to the Table Entry Values hash table If ($null -ne $PSBoundParameters.CustomField) { $DuplicateTableEntryValues = ForEach ($Key in $CustomField.Keys) { If (($TableEntryValues.ContainsKey($Key) -eq $False)) { # Add the unique entry to the table entry values hash table $TableEntryValues.Add($Key, $CustomField[$Key]) } Else { # Capture the duplicate key name $Key } } } # Throw an error if duplicate fields were provided If ($null -ne $DuplicateTableEntryValues) { $DuplicateKeyList = $DuplicateTableEntryValues -join "," Throw "Ticket fields may only be used once: $DuplicateKeyList" } # Table Entry Splat $params = @{ Method = 'Post' Table = 'incident' Values = $TableEntryValues Connection = $Connection Credential = $Credential ServiceNowUrl = $ServiceNowURL ServiceNowSession = $ServiceNowSession } If ( $PSCmdlet.ShouldProcess($ShortDescription, 'Create new incident') ) { $response = Invoke-ServiceNowRestMethod @params If ($PassThru.IsPresent) { $response.PSObject.TypeNames.Insert(0, "ServiceNow.Incident") $response } } } } |