Public/Metaverse/Remove-JIMMetaverseObjectType.ps1
|
# Copyright (c) Tetron Limited. All rights reserved. # Licensed under the Tetron Commercial License. See LICENSE file in the project root. function Remove-JIMMetaverseObjectType { <# .SYNOPSIS Deletes a custom Metaverse Object Type from JIM. .DESCRIPTION Deletes a custom Metaverse Object Type. The cmdlet first fetches a delete preview to decide how to proceed: - Built-in types (User, Group) can never be deleted; the cmdlet refuses. - If any Metaverse Object of the type exists, deletion is a hard block; the cmdlet refuses and reports the object count. Delete the objects first. - If any Synchronisation Rule targets the type, deletion is a hard block (deleting the type would otherwise cascade-delete the whole rule); the cmdlet refuses and lists the rules. Remove the Synchronisation Rules first. - Otherwise the type is deleted, cascade-removing its softer references (Predefined Searches, Example Data Templates, and custom attribute bindings; the bound attributes themselves are kept). This is guarded server-side by a type-the-name confirmation, which the cmdlet satisfies automatically once you confirm (or pass -Force); the cascade is recorded as child Activities. .PARAMETER Id The ID of the Object Type to delete. .PARAMETER Name The name of the Object Type to delete. .PARAMETER ChangeReason An optional reason for the deletion, recorded in the Object Type's Configuration Change History. .PARAMETER Force Suppresses the confirmation prompt. The cmdlet still gives the name confirmation JIM requires before it removes the configuration that goes with the Object Type. .OUTPUTS None. .EXAMPLE Remove-JIMMetaverseObjectType -Id 5 Deletes Object Type 5 after confirmation, cascade-removing its Predefined Searches, Example Data Template entries and attribute bindings. .EXAMPLE Remove-JIMMetaverseObjectType -Name 'Device' -Force Deletes the 'Device' Object Type without an interactive prompt. .LINK Get-JIMMetaverseObjectType New-JIMMetaverseObjectType Set-JIMMetaverseObjectType #> [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'High', DefaultParameterSetName = 'ById')] [OutputType([void])] param( [Parameter(Mandatory, ParameterSetName = 'ById', ValueFromPipelineByPropertyName)] [int]$Id, [Parameter(Mandatory, ParameterSetName = 'ByName')] [ValidateNotNullOrEmpty()] [string]$Name, [Parameter()] [ValidateNotNullOrEmpty()] [string]$ChangeReason, [switch]$Force ) process { # Check connection first if (-not $script:JIMConnection) { Write-Error "You are not connected to JIM. Run Connect-JIM -Url <your JIM URL> to authenticate, then try again." return } # Resolve name to ID if using ByName parameter set if ($PSCmdlet.ParameterSetName -eq 'ByName') { try { $resolvedType = Resolve-JIMMetaverseObjectType -Name $Name $Id = $resolvedType.id } catch { Write-Error $_ return } } # Fetch the delete preview to decide how to proceed and to obtain the exact type name for the # server's type-the-name confirmation. try { $impact = Invoke-JIMApi -Endpoint "/api/v1/metaverse/object-types/$Id/delete-preview" } catch { Write-Error "Failed to evaluate deletion of Metaverse Object Type ${Id}: $_" return } if ($impact.builtIn) { Write-Error "Cannot delete '$($impact.objectTypeName)': built-in Metaverse Object Types cannot be deleted." return } if ($impact.blockedByObjects) { Write-Error "Cannot delete '$($impact.objectTypeName)': $($impact.metaverseObjectCount) Metaverse Object(s) of this type exist. Delete the objects first, then retry." return } if ($impact.blockedBySynchronisationRules) { $ruleNames = ($impact.synchronisationRules | ForEach-Object { $_.description }) -join ', ' Write-Error "Cannot delete '$($impact.objectTypeName)': $($impact.synchronisationRules.Count) Synchronisation Rule(s) target this type ($ruleNames). Remove those Synchronisation Rules first, then retry." return } $cascadeCount = if ($impact.cascadeReferences) { @($impact.cascadeReferences).Count } else { 0 } $action = if ($cascadeCount -gt 0) { "Delete Metaverse Object Type and cascade-remove $cascadeCount reference(s)" } else { "Delete Metaverse Object Type" } if ($Force -and -not $PSBoundParameters.ContainsKey('Confirm')) { $ConfirmPreference = 'None' } if ($PSCmdlet.ShouldProcess($impact.objectTypeName, $action)) { Write-Verbose "Deleting Metaverse Object Type '$($impact.objectTypeName)'; references to cascade: $cascadeCount" try { # Always send confirmationName: the server requires it to match when references exist # and ignores it otherwise. $query = "confirmationName=$([uri]::EscapeDataString([string]$impact.objectTypeName))" if ($ChangeReason) { $query += "&changeReason=$([uri]::EscapeDataString($ChangeReason))" } $null = Invoke-JIMApi -Endpoint "/api/v1/metaverse/object-types/$Id`?$query" -Method 'DELETE' Write-Verbose "Deleted Metaverse Object Type '$($impact.objectTypeName)'" } catch { Write-Error "Failed to delete Metaverse Object Type '$($impact.objectTypeName)': $_" } } } } |