Functions/Get-MSPCompleteEndpointWithCredential.ps1

<#
.SYNOPSIS
    This function retrieves a copy of the given MSPComplete Endpoint with a "Credential" property.
.DESCRIPTION
    This function retrieves a copy of the given MSPComplete Endpoint with a "Credential" property.
    The property is a PSCredential object storing the username and password.
#>

function Get-MSPCompleteEndpointWithCredential {
    param (
        # The ID of the MSPComplete Endpoint.
        [Parameter(Mandatory=$true, ParameterSetName="endpointID")]
        [String]$endpointID,

        # The MSPComplete Endpoint.
        [Parameter(Mandatory=$true, ParameterSetName="endpoint", ValueFromPipeline=$true)]
        $endpoint,

        # The MSPComplete Ticket.
        [Parameter(Mandatory=$false)]
        $ticket = $mspc.Ticket,

        # The environment where the endpoint is stored.
        [Parameter(Mandatory=$false)]
        [ValidateSet("BT", "Beta", "Develop", "Release")]
        [String]$environment = "Beta"
    )

    # Retrieve the endpoint ID from the endpoint
    if ($PSCmdlet.ParameterSetName -eq "endpoint") {
        $endpointID = $endpoint.Id
    }

    # Retrieve the masked endpoint to return later
    else {
        try {
            $endpoint = Get-BT_Endpoint -Ticket $ticket -Id $endpointID -Environment $environment
        }
        catch {
            Write-Error "Error while retrieving masked endpoint with ID '$($endpointID)'. `r`n$($_.Exception.Message)"
            return $null
        }
        if ($null -eq $endpoint) {
            Write-Error "Failed to retrieve masked endpoint with ID '$($endpointID)'."
            return $null
        }
    }

    # Try to retrieve the unmasked endpoint using the endpoint ID
    try {
        # Create hash table to store params
        $getBTEndpointParams = @{
            Ticket                  = $ticket
            Id                      = $endpointID
            ShouldUnmaskProperties  = $true
            Environment             = $environment
        }

        # Get the unmasked endpoint using the endpoint ID
        $unmaskedEndpoint = Get-BT_Endpoint @getBTEndpointParams
    }

    # Error while retrieving unmasked endpoint
    catch {
        Write-Error "Error while retrieving the unmasked Endpoint with ID '$($endpointID)'. `r`n$($_.Exception.Message)"
        return $null
    }

    # Verify endpoint
    if ($null -eq $unmaskedEndpoint) {
        Write-Error "Failed to retrieve the unmasked Endpoint with ID '$($endpointID)'."
        return $null
    }

    # Create the credential object
    # Endpoint contains exchange configuration
    if ($unmaskedEndpoint.Configuration.GetType() -eq [ManagementProxy.ManagementService.ExchangeConfiguration]) {
        $credential = New-Object System.Management.Automation.PSCredential(
            $unmaskedEndpoint.Configuration.AdministrativeUserName,
            ($unmaskedEndpoint.Configuration.AdministrativePassword | ConvertTo-SecureString -AsPlainText -Force)
        )
    }

    # Endpoint contains generic configuration
    elseif ($unmaskedEndpoint.Configuration.GetType() -eq [ManagementProxy.ManagementService.GenericConfiguration]) {
        $credential = New-Object System.Management.Automation.PSCredential(
            $unmaskedEndpoint.Configuration.Username,
            ($unmaskedEndpoint.Configuration.Password | ConvertTo-SecureString -AsPlainText -Force)
        )
    }

    # Currently unsupported configuration type
    else {
        Write-Error "Endpoint '$($unmaskedEndpoint.Name)' has unsupported configuration type '$($endpoint.Configuration.GetType().Name)'."
    }

    # Add credential to masked endpoint
    $endpoint | Add-Member -NotePropertyName "Credential" -NotePropertyValue $credential -Force

    # Return masked endpoint with credential property
    return $endpoint
}