Public/Metaverse/Test-JIMMetaverseAttributeName.ps1
|
# Copyright (c) Tetron Limited. All rights reserved. # Licensed under the Tetron Commercial License. See LICENSE file in the project root. function Test-JIMMetaverseAttributeName { <# .SYNOPSIS Tests whether a Metaverse Attribute name is available. .DESCRIPTION Checks whether a name is free to use for a custom Metaverse Attribute. The comparison is case-insensitive, so "CostCentre" is reported as taken if "costCentre" already exists. Returns $true when the name is available, $false when it is already in use. When renaming an existing attribute, pass its ID to -ExcludeId so the attribute's own name does not count as a clash. .PARAMETER Name The attribute name to test. .PARAMETER ExcludeId The ID of an attribute to leave out of the check. Pass the attribute's own ID when renaming it, so its current name does not count as taken. .OUTPUTS $true when the name is free, or $false when an attribute already has it. .EXAMPLE Test-JIMMetaverseAttributeName -Name "CostCentre" Returns $true if no attribute already uses that name (case-insensitively). .EXAMPLE if (Test-JIMMetaverseAttributeName -Name "CostCentre") { New-JIMMetaverseAttribute -Name "CostCentre" -Type Text } Guards a create call with an availability check. .EXAMPLE Test-JIMMetaverseAttributeName -Name "CostCentre" -ExcludeId 42 Checks availability while renaming attribute 42, ignoring its own current name. .LINK New-JIMMetaverseAttribute Set-JIMMetaverseAttribute Get-JIMMetaverseAttribute #> [CmdletBinding()] [OutputType([bool])] param( [Parameter(Mandatory)] [ValidateNotNullOrEmpty()] [string]$Name, [Parameter()] [int]$ExcludeId ) 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 } try { $endpoint = "/api/v1/metaverse/attributes/name-availability?name=$([uri]::EscapeDataString($Name))" if ($PSBoundParameters.ContainsKey('ExcludeId')) { $endpoint += "&excludeId=$ExcludeId" } $result = Invoke-JIMApi -Endpoint $endpoint [bool]$result.available } catch { Write-Error "Failed to check availability of Metaverse Attribute name '$Name': $_" } } } |