Public/Set-FreshServiceRelease.ps1
|
<#
.SYNOPSIS Updates a Freshservice Release. .DESCRIPTION Updates a Freshservice Release via REST API. https://api.freshservice.com/#update_release_priority .PARAMETER id Unique identifier of the Release. .PARAMETER agent_id Unique identifier of the agent to whom the Release is assigned. .PARAMETER group_id Unique identifier of the agent group to which the Release is assigned. .PARAMETER priority Priority of the Release: 1 = Low 2 = Medium 3 = High 4 = Urgent .PARAMETER status Status identifier of the Release: 1 = Open 2 = On hold 3 = In Progress 4 = Incomplete 5 = Completed .PARAMETER release_type Type of the Release: 1 = minor 2 = standard 3 = major 4 = emergency .PARAMETER subject Subject of the Release. .PARAMETER description HTML description of the release. Description and description_html should not be passed together. .PARAMETER planned_start_date Timestamp at which release is starting. .PARAMETER planned_end_date Timestamp at which release is ending. .PARAMETER work_start_date Timestamp at which release work started. .PARAMETER work_end_date Timestamp at which release work ended. .PARAMETER department_id Unique ID of the department initiating the Release. .PARAMETER category Category of the Release. .PARAMETER sub_category Sub-category of the Release. .PARAMETER item_category Item of the Release. .PARAMETER custom_fields Key value pairs containing the names and values of custom fields. .PARAMETER assets List of assets associated with the release. .PARAMETER attachments Path to attachment(s). .PARAMETER build_plan Planning field containing the build plan. .PARAMETER test_plan Planning field containing the test plan. .EXAMPLE Set-FreshServiceRelease -id 4 -priority 3 id : 4 agent_id : 21000418005 description : <div>Release from Pester: cdc12ab5-5beb-48cf-a931-e3bdfc16391f</div> description_text : Release from Pester: cdc12ab5-5beb-48cf-a931-e3bdfc16391f assets : {} group_id : 21000188395 department_id : subject : Release from Pester: cdc12ab5-5beb-48cf-a931-e3bdfc16391f category : Hardware sub_category : Peripherals item_category : Router planned_start_date : 3/1/2023 1:00:00 AM planned_end_date : 3/1/2023 3:00:00 AM status : 1 priority : 3 release_type : 2 work_start_date : 3/1/2023 1:00:00 AM work_end_date : 3/1/2023 3:00:00 AM created_at : 3/1/2023 3:03:45 AM updated_at : 3/31/2023 1:07:21 AM associated_change_ids : {} custom_fields : planning_fields : Update the priority of a Freshservice Release. .NOTES This module was developed and tested with Freshservice REST API v2. #> function Set-FreshServiceRelease { [CmdletBinding(SupportsShouldProcess=$true, ConfirmImpact='Medium', DefaultParameterSetName = 'default')] param ( [Parameter( Mandatory = $true, HelpMessage = 'Unique identifier of the Release', ValueFromPipelineByPropertyName = $true )] [long]$id, [Parameter( Mandatory = $false, HelpMessage = 'Unique identifier of the agent to whom the Release is assigned', ValueFromPipelineByPropertyName = $true )] [long]$agent_id, [Parameter( Mandatory = $false, HelpMessage = 'Unique identifier of the agent group to which the Release is assigned', ValueFromPipelineByPropertyName = $true )] [long]$group_id, [Parameter( Mandatory=$false, HelpMessage = 'Priority of the Release 1-Low, 2-Medium, 3-High, 4-Urgent', ValueFromPipelineByPropertyName = $true )] [ValidateRange(1,4)] [int]$priority, [Parameter( Mandatory=$false, HelpMessage = 'Status identifier of the Release. 1-Open, 2-On hold, 3-In Progress, 4-Incomplete, 5-Completed', ValueFromPipelineByPropertyName = $true )] [ValidateRange(1,5)] [int]$status, [Parameter( Mandatory=$false, HelpMessage = 'Type of the Release 1-minor, 2-standard, 3-major, 4-emergency', ValueFromPipelineByPropertyName = $true )] [ValidateRange(1,4)] [int]$release_type, [Parameter( Mandatory=$false, HelpMessage = 'Subject of the Release', ValueFromPipelineByPropertyName = $true )] [string]$subject, [Parameter( Mandatory = $false, HelpMessage = 'HTML description of the release. Description and description_html should not be passed together', ValueFromPipelineByPropertyName = $true )] [string]$description, [Parameter( Mandatory=$false, HelpMessage = 'Timestamp at which release is starting', ValueFromPipelineByPropertyName = $true )] [datetime]$planned_start_date, [Parameter( Mandatory=$false, HelpMessage = 'Timestamp at which release is ending', ValueFromPipelineByPropertyName = $true )] [datetime]$planned_end_date, [Parameter( Mandatory = $false, HelpMessage = 'Timestamp at which release work started', ValueFromPipelineByPropertyName = $true )] [datetime]$work_start_date, [Parameter( Mandatory = $false, HelpMessage = 'Timestamp at which release work ended', ValueFromPipelineByPropertyName = $true )] [datetime]$work_end_date, [Parameter( Mandatory = $false, HelpMessage = 'Unique ID of the department initiating the Release', ValueFromPipelineByPropertyName = $true )] [long]$department_id, [Parameter( Mandatory = $false, HelpMessage = 'Category of the Release', ValueFromPipelineByPropertyName = $true )] [string]$category, [Parameter( Mandatory = $false, HelpMessage = 'Sub-category of the Release', ValueFromPipelineByPropertyName = $true )] [string]$sub_category, [Parameter( Mandatory = $false, HelpMessage = 'Item of the Release', ValueFromPipelineByPropertyName = $true )] [string]$item_category, [Parameter( Mandatory = $false, HelpMessage = 'Key value pairs containing the names and values of custom fields.', ValueFromPipelineByPropertyName = $true )] [hashtable]$custom_fields, [Parameter( Mandatory = $false, HelpMessage = 'List of assets associated with the release', ValueFromPipelineByPropertyName = $true )] [object[]]$assets, [Parameter( Mandatory = $false, HelpMessage = 'Release attachments. The total size of these attachments cannot exceed 15MB.', ValueFromPipelineByPropertyName = $true )] [ValidateScript({ if(-Not ($_ | Test-Path) ){ throw ("Cannot find path {0} because it does not exist." -f $_.FullName) } if(-Not ($_ | Test-Path -PathType Leaf) ){ throw ("{0} is not a valid file. Folder paths are not allowed." -f $_.FullName) } if($_.Length/1MB -gt 15 ) { throw ("{0} exceeds the file size limit. Files must be under 15MB." -f $_.FullName) } return $true })] [System.IO.FileInfo[]]$attachments, [Parameter( Mandatory = $false, HelpMessage = 'Release symptom description', ValueFromPipelineByPropertyName = $true, ParameterSetName = 'default', Position = 19 )] [string]$build_plan, [Parameter( Mandatory = $false, HelpMessage = 'Release impact description', ValueFromPipelineByPropertyName = $true, ParameterSetName = 'default', Position = 20 )] [string]$test_plan ) begin { $PrivateData = $MyInvocation.MyCommand.Module.PrivateData if (!$PrivateData.FreshserviceBaseUri) { throw "No connection found! Setup a new Freshservice connection with New-FreshServiceConnection and then Connect-FreshService. Set a default connection with New-FreshServiceConnection or Set-FreshConnection to automatically connect when importing the module." } } process { $uri = [System.UriBuilder]('{0}/releases' -f $PrivateData['FreshserviceBaseUri']) if ($Id) { $uri.Path = "{0}/{1}" -f $uri.Path, $Id [void]$PSBoundParameters.Remove('id') } $pf = @{} if ($PSBoundParameters.ContainsKey('build_plan')) { $pf.Add('build_plan',@{'description'=$build_plan}) [void]$PSBoundParameters.Remove('build_plan') } if ($PSBoundParameters.ContainsKey('test_plan')) { $pf.Add('test_plan',@{'description'=$test_plan}) [void]$PSBoundParameters.Remove('test_plan') } if ($pf.Count -gt 0){$PSBoundParameters['planning_fields'] = $pf} $jsonBody = @{} $PSBoundParameters.keys.where{ $PSItem -notin $PrivateData.FreshserviceBodyExclusions }.foreach{ if ($PSBoundParameters[$PSItem] -is [datetime]) { $jsonBody[$PSItem.ToLower()] = (Get-Date -Date $PSBoundParameters[$PSItem]).ToUniversalTime() } else { $jsonBody[$PSItem.ToLower()] = $PSBoundParameters[$PSItem] } } try { if ($PSCmdlet.ShouldProcess($uri.Uri.AbsoluteUri)) { $params = @{ Uri = $uri.Uri.AbsoluteUri Method = 'PUT' ErrorAction = 'Stop' } if ( $attachments ) { if ( $PSVersionTable.PSVersion.Major -lt 7 ) { Write-Warning "Sorry! Attachments are not currently supported in versions earlier than Powershell 7.x due to multipart/form-data requirements. Attachment parameter will be ignored." $jsonBody.Remove('attachments') $params.Body = $jsonBody | ConvertTo-Json } else { #Invoke-WebRequest -Form is supported in 7+ $jsonBody.Add('attachments[]',$attachments) $jsonBody.Remove('attachments') $params.Form = $jsonBody } } else { $params.Body = $jsonBody | ConvertTo-Json } $result = Invoke-FreshworksRestMethod @params $content = $result.Content | ConvertFrom-Json if ($content) { #API returns singluar or plural property based on the number of records, parse to get property returned. $objProperty = $content[0].PSObject.Properties.Name Write-Verbose -Message ("Returning {0} property with count {1}" -f $objProperty, $content."$($objProperty)".Count) $content."$($objProperty)" } } } catch { Throw $_ } } end {} } |