From 46dab6d6fbaf1443fa08c9572da1809ab575691e Mon Sep 17 00:00:00 2001 From: skeller-tv <45237037+skeller-tv@users.noreply.github.com> Date: Thu, 25 May 2023 16:03:01 +0200 Subject: [PATCH] allow unmanage of Devices, add LastSeen field to managed devices (#17) Add new field "LastSeenAt" to devices fetched via API Add new function "Remove-TeamViewerManagedDeviceManagement" to allow unmanaging of devices --- Build/New-TeamViewerPSPackage.ps1 | 12 +- CHANGELOG.md | 4 +- .../ConvertTo-TeamViewerManagedDevice.ps1 | 4 +- ...move-TeamViewerManagedDeviceManagement.ps1 | 28 +++++ TeamViewerPS/TeamViewerPS.psd1 | 4 +- .../Get-TeamViewerManagedDevice.Tests.ps1 | 5 + ...eamViewerManagedDeviceManagement.Tests.ps1 | 45 +++++++ docs/about_TeamViewerPS.md | 2 + ...emove-TeamViewerManagedDeviceManagement.md | 116 ++++++++++++++++++ 9 files changed, 209 insertions(+), 11 deletions(-) create mode 100644 TeamViewerPS/Public/Remove-TeamViewerManagedDeviceManagement.ps1 create mode 100644 Tests/Public/Remove-TeamViewerManagedDeviceManagement.Tests.ps1 create mode 100644 docs/commands/Remove-TeamViewerManagedDeviceManagement.md diff --git a/Build/New-TeamViewerPSPackage.ps1 b/Build/New-TeamViewerPSPackage.ps1 index a0b8be5..c608dfe 100644 --- a/Build/New-TeamViewerPSPackage.ps1 +++ b/Build/New-TeamViewerPSPackage.ps1 @@ -18,7 +18,7 @@ New-Item -Type Directory "$BuildOutputPath/TeamViewerPS" | Out-Null # Compile all functions into a single psm file $targetFile = "$BuildOutputPath/TeamViewerPS/TeamViewerPS.psm1" -Write-Verbose "Compiling single-file TeamViewer module." +Write-Verbose 'Compiling single-file TeamViewer module.' $ModuleTypes = @(Get-ChildItem -Path "$repoPath/TeamViewerPS/TeamViewerPS.Types.ps1") $PrivateFunctions = @(Get-ChildItem ` -Path "$repoPath/TeamViewerPS/Private/*.ps1" ` @@ -31,10 +31,10 @@ Write-Verbose "Found $($PublicFunctions.Count) public function files." @($ModuleTypes + $PrivateFunctions + $PublicFunctions) | ` Get-Content -Raw | ` ForEach-Object { $_; "`r`n" } | ` - Set-Content -Path $targetFile -Encoding utf8NoBOM + Set-Content -Path $targetFile -Encoding UTF8 # Create help from markdown -Write-Verbose "Building help from Markdown" +Write-Verbose 'Building help from Markdown' New-ExternalHelp ` -Path "$repoPath/docs" ` -OutputPath "$BuildOutputPath/TeamViewerPS/en-US" | ` @@ -45,7 +45,7 @@ New-ExternalHelp ` Out-Null # Create module manifest -Write-Verbose "Creating module manifest" +Write-Verbose 'Creating module manifest' Copy-Item ` -Path "$repoPath/TeamViewerPS/TeamViewerPS.psd1" ` -Destination "$BuildOutputPath/TeamViewerPS/" @@ -58,7 +58,7 @@ Update-Metadata ` -Value $PublicFunctions.BaseName # Copy additional package files -Write-Verbose "Copying additional files into the package" +Write-Verbose 'Copying additional files into the package' Copy-Item ` -Path ` "$repoPath/LICENSE", ` @@ -66,7 +66,7 @@ Copy-Item ` "$repoPath/README.md"` -Destination "$BuildOutputPath/TeamViewerPS/" -Write-Verbose "Listing package files:" +Write-Verbose 'Listing package files:' Push-Location $BuildOutputPath Get-ChildItem -Recurse "$BuildOutputPath/TeamViewerPS" | ` Sort-Object -Property FullName | ` diff --git a/CHANGELOG.md b/CHANGELOG.md index 63438a7..9687455 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,14 +1,16 @@ # Change Log -## 1.x.0 (2023-0x-xx) +## 1.5.0 (2023-05-24) ### Added - Added `Remove-TeamViewerUser` cmdlet to remove user from TeamViewer company. (Thanks @OtterKring) +- Added `Remove-TeamViewerManagedDeviceManagement` to unmanage a device. ### Changed - Extended `Add-TeamViewerManager` to add user group as manager. (Thanks @OtterKring) +- Extended `TeamViewerManagedDevice` to have "LastSeenAt" available for managed devices ## 1.4.0 (2022-04-19) diff --git a/TeamViewerPS/Private/ConvertTo-TeamViewerManagedDevice.ps1 b/TeamViewerPS/Private/ConvertTo-TeamViewerManagedDevice.ps1 index fc5b456..d192832 100644 --- a/TeamViewerPS/Private/ConvertTo-TeamViewerManagedDevice.ps1 +++ b/TeamViewerPS/Private/ConvertTo-TeamViewerManagedDevice.ps1 @@ -12,8 +12,8 @@ function ConvertTo-TeamViewerManagedDevice { IsOnline = $InputObject.isOnline } - if ($InputObject.pendingOperation) { - $properties["PendingOperation"] = $InputObject.pendingOperation + if ($InputObject.last_seen) { + $properties['LastSeenAt'] = Get-Date -Date $InputObject.last_seen } if ($InputObject.teamviewerPolicyId) { diff --git a/TeamViewerPS/Public/Remove-TeamViewerManagedDeviceManagement.ps1 b/TeamViewerPS/Public/Remove-TeamViewerManagedDeviceManagement.ps1 new file mode 100644 index 0000000..202c001 --- /dev/null +++ b/TeamViewerPS/Public/Remove-TeamViewerManagedDeviceManagement.ps1 @@ -0,0 +1,28 @@ +function Remove-TeamViewerManagedDeviceManagement { + [CmdletBinding(SupportsShouldProcess = $true)] + param( + [Parameter(Mandatory = $true)] + [securestring] + $ApiToken, + + [Parameter(Mandatory = $true, ValueFromPipeline = $true)] + [ValidateScript( { $_ | Resolve-TeamViewerManagedDeviceId } )] + [Alias('DeviceId')] + [object] + $Device + ) + Process { + $deviceId = $Device | Resolve-TeamViewerManagedDeviceId + + $resourceUri = "$(Get-TeamViewerApiUri)/managed/devices/$deviceId" + + if ($PSCmdlet.ShouldProcess($deviceId, 'Remove Management from a device (clears all managers and groups)')) { + Invoke-TeamViewerRestMethod ` + -ApiToken $ApiToken ` + -Uri $resourceUri ` + -Method Delete ` + -WriteErrorTo $PSCmdlet | ` + Out-Null + } + } +} diff --git a/TeamViewerPS/TeamViewerPS.psd1 b/TeamViewerPS/TeamViewerPS.psd1 index f87c778..f369816 100644 --- a/TeamViewerPS/TeamViewerPS.psd1 +++ b/TeamViewerPS/TeamViewerPS.psd1 @@ -3,7 +3,7 @@ RootModule = 'TeamViewerPS.psm1' # Version number of this module. - ModuleVersion = '1.4.0' + ModuleVersion = '1.5.0' # Supported PSEditions. # CompatiblePSEditions = @() @@ -54,7 +54,7 @@ # TypesToProcess = @() # Format files (.ps1xml) to be loaded when importing this module. - FormatsToProcess = @('TeamViewerPS.format.ps1xml') + FormatsToProcess = @('TeamViewerPS.format.ps1xml') # Modules to import as nested modules of the module specified in RootModule/ModuleToProcess. # NestedModules = @() diff --git a/Tests/Public/Get-TeamViewerManagedDevice.Tests.ps1 b/Tests/Public/Get-TeamViewerManagedDevice.Tests.ps1 index 19a00bc..9aa85c9 100644 --- a/Tests/Public/Get-TeamViewerManagedDevice.Tests.ps1 +++ b/Tests/Public/Get-TeamViewerManagedDevice.Tests.ps1 @@ -97,12 +97,14 @@ Describe 'Get-TeamViewerManagedDevice' { name = 'test device 1' teamviewerId = 12345678 isOnline = $false + last_seen = '2023-02-03T11:14:19Z' }, @{ id = 'bc76c466-50dc-4b1f-963d-9b3a10a40ec6' name = 'test device 2' teamviewerId = 87654321 isOnline = $true + last_seen = '2023-02-03T11:14:19Z' } ) } } @@ -141,12 +143,14 @@ Describe 'Get-TeamViewerManagedDevice' { name = 'test device 1' teamviewerId = 12345678 isOnline = $false + last_seen = '2023-02-03T11:14:19Z' }, @{ id = 'bc76c466-50dc-4b1f-963d-9b3a10a40ec6' name = 'test device 2' teamviewerId = 87654321 isOnline = $true + last_seen = '2023-02-03T11:14:19Z' } ) } } @@ -158,6 +162,7 @@ Describe 'Get-TeamViewerManagedDevice' { name = 'test device 3' teamviewerId = 12345678 isOnline = $false + last_seen = '2023-02-03T11:14:19Z' } ) } } -ParameterFilter { $Body -And $Body['paginationToken'] -eq 'abc' } diff --git a/Tests/Public/Remove-TeamViewerManagedDeviceManagement.Tests.ps1 b/Tests/Public/Remove-TeamViewerManagedDeviceManagement.Tests.ps1 new file mode 100644 index 0000000..10571a2 --- /dev/null +++ b/Tests/Public/Remove-TeamViewerManagedDeviceManagement.Tests.ps1 @@ -0,0 +1,45 @@ +BeforeAll { + . "$PSScriptRoot/../../TeamViewerPS/Public/Remove-TeamViewerManagedDeviceManagement.ps1" + + @(Get-ChildItem -Path "$PSScriptRoot/../../TeamViewerPS/Private/*.ps1") | ` + ForEach-Object { . $_.FullName } + + $testApiToken = [securestring]@{} + $null = $testApiToken + $testDeviceId = 'c37e72b8-b78d-467f-923c-6083c13cf82f' + $null = $testDeviceId + + Mock Get-TeamViewerApiUri { '//unit.test' } + Mock Invoke-TeamViewerRestMethod { } +} + +Describe 'Remove-TeamViewerManagedDeviceManagement' { + It 'Should call the correct API endpoint' { + Remove-TeamViewerManagedDeviceManagement -ApiToken $testApiToken -DeviceId $testDeviceId + + Assert-MockCalled Invoke-TeamViewerRestMethod -Times 1 -Scope It -ParameterFilter { + $ApiToken -eq $testApiToken -And ` + $Uri -eq "//unit.test/managed/devices/$testDeviceId" -And ` + $Method -eq 'Delete' } + } + + It 'Should accept ManagedDevice objects' { + $testDeviceObj = @{ id = $testDeviceId } | ConvertTo-TeamViewerManagedDevice + Remove-TeamViewerManagedDeviceManagement -ApiToken $testApiToken -Device $testDeviceObj + + Assert-MockCalled Invoke-TeamViewerRestMethod -Times 1 -Scope It -ParameterFilter { + $ApiToken -eq $testApiToken -And ` + $Uri -eq "//unit.test/managed/devices/$testDeviceId" -And ` + $Method -eq 'Delete' } + } + + It 'Should accept pipeline input' { + $testDeviceObj = @{ id = $testDeviceId } | ConvertTo-TeamViewerManagedDevice + $testDeviceObj | Remove-TeamViewerManagedDeviceManagement -ApiToken $testApiToken + + Assert-MockCalled Invoke-TeamViewerRestMethod -Times 1 -Scope It -ParameterFilter { + $ApiToken -eq $testApiToken -And ` + $Uri -eq "//unit.test/managed/devices/$testDeviceId" -And ` + $Method -eq 'Delete' } + } +} diff --git a/docs/about_TeamViewerPS.md b/docs/about_TeamViewerPS.md index bcb2575..6c8fe9f 100644 --- a/docs/about_TeamViewerPS.md +++ b/docs/about_TeamViewerPS.md @@ -111,6 +111,8 @@ The following functions are available in this category: [`Remove-TeamViewerManagedDevice`](commands/Remove-TeamViewerManagedDevice.md) +[`Remove-TeamViewerManagedDeviceManagement`](commands/Remove-TeamViewerManagedDeviceManagement.md) + [`Remove-TeamViewerManagedGroup`](commands/Remove-TeamViewerManagedGroup.md) [`Remove-TeamViewerManager`](commands/Remove-TeamViewerManager.md) diff --git a/docs/commands/Remove-TeamViewerManagedDeviceManagement.md b/docs/commands/Remove-TeamViewerManagedDeviceManagement.md new file mode 100644 index 0000000..6c2197e --- /dev/null +++ b/docs/commands/Remove-TeamViewerManagedDeviceManagement.md @@ -0,0 +1,116 @@ +--- +external help file: TeamViewerPS-help.xml +Module Name: TeamViewerPS +online version: https://github.com/teamviewer/TeamViewerPS/blob/main/docs/commands/Remove-TeamViewerManagedDeviceManagement.md +schema: 2.0.0 +--- + +# Remove-TeamViewerManagedDevice + +## SYNOPSIS + +Removes the management status from a managed device. + +## SYNTAX + +```powershell +Remove-TeamViewerManagedDeviceManagement [-ApiToken] [-Device] [-WhatIf] + [-Confirm] [] +``` + +## DESCRIPTION + +Removes the management status from a managed device. +This makes the device unmanaged removing it from all groups and removing all managers. +The current account needs `ManagerAdministration` manager permissions on the device. + +## EXAMPLES + +### Example 1 + +```powershell +PS /> Remove-TeamViewerManagedDeviceManagement -Device 'c0cb303a-8a85-4e54-b657-a4757c791aef' +``` + +## PARAMETERS + +### -ApiToken + +The TeamViewer API access token. + +```yaml +Type: SecureString +Parameter Sets: (All) +Aliases: + +Required: True +Position: 0 +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 +``` + +### -Device + +Object that can be used to identify the managed device. +This can either be the managed device ID (as string or GUID) or a managed device +object that has been received using other module functions. + +```yaml +Type: Object +Parameter Sets: (All) +Aliases: DeviceId + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByValue) +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 +``` + +### 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 + +### System.Object + +## OUTPUTS + +## NOTES + +## RELATED LINKS