Public/New-ServiceNowChangeRequest.ps1

function New-ServiceNowChangeRequest {
    <#
    .SYNOPSIS
        Generates a new ServiceNow change request
 
    .DESCRIPTION
        Generates a new ServiceNow change request using predefined or custom fields by invoking the ServiceNow API
 
    .PARAMETER Caller
        sys_id of the caller of the change request (user Get-ServiceNowUser to retrieve this)
 
    .PARAMETER ShortDescription
        Short description of the change request
 
    .PARAMETER Description
       Long description of the change request
 
    .PARAMETER AssignmentGroup
        sys_id of the assignment group (use Get-ServiceNowUserGroup to retrieve this)
 
    .PARAMETER Comment
        Comment to include in the ticket
 
    .PARAMETER Category
        Category of the change request (e.g. 'Network')
 
    .PARAMETER Subcategory
        Subcategory of the change request (e.g. 'Network')
 
    .PARAMETER ConfigurationItem
        sys_id of the configuration item of the change request
 
    .PARAMETER CustomFields
        Custom fields as hashtable
 
    .PARAMETER ServiceNowCredential
        Credential used to authenticate to ServiceNow
 
    .PARAMETER ServiceNowURL
        The URL for the ServiceNow instance being used (eg: instancename.service-now.com)
 
    .PARAMETER Connection
        Azure Automation Connection object containing username, password, and URL for the ServiceNow instance
 
    .PARAMETER PassThru
        Returns the ticket values after creation
 
    .LINK
        https://github.com/Snow-Shell/servicenow-powershell
 
    .EXAMPLE
        Generate a basic change request attributed to the caller "UserName" with descriptions, categories, assignment groups and CMDB items set.
 
        New-ServiceNowchange request -Caller UserName -ShortDescription 'New PS change request' -Description 'This change request was created from Powershell' -AssignmentGroup ServiceDesk -Comment 'Inline Comment' -Category Office -Subcategory Outlook -ConfigurationItem UserPC1
 
    .EXAMPLE
        Generate an Change Request by 'splatting' all fields used in the 1st example plus some additional custom ServiceNow fields (These must exist in your ServiceNow instance), This example uses the caller's sys_id value for identification.
 
        $newServiceNowChangeRequestSplat = @{
            Caller = '55ccf91161924edc979d8e7e5627a47d'
            ShortDescription = 'New PS Change Request'
            Description = 'This change request was created from Powershell'
            AssignmentGroup = 'ServiceDesk'
            Comment = 'Inline Comment'
            Category = 'Office'
            Subcategory = 'Outlook'
            ConfigurationItem = 'UserPC1'
            CustomFields = @{
                u_custom1 = 'Custom Field Entry'
                u_another_custom = 'Related Test'
            }
        }
        New-ServiceNowChangeRequest @newServiceNowChangeRequestSplat
     #>


    [CmdletBinding(DefaultParameterSetName = 'Session', SupportsShouldProcess)]

    Param(
        [parameter(Mandatory)]
        [string]$Caller,

        [parameter(Mandatory)]
        [string]$ShortDescription,

        [parameter()]
        [string]$Description,

        [parameter()]
        [string]$AssignmentGroup,

        [parameter()]
        [string]$Comment,

        [parameter()]
        [string]$Category,

        [parameter()]
        [string]$Subcategory,

        [parameter()]
        [string]$ConfigurationItem,

        [parameter()]
        [hashtable]$CustomFields,

        [Parameter(ParameterSetName = 'SpecifyConnectionFields', Mandatory)]
        [ValidateNotNullOrEmpty()]
        [PSCredential]$ServiceNowCredential,

        [Parameter(ParameterSetName = 'SpecifyConnectionFields', Mandatory)]
        [ValidateNotNullOrEmpty()]
        [string]$ServiceNowURL,

        [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 CustomFields) that have values
        $DefinedChangeRequestParameters = @('AssignmentGroup', 'Caller', 'Category', 'Comment', 'ConfigurationItem', 'Description', 'ShortDescription', 'Subcategory')
        $TableEntryValues = @{ }
        ForEach ($Parameter in $DefinedChangeRequestParameters) {
            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 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
        $params = @{
            Method            = 'Post'
            Table             = 'change_request'
            Values            = $TableEntryValues
            Connection        = $Connection
            Credential        = $Credential
            ServiceNowUrl     = $ServiceNowURL
            ServiceNowSession = $ServiceNowSession
        }

        If ( $PSCmdlet.ShouldProcess($ShortDescription, 'Create new change request') ) {
            $response = Invoke-ServiceNowRestMethod @params
            If ($PassThru.IsPresent) {
                $response.PSObject.TypeNames.Insert(0, "ServiceNow.ChangeRequest")
                $response
            }
        }
    }

    end {}
}