ServiceNow

1.2.2

Public/New-ServiceNowIncident.ps1

function New-ServiceNowIncident{
    Param(

        # sys_id of the caller of the incident (user Get-ServiceNowUser to retrieve this)
        [parameter(Mandatory=$true)]
        [parameter(ParameterSetName='SpecifyConnectionFields')]
        [parameter(ParameterSetName='UseConnectionObject')]
        [parameter(ParameterSetName='SetGlobalAuth')]
        [string]$Caller,
        
        # Short description of the incident
        [parameter(Mandatory=$true)]
        [parameter(ParameterSetName='SpecifyConnectionFields')]
        [parameter(ParameterSetName='UseConnectionObject')]
        [parameter(ParameterSetName='SetGlobalAuth')]
        [string]$ShortDescription,

        # Long description of the incident
        [parameter(mandatory=$false)]
        [parameter(ParameterSetName='SpecifyConnectionFields')]
        [parameter(ParameterSetName='UseConnectionObject')]
        [parameter(ParameterSetName='SetGlobalAuth')]
        [string]$Description,

        # sys_id of the assignment group (use Get-ServiceNowUserGroup to retrieve this)
        [parameter(mandatory=$false)]
        [parameter(ParameterSetName='SpecifyConnectionFields')]
        [parameter(ParameterSetName='UseConnectionObject')]
        [parameter(ParameterSetName='SetGlobalAuth')]
        [string]$AssignmentGroup,

        # Comment to include in the ticket
        [parameter(mandatory=$false)]        
        [parameter(ParameterSetName='SpecifyConnectionFields')]
        [parameter(ParameterSetName='UseConnectionObject')]
        [parameter(ParameterSetName='SetGlobalAuth')]
        [string]$Comment,

        # Category of the incident (e.g. 'Network')
        [parameter(mandatory=$false)]        
        [parameter(ParameterSetName='SpecifyConnectionFields')]
        [parameter(ParameterSetName='UseConnectionObject')]
        [parameter(ParameterSetName='SetGlobalAuth')]
        [string]$Category,

        # Subcategory of the incident (e.g. 'Network')
        [parameter(mandatory=$false)]
        [parameter(ParameterSetName='SpecifyConnectionFields')]
        [parameter(ParameterSetName='UseConnectionObject')]
        [parameter(ParameterSetName='SetGlobalAuth')]
        [string]$Subcategory,

        # sys_id of the configuration item of the incident
        [parameter(mandatory=$false)]
        [parameter(ParameterSetName='SpecifyConnectionFields')]
        [parameter(ParameterSetName='UseConnectionObject')]
        [parameter(ParameterSetName='SetGlobalAuth')]
        [string]$ConfigurationItem,

        # custom fields as hashtable
        [parameter(mandatory=$false)]
        [parameter(ParameterSetName='SpecifyConnectionFields')]
        [parameter(ParameterSetName='UseConnectionObject')]
        [parameter(ParameterSetName='SetGlobalAuth')]
        [hashtable]$CustomFields,

        # Credential used to authenticate to ServiceNow
        [Parameter(ParameterSetName='SpecifyConnectionFields', Mandatory=$True)]
        [ValidateNotNullOrEmpty()]
        [PSCredential]$ServiceNowCredential, 

        # The URL for the ServiceNow instance being used (eg: instancename.service-now.com)
        [Parameter(ParameterSetName='SpecifyConnectionFields', Mandatory=$True)]
        [ValidateNotNullOrEmpty()]
        [string]$ServiceNowURL, 

        #Azure Automation Connection object containing username, password, and URL for the ServiceNow instance
        [Parameter(ParameterSetName='UseConnectionObject', Mandatory=$True)] 
        [ValidateNotNullOrEmpty()]
        [Hashtable]$Connection
    )

    # Create a hash table of any defined parameters (not CustomFields) 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'}
                Caller              {'caller_id'}
                Category            {'category'}
                Comment             {'comments'}
                ConfigurationItem   {'cmdb_ci'}
                Description         {'description'}
                ShortDescription    {'short_description'}
                Subcategory         {'subcategory'}
            }
            $TableEntryValues.Add($KeyToAdd,$PSBoundParameters.$Parameter)
        }
    }
    
    # Add CustomFields hash pairs to the Table Entry Values hash table
    If ($null -ne $PSBoundParameters.CustomFields) {
        $DuplicateTableEntryValues = ForEach ($Key in $CustomFields.Keys) {
            If (($TableEntryValues.ContainsKey($Key) -eq $False)) {
                # Add the unique entry to the table entry values hash table
                $TableEntryValues.Add($Key,$CustomFields[$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
    $newServiceNowTableEntrySplat = @{
        Table = 'incident'
        Values = $TableEntryValues
    }

    # Update the splat if the parameters have values
    if ($null -ne $PSBoundParameters.Connection)
    {     
        $newServiceNowTableEntrySplat.Add('Connection',$Connection)
    }
    elseif ($null -ne $PSBoundParameters.ServiceNowCredential -and $null -ne $PSBoundParameters.ServiceNowURL) 
    {
        $newServiceNowTableEntrySplat.Add('ServiceNowCredential',$ServiceNowCredential)
        $newServiceNowTableEntrySplat.Add('ServiceNowURL',$ServiceNowURL)
    }
       
    # Create the table entry
    New-ServiceNowTableEntry @newServiceNowTableEntrySplat
}