AddOrganizationalUnits

.vscode/.spelling

@@ -3,6 +3,10 @@ TeamViewer
 TeamViewer's
 TeamViewerPS
 TVPS
+Organizational Unit
+Organizational Units
+OrganizationalUnit
+OrganizationalUnits
 
 // Powershell
 cmdlet

CHANGELOG.md

@@ -4,6 +4,10 @@
 
 ### Added
 
+- Adds `Get-TeamViewerOrganizationalUnit` to retrieve the organizational unit details (beta phase, available only for specific tenants).
+- Adds `New-TeamViewerOrganizationalUnit` to add a new organizational unit (beta phase, available only for specific tenants).
+- Adds `Remove-TeamViewerOrganizationalUnit` to delete the organizational unit (beta phase, available only for specific tenants).
+- Adds `Set-TeamViewerOrganizationalUnit` to modify the organizational unit (beta phase, available only for specific tenants).
 - Adds `Get-TeamViewerRolePermission` to retrieve all supported role permissions.
 - Adds `Get-TeamViewerDeviceCustomField` to retrieve custom field values from a managed device.
 - Adds `Set-TeamViewerDeviceCustomField` to set or update a custom field value on a managed device.
@@ -15,6 +19,7 @@
 
 ### Changed
 
+- Fixes, completes, and improves help file `TeamViewerPS.md`.
 - Adds `OutputType` to public commands.
 - Adds `CmdletBinding` to public commands.
 - Standardizes pipeline emission on Write-Output.

Cmdlets/Private/ConvertTo-TeamViewerOrganizationalUnit.ps1

