From 96ab3b2d5a5e323a9dd6ee57885b45a65a9e68b8 Mon Sep 17 00:00:00 2001 From: JP-Consulting Date: Tue, 16 Dec 2025 20:48:32 +0100 Subject: [PATCH] Add Rename-PASPlatform command with documentation and tests --- Tests/Rename-PASPlatform.Tests.ps1 | 117 ++++++++++++++ .../_commands/Rename-PASPlatform.md | 125 ++++++++++++++ docs/collections/_pages/commands.md | 3 + .../Platforms/Rename-PASPlatform.ps1 | 44 +++++ psPAS/en-US/psPAS-help.xml | 152 ++++++++++++++++++ psPAS/psPAS.psd1 | 1 + 6 files changed, 442 insertions(+) create mode 100644 Tests/Rename-PASPlatform.Tests.ps1 create mode 100644 docs/collections/_commands/Rename-PASPlatform.md create mode 100644 psPAS/Functions/Platforms/Rename-PASPlatform.ps1 diff --git a/Tests/Rename-PASPlatform.Tests.ps1 b/Tests/Rename-PASPlatform.Tests.ps1 new file mode 100644 index 00000000..738881ff --- /dev/null +++ b/Tests/Rename-PASPlatform.Tests.ps1 @@ -0,0 +1,117 @@ +Describe $($PSCommandPath -Replace '.Tests.ps1') { + + BeforeAll { + #Get Current Directory + $Here = Split-Path -Parent $PSCommandPath + + #Assume ModuleName from Repository Root folder + $ModuleName = Split-Path (Split-Path $Here -Parent) -Leaf + + #Resolve Path to Module Directory + $ModulePath = Resolve-Path "$Here\..\$ModuleName" + + #Define Path to Module Manifest + $ManifestPath = Join-Path "$ModulePath" "$ModuleName.psd1" + + if ( -not (Get-Module -Name $ModuleName -All)) { + + Import-Module -Name "$ManifestPath" -ArgumentList $true -Force -ErrorAction Stop + + } + + $Script:RequestBody = $null + $psPASSession = [ordered]@{ + BaseURI = 'https://SomeURL/SomeApp' + User = $null + ExternalVersion = [System.Version]'0.0' + WebSession = New-Object Microsoft.PowerShell.Commands.WebRequestSession + StartTime = $null + ElapsedTime = $null + LastCommand = $null + LastCommandTime = $null + LastCommandResults = $null + } + + New-Variable -Name psPASSession -Value $psPASSession -Scope Script -Force + + } + + + AfterAll { + + $Script:RequestBody = $null + + } + + InModuleScope $(Split-Path (Split-Path (Split-Path -Parent $PSCommandPath) -Parent) -Leaf ) { + + BeforeEach { + Mock Invoke-PASRestMethod -MockWith { } + + Rename-PASPlatform -ID 42 -Name 'NewPlatformName' + } + + Context 'Input' { + + It 'sends request' { + + Assert-MockCalled Invoke-PASRestMethod -Scope It + + } + + It 'sends request to expected endpoint' { + + Assert-MockCalled Invoke-PASRestMethod -ParameterFilter { + + $URI -eq "$($Script:psPASSession.BaseURI)/API/Platforms/targets/42" + + } -Scope It + + } + + It 'uses expected method' { + + Assert-MockCalled Invoke-PASRestMethod -ParameterFilter { $Method -match 'PUT' } -Times 1 -Exactly -Scope It + + } + + It 'sends request with expected body' { + + Assert-MockCalled Invoke-PASRestMethod -ParameterFilter { + If ($null -ne $Body) { + $($Body | ConvertFrom-Json | Select-Object -ExpandProperty Name) -eq 'NewPlatformName' + } + } -Scope It -Times 1 + + } + + It 'throws error if version requirement not met' { + $psPASSession.ExternalVersion = '1.0' + { Rename-PASPlatform -ID 42 -Name 'NewPlatformName' } | Should -Throw + $psPASSession.ExternalVersion = '0.0' + } + + It 'throws error if run against Privilege Cloud' { + $psPASSession.BaseURI = 'https://something.cyberark.cloud' + { Rename-PASPlatform -ID 42 -Name 'NewPlatformName' } | Should -Throw + $psPASSession.BaseURI = 'https://SomeURL/SomeApp' + } + + } + + Context 'Output' { + + It 'provides no output' { + Mock Invoke-PASRestMethod -MockWith { } + + $response = Rename-PASPlatform -ID 42 -Name 'NewPlatformName' + + $response | Should -BeNullOrEmpty + + } + + } + + } + +} diff --git a/docs/collections/_commands/Rename-PASPlatform.md b/docs/collections/_commands/Rename-PASPlatform.md new file mode 100644 index 00000000..0119e3a9 --- /dev/null +++ b/docs/collections/_commands/Rename-PASPlatform.md @@ -0,0 +1,125 @@ +--- +category: PSPAS +external help file: psPAS-help.xml +Module Name: psPAS +online version: https://pspas.pspete.dev/commands/Rename-PASPlatform +schema: 2.0.0 +title: Rename-PASPlatform +--- + +# Rename-PASPlatform + +## SYNOPSIS +Renames a target platform. + +## SYNTAX + +``` +Rename-PASPlatform -ID -Name [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION +Renames an existing target platform. + +The user must be a member of the Vault Admins group. + +This command is only applicable to Self-Hosted implementations. + +## EXAMPLES + +### EXAMPLE 1 +``` +Rename-PASPlatform -ID 42 -Name "NewPlatformName" +``` + +Renames the target platform with ID 42 to "NewPlatformName" + +### EXAMPLE 2 +``` +Get-PASPlatform -PlatformType Target | Where-Object {$_.Name -eq "OldName"} | Rename-PASPlatform -Name "NewName" +``` + +Finds a target platform by name and renames it + +## PARAMETERS + +### -ID +The unique ID of the platform to rename. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: 0 +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -Name +The new name for the platform. + +Platform names must be unique across the system. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +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 + +## NOTES +Minimum version 15.0 + +Self-Hosted implementations only + +## RELATED LINKS + +[https://pspas.pspete.dev/commands/Rename-PASPlatform](https://pspas.pspete.dev/commands/Rename-PASPlatform) + +[https://docs.cyberark.com/pam-self-hosted/latest/en/content/sdk/rest-api-update-target-platform.htm](https://docs.cyberark.com/pam-self-hosted/latest/en/content/sdk/rest-api-update-target-platform.htm) diff --git a/docs/collections/_pages/commands.md b/docs/collections/_pages/commands.md index 67d54af5..66c455cc 100644 --- a/docs/collections/_pages/commands.md +++ b/docs/collections/_pages/commands.md @@ -108,6 +108,7 @@ A psPAS command may not appear in the below list due to it not being explicitly [Activate target platform][Activate target platform] | [Enable-PASPlatform][Enable-PASPlatform] [Deactivate target platform][Deactivate target platform] | [Disable-PASPlatform][Disable-PASPlatform] [Delete target platform][Delete target platform] | [Remove-PASPlatform][Remove-PASPlatform] +[Rename target platform][Rename target platform] | [Rename-PASPlatform][Rename-PASPlatform] [Get dependent platforms][Get dependent platforms] | [Get-PASPlatform][Get-PASPlatform] [Duplicate dependent platforms][Duplicate dependent platforms] | [Copy-PASPlatform][Copy-PASPlatform] [Delete dependent platform][Delete dependent platform] | [Remove-PASPlatform][Remove-PASPlatform] @@ -409,6 +410,7 @@ A psPAS command may not appear in the below list due to it not being explicitly [Disable-PASPlatform]:/commands/Disable-PASPlatform [Enable-PASPlatform]:/commands/Enable-PASPlatform [Remove-PASPlatform]:/commands/Remove-PASPlatform +[Rename-PASPlatform]:/commands/Rename-PASPlatform [Remove-PASGroup]:/commands/Remove-PASGroup [Add-PASOpenIDConnectProvider]:/commands/Add-PASOpenIDConnectProvider [Get-PASOpenIDConnectProvider]:/commands/Get-PASOpenIDConnectProvider @@ -559,6 +561,7 @@ A psPAS command may not appear in the below list due to it not being explicitly [Activate target platform]:https://docs.cyberark.com/Product-Doc/OnlineHelp/PAS/Latest/en/Content/SDK/rest-api-activate-target-platform.htm [Deactivate target platform]:https://docs.cyberark.com/Product-Doc/OnlineHelp/PAS/Latest/en/Content/SDK/rest-api-deactivate-target-platform.htm [Delete target platform]:https://docs.cyberark.com/Product-Doc/OnlineHelp/PAS/Latest/en/Content/SDK/rest-api-delete-target-platform.htm +[Rename target platform]:https://docs.cyberark.com/pam-self-hosted/latest/en/content/sdk/rest-api-update-target-platform.htm [Get dependent platforms]:https://docs.cyberark.com/Product-Doc/OnlineHelp/PAS/Latest/en/Content/SDK/rest-api-get-dependent-platforms.htm [Duplicate dependent platforms]:https://docs.cyberark.com/Product-Doc/OnlineHelp/PAS/Latest/en/Content/SDK/rest-api-duplicate-dependent-platforms.htm [Delete dependent platform]:https://docs.cyberark.com/Product-Doc/OnlineHelp/PAS/Latest/en/Content/SDK/rest-api-delete-dependent-platform.htm diff --git a/psPAS/Functions/Platforms/Rename-PASPlatform.ps1 b/psPAS/Functions/Platforms/Rename-PASPlatform.ps1 new file mode 100644 index 00000000..89437666 --- /dev/null +++ b/psPAS/Functions/Platforms/Rename-PASPlatform.ps1 @@ -0,0 +1,44 @@ +# .ExternalHelp psPAS-help.xml +function Rename-PASPlatform { + [CmdletBinding(SupportsShouldProcess)] + param( + [parameter( + Mandatory = $true, + ValueFromPipelinebyPropertyName = $true + )] + [int]$ID, + + [parameter( + Mandatory = $true, + ValueFromPipelinebyPropertyName = $true + )] + [string]$Name + ) + + begin { + Assert-VersionRequirement -SelfHosted + Assert-VersionRequirement -RequiredVersion 15.0 + }#begin + + process { + + #Create URL for request + $URI = "$($psPASSession.BaseURI)/API/Platforms/targets/$ID" + + #Get request parameters + $boundParameters = $PSBoundParameters | Get-PASParameter -ParametersToRemove ID + + $body = $boundParameters | ConvertTo-Json + + if ($PSCmdlet.ShouldProcess($ID, "Update Target Platform Name")) { + + #send request to web service + Invoke-PASRestMethod -Uri $URI -Method PUT -Body $body + + } + + }#process + + end { }#end + +} diff --git a/psPAS/en-US/psPAS-help.xml b/psPAS/en-US/psPAS-help.xml index 1e2a3d79..aeb328f5 100644 --- a/psPAS/en-US/psPAS-help.xml +++ b/psPAS/en-US/psPAS-help.xml @@ -40088,6 +40088,158 @@ Publish-PASDiscoveredAccount -id 66_6 -PlatformID WinDomain -safeName SomeSafe - + + + Rename-PASPlatform + Rename + PASPlatform + + Renames a target platform. + + + + Renames an existing target platform. + The user must be a member of the Vault Admins group. + This command is only applicable to Self-Hosted implementations. + + + + Rename-PASPlatform + + ID + + The unique ID of the platform to rename. + + Int32 + + Int32 + + + 0 + + + Name + + The new name for the platform. + Platform names must be unique across the system. + + String + + String + + + None + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + + SwitchParameter + + + False + + + + + + ID + + The unique ID of the platform to rename. + + Int32 + + Int32 + + + 0 + + + Name + + The new name for the platform. + Platform names must be unique across the system. + + String + + String + + + None + + + WhatIf + + Shows what would happen if the cmdlet runs. The cmdlet is not run. + + SwitchParameter + + SwitchParameter + + + False + + + Confirm + + Prompts you for confirmation before running the cmdlet. + + SwitchParameter + + SwitchParameter + + + False + + + + + + + Minimum version 15.0 + Self-Hosted implementations only + + + + + -------------------------- EXAMPLE 1 -------------------------- + Rename-PASPlatform -ID 42 -Name "NewPlatformName" + + Renames the target platform with ID 42 to "NewPlatformName" + + + + -------------------------- EXAMPLE 2 -------------------------- + Get-PASPlatform -PlatformType Target | Where-Object {$_.Name -eq "OldName"} | Rename-PASPlatform -Name "NewName" + + Finds a target platform by name and renames it + + + + + + https://pspas.pspete.dev/commands/Rename-PASPlatform + https://pspas.pspete.dev/commands/Rename-PASPlatform + + + https://docs.cyberark.com/pam-self-hosted/latest/en/content/sdk/rest-api-update-target-platform.htm + https://docs.cyberark.com/pam-self-hosted/latest/en/content/sdk/rest-api-update-target-platform.htm + + + Request-PASJustInTimeAccess diff --git a/psPAS/psPAS.psd1 b/psPAS/psPAS.psd1 index 41766bf1..e8ad1b4c 100644 --- a/psPAS/psPAS.psd1 +++ b/psPAS/psPAS.psd1 @@ -189,6 +189,7 @@ 'Disable-PASPlatform', 'Enable-PASPlatform', 'Remove-PASPlatform', + 'Rename-PASPlatform', 'Remove-PASGroup', 'Get-PASAllowedReferrer', 'Add-PASAllowedReferrer',