spec.teamviewer.utilities

1.1.8

Public/Get-specTVPolicyGUIDFromName.ps1

Function Get-specTVPolicyGUIDFromName {
    <#
    .SYNOPSIS
        Retrieves the GUID of a TeamViewer policy based on its name.
 
    .DESCRIPTION
        This function takes the name of a TeamViewer policy and a secure API key as parameters. It retrieves all TeamViewer policies
        using the provided API key and searches for a policy with the specified name. If found, it returns a custom object with the
        PolicyName and PolicyGuid properties.
 
    .PARAMETER PolicyName
        Specifies the name of the TeamViewer policy to retrieve.
 
    .PARAMETER TVSecureAPIKey
        Specifies the secure API key for accessing TeamViewer policies. This must be in the format of a secure string.
 
    .EXAMPLE
        Get-specTVPolicyGUIDFromName -PolicyName "MyPolicy" -TVSecureAPIKey $SecureAPIKey
        Retrieves the GUID of the TeamViewer policy named "MyPolicy" using the specified secure API key.
 
    .EXAMPLE
        "Policy1", "Policy2" | Get-specTVPolicyGUIDFromName -TVSecureAPIKey $SecureAPIKey
        Retrieves the GUIDs of the TeamViewer policies named "Policy1" and "Policy2" using the specified secure API key through the pipeline.
 
    .OUTPUTS
        Returns a custom object with the following properties:
        - PolicyName (string): The name of the TeamViewer policy.
        - PolicyGuid (string): The GUID of the TeamViewer policy.
 
        - Returns 1 if there is an error.
 
    .NOTES
        Author: Owen Heaume
        Version: 1.0
    #>

    [cmdletbinding()]

    param (
        [Parameter(Mandatory = $true,
            ValueFromPipeline = $true)]
        [string[]]$PolicyName,

        [Parameter(Mandatory = $true)]
        [securestring]$TVSecureAPIKey
    )


    BEGIN {
        $OK = $true

        # Get all policies
        try {
            $allTVPolicies = Get-TeamViewerPolicy -ApiToken $TVSecureAPIKey
        } catch {
            Write-Warning "Unable to obtain policies using Get-TeamViewerPolicy. The error was: $($_.exception.message)"
            $OK = $false
        }
    }

    PROCESS {
        if ($OK) {
            foreach ($name in $PolicyName) {
                if ($Name -in ($allTVPolicies.name)) {
                    Write-Verbose "Found policy: $Name"
                    # now get the policy GUID
                    $PolicyGUID = ($allTVPolicies | where-object { $_.name -eq $Name }).id

                    [pscustomobject]@{
                        PolicyName = $name
                        PolicyGuid = $PolicyGUID
                    }
                } else {
                    Write-Warning "Policy '$name' could not be found"
                }
            }
        } else {
            # An error occurred - no processing took place
            return 1
        }
    }

    END {}
}