diff --git a/docs/commands/lists/Clear-TssList.md b/docs/commands/lists/Clear-TssList.md index fc258598..ff8f4757 100644 --- a/docs/commands/lists/Clear-TssList.md +++ b/docs/commands/lists/Clear-TssList.md @@ -1,7 +1,7 @@ # Clear-TssList ## SYNOPSIS -Clear all List options from the list +Clear all List categories and options from the list. ## SYNTAX @@ -10,7 +10,7 @@ Clear-TssList [-TssSession] -Id [-WhatIf] [-Confirm] [ -Id -OptionId [-WhatIf] [-Confirm] + [] +``` + +## DESCRIPTION +Clear a List option from a list + +## EXAMPLES + +### EXAMPLE 1 +``` +$session = New-TssSession -SecretServer https://alpha -Credential $ssCred +$options = Get-TssListOption -TssSession $session -Id 2d92c585-a3e1-4706-96b8-23ad2edda6b0 +$options | Where-Object Option -eq 'Option 2' | Clear-TssListOption -TssSession $session +``` + +Clear the "Option 1" from the List, will prompt to confirm the action since it is not reversible + +### EXAMPLE 2 +``` +$session = New-TssSession -SecretServer https://alpha -Credential $ssCred +$options = Get-TssListOption -TssSession $session -Id 2d92c585-a3e1-4706-96b8-23ad2edda6b0 +$options | Where-Object Option -eq 'Option 2' | Clear-TssListOption -TssSession $session -Confirm:$false +``` + +Clear the "Option 1" from the List, will **not** prompt to confirm the action since it is not reversible + +### EXAMPLE 3 +``` +$session = New-TssSession -SecretServer https://alpha -Credential $ssCred +$options = Get-TssListOption -TssSession $session -Id 2d92c585-a3e1-4706-96b8-23ad2edda6b0 +$options | Where-Object Option -match '^TBSERV' | Clear-TssListOption -TssSession $session -Confirm:$false +``` + +Clear all options that start with "TBSERV" from the List, will **not** prompt to confirm the action since it is not reversible + +## PARAMETERS + +### -TssSession +TssSession object created by New-TssSession for authentication + +```yaml +Type: Session +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -Id +Categorized List ID + +```yaml +Type: String +Parameter Sets: (All) +Aliases: CategorizedListId + +Required: True +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -OptionId +The List's Option Id to clear + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: CategorizedListItemId + +Required: True +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -WhatIf +Shows what would happen if the cmdlet runs. +The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +### Thycotic.PowerShell.Common.Delete +## NOTES +Requires TssSession object returned by New-TssSession + +## RELATED LINKS + +[https://thycotic-ps.github.io/thycotic.secretserver/commands/lists/Clear-TssListOption](https://thycotic-ps.github.io/thycotic.secretserver/commands/lists/Clear-TssListOption) + +[https://github.com/thycotic-ps/thycotic.secretserver/blob/main/src/functions/lists/Clear-TssListOption.ps1](https://github.com/thycotic-ps/thycotic.secretserver/blob/main/src/functions/lists/Clear-TssListOption.ps1) + diff --git a/src/functions/lists/Clear-TssListOption.ps1 b/src/functions/lists/Clear-TssListOption.ps1 new file mode 100644 index 00000000..98d0b7da --- /dev/null +++ b/src/functions/lists/Clear-TssListOption.ps1 @@ -0,0 +1,94 @@ +function Clear-TssListOption { + <# + .SYNOPSIS + Clear a List option from a list + + .DESCRIPTION + Clear a List option from a list + + .EXAMPLE + $session = New-TssSession -SecretServer https://alpha -Credential $ssCred + $options = Get-TssListOption -TssSession $session -Id 2d92c585-a3e1-4706-96b8-23ad2edda6b0 + $options | Where-Object Option -eq 'Option 2' | Clear-TssListOption -TssSession $session + + Clear the "Option 1" from the List, will prompt to confirm the action since it is not reversible + + .EXAMPLE + $session = New-TssSession -SecretServer https://alpha -Credential $ssCred + $options = Get-TssListOption -TssSession $session -Id 2d92c585-a3e1-4706-96b8-23ad2edda6b0 + $options | Where-Object Option -eq 'Option 2' | Clear-TssListOption -TssSession $session -Confirm:$false + + Clear the "Option 1" from the List, will **not** prompt to confirm the action since it is not reversible + + .EXAMPLE + $session = New-TssSession -SecretServer https://alpha -Credential $ssCred + $options = Get-TssListOption -TssSession $session -Id 2d92c585-a3e1-4706-96b8-23ad2edda6b0 + $options | Where-Object Option -match '^TBSERV' | Clear-TssListOption -TssSession $session -Confirm:$false + + Clear all options that start with "TBSERV" from the List, will **not** prompt to confirm the action since it is not reversible + + .LINK + https://thycotic-ps.github.io/thycotic.secretserver/commands/lists/Clear-TssListOption + + .LINK + https://github.com/thycotic-ps/thycotic.secretserver/blob/main/src/functions/lists/Clear-TssListOption.ps1 + + .NOTES + Requires TssSession object returned by New-TssSession + #> + [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'High')] + [OutputType('Thycotic.PowerShell.Common.Delete')] + param ( + # TssSession object created by New-TssSession for authentication + [Parameter(Mandatory, ValueFromPipeline, Position = 0)] + [Thycotic.PowerShell.Authentication.Session] + $TssSession, + + # Categorized List ID + [Parameter(Mandatory, ValueFromPipelineByPropertyName)] + [Alias('CategorizedListId')] + [string] + $Id, + + # The List's Option Id to clear + [Parameter(Mandatory, ValueFromPipelineByPropertyName)] + [Alias('CategorizedListItemId')] + [string[]] + $OptionId + ) + begin { + $tssParams = $PSBoundParameters + $invokeParams = . $GetInvokeApiParams $TssSession + } + process { + Get-TssInvocation $PSCmdlet.MyInvocation + if ($tssParams.ContainsKey('TssSession') -and $TssSession.IsValidSession()) { + Compare-TssVersion $TssSession '11.0.000005' $PSCmdlet.MyInvocation + foreach ($option in $OptionId) { + $uri = $TssSession.ApiUrl, 'lists', $Id, 'options', $option -join '/' + $invokeParams.Uri = $uri + $invokeParams.Method = 'DELETE' + + if ($PSCmdlet.ShouldProcess("List: $Id", "$($invokeParams.Method) $uri")) { + Write-Verbose "$($invokeParams.Method) $uri" + try { + $apiResponse = Invoke-TssApi @invokeParams + $restResponse = . $ProcessResponse $apiResponse + } catch { + Write-Warning 'Issue clearing List [$list] option [$option]' + $err = $_ + . $ErrorHandling $err + } + + if ($restResponse.isDeleted) { + Write-Verbose "Option [$option] successfully cleared from List [$Id]" + } else { + Write-Warning "Option [$option] was not cleared from List [$Id]" + } + } + } + } else { + Write-Warning 'No valid session found' + } + } +} \ No newline at end of file diff --git a/tests/lists/Add-TssListOption.Tests.ps1 b/tests/lists/Add-TssListOption.Tests.ps1 new file mode 100644 index 00000000..d4d8af98 --- /dev/null +++ b/tests/lists/Add-TssListOption.Tests.ps1 @@ -0,0 +1,24 @@ +BeforeDiscovery { + $commandName = Split-Path ($PSCommandPath.Replace('.Tests.ps1','')) -Leaf +} +Describe "$commandName verify parameters" { + BeforeDiscovery { + [object[]]$knownParameters = 'TssSession', 'Id', 'Category', 'Option' + [object[]]$currentParams = ([Management.Automation.CommandMetaData]$ExecutionContext.SessionState.InvokeCommand.GetCommand($commandName,'Function')).Parameters.Keys + [object[]]$commandDetails = [System.Management.Automation.CommandInfo]$ExecutionContext.SessionState.InvokeCommand.GetCommand($commandName,'Function') + $unknownParameters = Compare-Object -ReferenceObject $knownParameters -DifferenceObject $currentParams -PassThru + } + Context "Verify parameters" -Foreach @{currentParams = $currentParams } { + It "$commandName should contain <_> parameter" -TestCases $knownParameters { + $_ -in $currentParams | Should -Be $true + } + It "$commandName should not contain parameter: <_>" -TestCases $unknownParameters { + $_ | Should -BeNullOrEmpty + } + } + Context "Command specific details" { + It "$commandName should set OutputType to Thycotic.PowerShell.List.ListItem" -TestCases $commandDetails { + $_.OutputType.Name | Should -Be 'Thycotic.PowerShell.List.ListItem' + } + } +} \ No newline at end of file