@@ -0,0 +1,24 @@
+function ConvertTo-TeamViewerOrganizationalUnit {
+    param(
+        [Parameter(ValueFromPipeline = $true, Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [PSObject]
+        $InputObject
+    )
+
+    process {
+        $properties = @{
+            Id          = $InputObject.id
+            Name        = $InputObject.name
+            Description = $InputObject.description
+            ParentId    = $InputObject.parentId
+            CreatedAt   = $InputObject.createdAt
+            UpdatedAt   = $InputObject.updatedAt
+        }
+
+        $result = New-Object -TypeName PSObject -Property $properties
+        $result.PSObject.TypeNames.Insert(0, 'TeamViewerPS.OrganizationalUnit')
+
+        Write-Output $result
+    }
+}

Cmdlets/Private/Resolve-TeamViewerOrganizationalUnitId.ps1

@@ -0,0 +1,24 @@
+function Resolve-TeamViewerOrganizationalUnitId {
+    param(
+        [Parameter(ValueFromPipeline = $true, Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [PSObject]
+        $OrganizationalUnit
+    )
+
+    process {
+        if ($OrganizationalUnit.PSObject.TypeNames -contains 'TeamViewerPS.OrganizationalUnit') {
+            Write-Output $OrganizationalUnit.Id
+        }
+        elseif ($OrganizationalUnit -is [string]) {
+            if ($OrganizationalUnit -notmatch '(?im)^[{(]?[0-9A-F]{8}[-]?(?:[0-9A-F]{4}[-]?){3}[0-9A-F]{12}[)}]?$') {
+                throw "Invalid organizational unit identifier '$OrganizationalUnit'. String must be an UUID."
+            }
+
+            $OrganizationalUnit
+        }
+        else {
+            throw "Invalid organizational unit identifier '$OrganizationalUnit'. Must be either a [TeamViewerPS.OrganizationalUnit] or [UUID]."
+        }
+    }
+}

Cmdlets/Public/Get-TeamViewerOrganizationalUnit.ps1

@@ -0,0 +1,99 @@
+function Get-TeamViewerOrganizationalUnit {
+        [CmdletBinding(DefaultParameterSetName = 'List')]
+
+        param(
+                [Parameter(Mandatory = $true)]
+                [ValidateNotNullOrEmpty()]
+                [Alias('Token')]
+                [securestring]
+                $ApiToken,
+
+                [Parameter(ValueFromPipeline = $true, Mandatory = $true, ParameterSetName = 'ById')]
+                [ValidateScript({ $_ | Resolve-TeamViewerOrganizationalUnitId })]
+                [Alias('Id', 'OrganizationalUnitId')]
+                [object]
+                $OrganizationalUnit,
+
+                [Parameter( Mandatory = $false, ParameterSetName = 'List')]
+                [Alias('IncludeChildren')]
+                [Switch]
+                $Recursive,
+
+                [Parameter( Mandatory = $false, ParameterSetName = 'List')]
+                [ValidateScript({ $_ -match '(?im)^[{(]?[0-9A-F]{8}[-]?(?:[0-9A-F]{4}[-]?){3}[0-9A-F]{12}[)}]?$' })]
+                [Alias('ParentId')]
+                [string]
+                $Parent,
+
+                [Parameter( Mandatory = $false, ParameterSetName = 'List')]
+                [ValidateLength(1, [int]::MaxValue)]
+                [string]
+                $Filter,
+
+                [Parameter( Mandatory = $false, ParameterSetName = 'List')]
+                [ValidateSet('Name', 'CreatedAt', 'UpdatedAt')]
+                [Alias('Sort')]
+                [string]
+                $SortBy = 'Name',
+
+                [Parameter( Mandatory = $false, ParameterSetName = 'List')]
+                [ValidateSet('Asc', 'Desc')]
+                [Alias('Order')]
+                [string]
+                $SortOrder = 'Asc',
+
+                [Parameter( Mandatory = $false, ParameterSetName = 'List')]
+                [ValidateRange(50, 250)]
+                [int]
+                $PageSize = 100,
+
+                [Parameter( Mandatory = $false, ParameterSetName = 'List')]
+                [ValidateRange(1, [int]::MaxValue)]
+                [int]
+                $PageNumber = 1
+        )
+
+        process {
+                $Uri = "$(Get-TeamViewerApiUri)/organizationalunits"
+                $Body = @{}
+
+                switch ($PSCmdlet.ParameterSetName) {
+                        'ById' {
+                                $OrganizationalUnitId = $OrganizationalUnit | Resolve-TeamViewerOrganizationalUnitId
+                                $Uri += "/$OrganizationalUnitId"
+                                $Body = $null
+                        }
+                        'List' {
+                                if ($Recursive) {
+                                        $Body.includeChildren = $true
+                                }
+                                if ($Parent) {
+                                        $Body.startOrganizationalUnitId = $Parent
+                                }
+                                if ($Filter) {
+                                        $Body.filter = $Filter
+                                }
+
+                                $Body.sortBy = $SortBy
+                                $Body.sortOrder = $SortOrder
+                                $Body.pageSize = $PageSize
+                                $Body.pageNumber = $PageNumber
+                        }
+                }
+
+                $Response = Invoke-TeamViewerRestMethod `
+                        -ApiToken $ApiToken `
+                        -Uri $Uri `
+                        -Method Get `
+                        -Body $Body `
+                        -WriteErrorTo $PSCmdlet `
+                        -ErrorAction Stop
+
+                if ($PSCmdlet.ParameterSetName -eq 'ById') {
+                        $Response | ConvertTo-TeamViewerOrganizationalUnit
+                }
+                else {
+                        $Response.data | ConvertTo-TeamViewerOrganizationalUnit
+                }
+        }
+}

Cmdlets/Public/New-TeamViewerOrganizationalUnit.ps1

@@ -0,0 +1,56 @@
+function New-TeamViewerOrganizationalUnit {
+        [CmdletBinding(SupportsShouldProcess = $true)]
+
+        param(
+                [Parameter(Mandatory = $true)]
+                [ValidateNotNullOrEmpty()]
+                [Alias('Token')]
+                [securestring]
+                $ApiToken,
+
+                [Parameter( Mandatory = $true)]
+                [ValidateLength(1, 100)]
+                [string]
+                $Name,
+
+                [Parameter(Mandatory = $false)]
+                [ValidateLength(1, 300)]
+                [string]
+                $Description,
+
+                [Parameter(Mandatory = $false)]
+                [ValidateScript({ $_ -match '(?im)^[{(]?[0-9A-F]{8}[-]?(?:[0-9A-F]{4}[-]?){3}[0-9A-F]{12}[)}]?$' })]
+                [Alias('ParentId')]
+                [string]
+                $Parent
+        )
+
+        begin {
+                $Uri = "$(Get-TeamViewerApiUri)/organizationalunits"
+
+                # Append parameters to request body
+                $Body = @{ name = $Name }
+
+                if ($Description) {
+                        $Body.description = $Description
+                }
+                if ($Parent) {
+                        $Body.parentId = $Parent
+                }
+        }
+
+        process {
+                if ($PSCmdlet.ShouldProcess($Name, 'Create organizational unit')) {
+                        $Response = Invoke-TeamViewerRestMethod `
+                                -ApiToken $ApiToken `
+                                -Uri $Uri `
+                                -Method Post `
+                                -ContentType 'application/json; charset=utf-8' `
+                                -Body ([System.Text.Encoding]::UTF8.GetBytes(($Body | ConvertTo-Json))) `
+                                -WriteErrorTo $PSCmdlet `
+                                -ErrorAction Stop
+
+                        $Response | ConvertTo-TeamViewerOrganizationalUnit
+                }
+        }
+}

Cmdlets/Public/Remove-TeamViewerOrganizationalUnit.ps1

@@ -0,0 +1,31 @@
+function Remove-TeamViewerOrganizationalUnit {
+    [CmdletBinding(SupportsShouldProcess = $true)]
+
+    param(
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [Alias('Token')]
+        [securestring]
+        $ApiToken,
+
+        [Parameter(ValueFromPipeline = $true, Mandatory = $true)]
+        [ValidateScript({ $_ | Resolve-TeamViewerOrganizationalUnitId })]
+        [Alias('Id', 'OrganizationalUnitId')]
+        [object]
+        $OrganizationalUnit
+    )
+
+    process {
+        $OrganizationalUnitId = $OrganizationalUnit | Resolve-TeamViewerOrganizationalUnitId
+        $Uri = "$(Get-TeamViewerApiUri)/organizationalunits/$OrganizationalUnitId"
+
+        if ($PSCmdlet.ShouldProcess($OrganizationalUnitId, 'Remove organizational unit')) {
+            Invoke-TeamViewerRestMethod `
+                -ApiToken $ApiToken `
+                -Uri $Uri `
+                -Method Delete `
+                -WriteErrorTo $PSCmdlet `
+                -ErrorAction Stop | Out-Null
+        }
+    }
+}

Cmdlets/Public/Set-TeamViewerOrganizationalUnit.ps1

@@ -0,0 +1,68 @@
+function Set-TeamViewerOrganizationalUnit {
+        [CmdletBinding(SupportsShouldProcess = $true)]
+
+        param(
+                [Parameter(Mandatory = $true)]
+                [ValidateNotNullOrEmpty()]
+                [Alias('Token')]
+                [securestring]
+                $ApiToken,
+
+                [Parameter(ValueFromPipeline = $true, Mandatory = $true)]
+                [ValidateScript({ $_ | Resolve-TeamViewerOrganizationalUnitId })]
+                [Alias('Id', 'OrganizationalUnitId')]
+                [object]
+                $OrganizationalUnit,
+
+                [Parameter(Mandatory = $false)]
+                [ValidateLength(1, 100)]
+                [string]
+                $Name,
+
+                [Parameter(Mandatory = $false)]
+                [ValidateLength(1, 300)]
+                [string]
+                $Description,
+
+                [Parameter(Mandatory = $false)]
+                [ValidateScript({ $_ -match '(?im)^[{(]?[0-9A-F]{8}[-]?(?:[0-9A-F]{4}[-]?){3}[0-9A-F]{12}[)}]?$' })]
+                [Alias('ParentId')]
+                [string]
+                $Parent
+        )
+
+        begin {
+                $Body = @{ }
+
+                # Append parameters to request body
+                if ($Name) {
+                        $Body.name = $Name
+                }
+
+                if ($Description) {
+                        $Body.description = $Description
+                }
+
+                if ($Parent) {
+                        $Body.parentId = $Parent
+                }
+        }
+
+        process {
+                $OrganizationalUnitId = $OrganizationalUnit | Resolve-TeamViewerOrganizationalUnitId
+                $Uri = "$(Get-TeamViewerApiUri)/organizationalunits/$OrganizationalUnitId"
+
+                if ($PSCmdlet.ShouldProcess($OrganizationalUnitId, 'Change organizational unit')) {
+                        $response = Invoke-TeamViewerRestMethod `
+                                -ApiToken $ApiToken `
+                                -Uri $Uri `
+                                -Method Put `
+                                -ContentType 'application/json; charset=utf-8' `
+                                -Body ([System.Text.Encoding]::UTF8.GetBytes(($Body | ConvertTo-Json))) `
+                                -WriteErrorTo $PSCmdlet `
+                                -ErrorAction Stop
+
+                        $response | ConvertTo-TeamViewerOrganizationalUnit
+                }
+        }
+}