Public/Settings.ps1
|
function New-TMSetting { <# .SYNOPSIS Creates a setting in TransitionManager. .DESCRIPTION Creates a TM setting with the supplied key and value. The function can optionally return the created setting object. .PARAMETER Name The setting key to create. .PARAMETER Value The value to assign to the setting. .PARAMETER TMSession A TMSession object or session name to use for the request. Defaults to `'Default'`. .PARAMETER Passthru Switch indicating that the created setting should be returned. .EXAMPLE New-TMSetting -Name 'DefaultWave' -Value 'Wave 1' -Passthru Creates a setting and returns the created setting object. #> [CmdletBinding()] param( [Parameter(Mandatory)] [string]$Name, [Parameter(Mandatory)] [psobject]$Value, [psobject]$TMSession = 'Default', [switch]$Passthru ) begin { $TMSession = Get-TMSession $TMSession $bodyParams = @{ category = 'SCRIPT_SETTING' key = $Name type = 'text' value = $Value } } process { try { $response = Invoke-TMRestMethod -Api setting -Method Post -BodyParams $bodyParams return $Passthru.IsPresent ? [TMSetting]::new($response) : $null } catch { if ($_.Exception.Message -match '.*Response: A duplicate key was encountered$') { throw "Setting '$Name' already exists" } } } } function Set-TMSetting { <# .SYNOPSIS Updates a setting in TransitionManager. .DESCRIPTION Updates a TM setting either from an existing `TMSetting` object or from individual setting properties such as id, key, and value. .PARAMETER TMSession A TMSession object or session name to use for the request. Defaults to `'Default'`. .PARAMETER TMSetting The setting object to update when using the `ByValue` parameter set. .PARAMETER Id The setting identifier to update when using the `ByProperty` parameter set. .PARAMETER Name The setting key to update when using the `ByProperty` parameter set. .PARAMETER ProjectId The project identifier associated with the setting. .PARAMETER Value The new setting value. .PARAMETER Format The storage format for the value, such as `json` or `text`. .PARAMETER Passthru Switch indicating that the updated setting should be returned. .EXAMPLE $setting = Get-TMSetting -Name 'DefaultWave' $setting.Value = 'Wave 2' Set-TMSetting -TMSetting $setting -Passthru Updates a setting from an existing `TMSetting` object and returns it. .EXAMPLE Set-TMSetting -Id 5 -Name 'DefaultWave' -Value 'Wave 2' -Format text -Passthru Updates a setting by specifying the setting properties directly. .NOTES Choose the parameter set that matches whether you already have a `TMSetting` object available. #> [CmdletBinding()] param ( [Parameter(Mandatory = $false, Position = 0)] [PSObject]$TMSession = 'Default', [Parameter(ParameterSetName = "ByValue", Mandatory, Position = 0)] [TMSetting] $TMSetting, [Parameter(ParameterSetName = "ByProperty", Mandatory = $true, ValueFromPipelineByPropertyName = $true)] [Object]$Id, [Parameter(ParameterSetName = "ByProperty", Mandatory = $true, ValueFromPipelineByPropertyName = $true)] [Alias('Key')] [String]$Name, [Parameter(ParameterSetName = "ByProperty", Mandatory = $false, ValueFromPipelineByPropertyName = $true)] [AllowNull()] [Alias('Project')] [Object]$ProjectId, [Parameter(ParameterSetName = "ByProperty", Mandatory = $true, ValueFromPipelineByPropertyName = $true)] [Object]$Value, [Parameter(Mandatory = $false, ValueFromPipelineByPropertyName = $true)] [ValidateSet('json', 'text')] [String]$Format = 'json', [Parameter(Mandatory = $false)] [Switch]$Passthru ) begin { if ($PSCmdlet.ParameterSetName -eq "ByValue") { $Id = $TMSetting.Id $ProjectId = $TMSetting.Project $Name = $TMSetting.Key $Value = $TMSetting.Value } # Get the session configuration Write-Verbose "Checking for cached TMSession" $TMSession = Get-TMSession $TMSession Write-Debug "TMSession:" Write-Debug ($TMSession | ConvertTo-Json -Depth 5) $bodyParams = @{ id = $Id category = 'SCRIPT_SETTING' key = $Name type = $Value -is [String] ? 'text' : 'json' value = $Value } if ($ProjectId -is [TMReference]) { $ProjectId = $ProjectId.Id } else { $ProjectId = $TMSession.Project.Id } } process { $Response = Invoke-TMRestMethod -Api "setting/$Id.$Format" -ApiParams "project=$ProjectId" -BodyParams $bodyParams -Method Put if ($Passthru) { [TMSetting]::new($Response) } } } function Get-TMSetting { <# .SYNOPSIS Gets settings from TransitionManager. .DESCRIPTION Retrieves TM settings either by identifier or by setting name. .PARAMETER TMSession A TMSession object or session name to use for the request. Defaults to `'Default'`. .PARAMETER Id The setting identifier to retrieve when using the `ById` parameter set. .PARAMETER Name The setting key to retrieve when using the `ByName` parameter set. .EXAMPLE Get-TMSetting -Id 5 Retrieves the setting with id `5`. .EXAMPLE Get-TMSetting -Name 'DefaultWave' Retrieves the setting named `DefaultWave`. .NOTES Use the parameter set that matches the identifier you have available. #> [CmdletBinding()] param( [Parameter()] [psobject]$TMSession = 'Default', [Parameter( ParameterSetName = 'ById', Mandatory, ValueFromPipelineByPropertyName )] [int]$Id, [Parameter( ParameterSetName = 'ByName', Mandatory, ValueFromPipelineByPropertyName )] [string]$Name ) begin { $TMSession = Get-TMSession $TMSession switch ($PSCmdlet.ParameterSetName) { ById { $api = 'setting/{0}' -f $Id } ByName { $api = 'setting/SCRIPT_SETTING/{0}.json' -f $Name.ToUpper() } } $uri = 'https://{0}/tdstm/api/{1}?project={2}' -f $TMSession.TMServer, $Api, $TMSession.UserContext.Project.Id } process { # cannot use invoke-tmrestmethod as this endpoint does not like # having a project passed in the body of the request try { $response = Invoke-RestMethod -Uri $uri -WebSession $TMSession.TMRestSession -Method Get } catch { if ($_.ErrorDetails.Message -match 'Requested information was not found') { switch ($PSCmdlet.ParameterSetName) { 'ById' { throw "Setting with Id '$Id' was not found" } 'ByName' { throw "Setting '$Name' was not found" } } } throw "Error getting TM Setting: $_" } return [TMSetting]::new($response) } } function Remove-TMSetting { <# .SYNOPSIS Removes a setting from TransitionManager. .DESCRIPTION Deletes a TM setting by using the supplied setting properties. .PARAMETER TMSession A TMSession object or session name to use for the request. Defaults to `'Default'`. .PARAMETER Id The setting identifier to remove. .PARAMETER Name The setting key to remove. .PARAMETER ProjectId The project identifier associated with the setting. .PARAMETER Value The setting value included in the delete request. .EXAMPLE $setting = Get-TMSetting -Name 'DefaultWave' Remove-TMSetting -Id $setting.Id -Name $setting.Key -Value $setting.Value Removes the specified setting from TransitionManager. .NOTES Provide the setting properties from a previously retrieved setting object when possible. #> [CmdletBinding()] param ( [Parameter(Mandatory = $false, Position = 0)] [PSObject]$TMSession = 'Default', [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)] [Object]$Id, [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)] [Alias('Key')] [String]$Name, [Parameter(Mandatory = $false, ValueFromPipelineByPropertyName = $true)] [AllowNull()] [Alias('Project')] [Object]$ProjectId, [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)] [Object]$Value ) begin { # Get the session configuration Write-Verbose "Checking for cached TMSession" $TMSession = Get-TMSession $TMSession Write-Debug 'TMSession:' Write-Debug ($TMSession | ConvertTo-Json -Depth 5) $bodyParams = @{ id = $Id category = 'SCRIPT_SETTING' key = $Name type = $Value -is [string] ? 'text' : 'json' value = $Value } } process { if ($ProjectId -is [TMReference]) { $ProjectId = $ProjectId.Id } else { $ProjectId = $TMSession.Project.Id } $Response = Invoke-TMRestMethod -Api setting/$Id -Method Delete -BodyParams $bodyParams if ($Response.deleted -eq 1) { return } } } |