Public/Set-FreshServiceProject.ps1
|
<#
.SYNOPSIS Updates a Freshservice Project. .DESCRIPTION Updates a Freshservice Project via REST API. https://api.freshservice.com/#create_a_project_newgen Only users with "View or Manage Projects" privilege can access this API endpoint. .PARAMETER id Unique identifier of the project. .PARAMETER name Name of the project. The maximum number of characters allowed is 255. .PARAMETER description Description of the project in plain text or HTML format. .PARAMETER key Project Key. The key should start with a letter followed by a combination of letters, numbers or both. The maximum length is 10 characters. .PARAMETER status_id Status of the project. 1 = Yet to Start 2 = In Progress 3 = Completed .PARAMETER priority_id Priority of the project. Default is Medium (2). 1 = Low 2 = Medium 3 = High 4 = Urgent .PARAMETER project_type Type of the Project. 0 = Software 1 = Business .PARAMETER manager_id User ID of the project manager. .PARAMETER start_date Start date of the project. The acceptable format is yyyy-mm-dd. .PARAMETER end_date End date of the project. The acceptable format is yyyy-mm-dd. .PARAMETER visibility Visibility of the project. Default is Public (1). 0 = Private 1 = Public .PARAMETER sprint_duration Sprint duration in days for the project. Default is 14. .PARAMETER custom_fields Key value pairs containing the names and values of custom fields. .PARAMETER Archive Archive the project. .EXAMPLE Set-FreshServiceProject -id 1000320954 -priority 3 id : 1000320954 name : Project 1e49df30-7850-4a5b-a9b0-aefafdac192b key : P667977 description : Project 1e49df30-7850-4a5b-a9b0-aefafdac192b status_id : 2 priority_id : 3 sprint_duration : 14 project_type : 1 start_date : 2023-04-23 end_date : 2023-05-03 archived : False visibility : 1 manager_id : 21000418005 created_at : 4/24/2023 3:47:13 PM updated_at : 4/24/2023 3:47:16 PM custom_fields : Update a Freshservice Project status. .NOTES This module was developed and tested with Freshservice REST API v2. #> function Set-FreshServiceProject { [CmdletBinding(SupportsShouldProcess=$true, ConfirmImpact='Medium', DefaultParameterSetName = 'default')] param ( [Parameter( Mandatory = $true, HelpMessage = 'Unique identifier of the project.', ValueFromPipelineByPropertyName = $true, Position = 0 )] [long]$id, [Parameter( Mandatory = $false, HelpMessage = 'Name of the project. The maximum number of characters allowed is 255.', ParameterSetName = 'default', ValueFromPipelineByPropertyName = $true, Position = 1 )] [string]$name, [Parameter( Mandatory = $false, HelpMessage = 'Description of the project in plain text or HTML format.', ParameterSetName = 'default', ValueFromPipelineByPropertyName = $true, Position = 2 )] [string]$description, [Parameter( Mandatory = $false, HelpMessage = 'Project Key. The key should start with a letter followed by a combination of letters, numbers or both. The maximum length is 10 characters.', ParameterSetName = 'default', ValueFromPipelineByPropertyName = $true, Position = 3 )] [string]$key, [Parameter( Mandatory = $false, HelpMessage = 'Status of the project.', ValueFromPipelineByPropertyName = $true, ParameterSetName = 'default', Position = 4 )] [ValidateRange(1,3)] [int]$status_id, [Parameter( Mandatory = $false, HelpMessage = 'Priority of the project. Default is Medium.', ValueFromPipelineByPropertyName = $true, ParameterSetName = 'default', Position = 5 )] [ValidateRange(1,4)] [int]$priority_id, [Parameter( Mandatory = $false, HelpMessage = 'User ID of the project manager.', ValueFromPipelineByPropertyName = $true, ParameterSetName = 'default', Position = 6 )] [long]$manager_id, [Parameter( Mandatory = $false, HelpMessage = 'Start date of the project. The acceptable format is yyyy-mm-dd.', ValueFromPipelineByPropertyName = $true, ParameterSetName = 'default', Position = 7 )] [datetime]$start_date, [Parameter( Mandatory = $false, HelpMessage = 'End date of the project. The acceptable format is yyyy-mm-dd.', ValueFromPipelineByPropertyName = $true, ParameterSetName = 'default', Position = 8 )] [datetime]$end_date, [Parameter( Mandatory = $false, HelpMessage = 'Visibility of the project - Public / Private. Default is Public.', ValueFromPipelineByPropertyName = $true, ParameterSetName = 'default', Position = 9 )] [ValidateRange(0,1)] [int]$visibility, [Parameter( Mandatory = $false, HelpMessage = 'Sprint duration in days for the project.', ValueFromPipelineByPropertyName = $true, ParameterSetName = 'default', Position = 10 )] [int]$sprint_duration, [Parameter( Mandatory = $false, HelpMessage = 'Key value pairs containing the names and values of custom fields. Read more here.', ValueFromPipelineByPropertyName = $true, ParameterSetName = 'default', Position = 11 )] [hashtable]$custom_fields, [Parameter( Mandatory = $false, HelpMessage = 'Archive a project.', ValueFromPipelineByPropertyName = $true, ParameterSetName = 'Archive', Position = 1 )] [switch]$Archive ) 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 { $Method = 'PUT' $uri = [System.UriBuilder]('{0}/pm/projects' -f $PrivateData['FreshserviceBaseUri']) if ($PSBoundParameters.ContainsKey('id')) { $uri.Path = "{0}/{1}" -f $uri.Path, $id [void]$PSBoundParameters.Remove('Id') } if ($PSBoundParameters.ContainsKey('archive')) { $uri.Path = "{0}/archive" -f $uri.Path $Method = 'POST' [void]$PSBoundParameters.Remove('archive') } $jsonBody = @{} $PSBoundParameters.keys.where{ $PSItem -notin $PrivateData.FreshserviceBodyExclusions }.foreach{ if ($PSBoundParameters[$PSItem] -is [datetime]) { $jsonBody[$PSItem.ToLower()] = Get-Date -Date $PSBoundParameters[$PSItem] -Format "yyyy-MM-dd" } else { $jsonBody[$PSItem.ToLower()] = $PSBoundParameters[$PSItem] } } try { if ($PSCmdlet.ShouldProcess($uri.Uri.AbsoluteUri)) { $params = @{ Uri = $uri.Uri.AbsoluteUri Method = $Method Body = $jsonBody | ConvertTo-Json ErrorAction = 'Stop' } $result = Invoke-FreshworksRestMethod @params if ($Archive) { [PSCustomObject]@{ id = $id status = "success {0}" -f $result.StatusCode } } else { if ($result.Content) { $content = $result.Content | ConvertFrom-Json #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 {} } |