iPilot

1.0.1

Public/Remove-iPilotTeamsUserAssignment.ps1

Function Remove-iPilotTeamsUserAssignment {
    <#
        .Synopsis
        Deprovisions a user in iPilot

        .Description
        Deprovisions a user's iPilot telephone number with the provided User Principal Name

        .Parameter UserPrincipalName
        User's User Principal Name.

        .Parameter ApiVersion
        Version of the NuWave iPilot to use. Defaults to v1.

        .Parameter iPilotDomain
        iPilot Domain Name.

        .Example
        # Deprovisions jdoe@contoso.com's iPilot number using API Version v1 in the contoso.com iPilot domain
        Remove-iPilotTeamsUserAssignment -UserPrincipalName jdoe@contoso.com -iPilotDomain contoso.com
    #>
    Param (
        [System.String] [Parameter(Mandatory = $true)] 
            $UserPrincipalName,
        [System.String]
            $ApiUrl = "https://api.nuwave.com", 
        [System.String]
            $ApiVersion = "v1",
        [System.String] 
            $ApiKey,
        [System.String] 
            $iPilotDomain,
        [System.Management.Automation.PSCredential] 
            $Credential
     )

    Begin {
        # Assign variables from dynamic parameters
        If ($UserPrincipalName -and $UserPrincipalName -notlike "*@*.*") {
            throw "Check the formatting of the user's User Principal Name. Format should be jdoe@contoso.com"
        }

        # Set iPilot Domain
        if (!$global:iPilotDomain -and !$iPilotDomain) {
            throw "Run Get-iPilotTeamsDomain or provide domain using -iPilotDomain"
        } elseif (!$iPilotDomain) {
            $iPilotDomain = $global:iPilotDomain
            Write-Verbose "iPilot Domain: $iPilotDomain"
        } # else use passed in iPilotDomain
    }

    Process {
        # Verbose Switch
        if($PSBoundParameters.containskey("Verbose")) {
            $PreviousVerbosePreference = $VerbosePreference
            $VerbosePreference = "continue"
        }

        # Debug Switch
        if($PSBoundParameters.containskey("Debug")) {
            $PreviousDebugPreference = $DebugPreference
            $DebugPreference = "continue"
        }

        # Get/re-use OAuth Token
        Initialize-iPilotSession -ApiUrl $ApiUrl -ApiVersion $ApiVersion -ApiKey $ApiKey -Credential $Credential

        # Get user's iPilot ID
        $User = Get-iPilotTeamsUser -FilterByUserPrincipalName $UserPrincipalName -iPilotDomain $iPilotDomain -Credential $Credential

        # Build iPilot API Request
        $RemoveiPilotUserRequestUri = "$ApiUrl/$ApiVersion/msteams/$iPilotDomain/users/$($User.id)" 

        #region Build Request Body
        Write-Verbose "Request Uri: $RemoveiPilotUserRequestUri"
        Write-Verbose "Request Method: Delete"

        # Splat Invoke-RestMethod Parameters
        $RemoveiPilotUserInvokeParams = @{
            Uri = $RemoveiPilotUserRequestUri
            Method = "Delete"
            ContentType = "application/json"
            Headers = @{
                "X-Access-Token" = $global:iPilotOAuthToken.access_token
                "x-api-key"      = $global:iPilotApiKey
            }
        }

        # Execute the REST API
        Try {
            $RemoveiPilotUserResponse = Invoke-RestMethod @RemoveiPilotUserInvokeParams
            return $RemoveiPilotUserResponse    
        } Catch {
            $InvokeRestMethodError = $_.Exception
            if ($InvokeRestMethodError.Response.StatusCode.value__ -eq 404) {
                Write-Error "iPilot user $($UserPrincipalName) could not be found.`nStatus: $($InvokeRestMethodError.Response.StatusCode.value__)`nURL: $($RemoveiPilotUserRequestUri). Error: $($Error[0])"
            } elseif ($InvokeRestMethodError.Response.StatusCode.value__ -eq 404) {
                Write-Error "iPilot OAuth token invalid. Unauthorized. Please re-authenticate with Get-iPilotOAuthToken.`nStatus: $($InvokeRestMethodError.Response.StatusCode.value__)`nURL: $($RemoveiPilotUserRequestUri). Error: $($Error[0])"
            } elseif ($InvokeRestMethodError.Response.StatusCode.value__ -eq 400) {
                Write-Error "$($InvokeRestMethodError.Response.StatusDescription)`n.`nStatus: $($InvokeRestMethodError.Response.StatusCode.value__)`nURL: $($RemoveiPilotUserRequestUri). Error: $($Error[0])"
            } elseif ($InvokeRestMethodError.Response.StatusCode.value__ -eq 406) {
                Write-Error "$($InvokeRestMethodError.Response.StatusDescription)`n.`nStatus: $($InvokeRestMethodError.Response.StatusCode.value__)`nURL: $($RemoveiPilotUserRequestUri). Error: $($Error[0])"
            } else {
                Write-Error "iPilot user $($UserPrincipalName) could not be deprovisioned.`nStatus: $($InvokeRestMethodError.Response.StatusCode.value__)`nURL: $($RemoveiPilotUserRequestUri). Error: $($Error[0])"
            }            
            break
        }

        # Return Available Numbers
        if ($RemoveiPilotUserResponse.statuscode -eq 200) {
            Write-Output "Successfully triggered deprovisioning of iPilot User.`nUPN: $UserPrincipalName`nTelephoneNumber: $TelephoneNumber)"
        } else {
            Write-Error "Failed to remove iPilot User.`nUPN: $UserPrincipalName`nTelephoneNumber: $TelephoneNumber).`nStatus Code: $RemoveiPilotUserResponse.statuscode"
        }

        # Verbose Switch
        if($PSBoundParameters.containskey("Verbose")) {
            $VerbosePreference = $PreviousVerbosePreference
        }

        # Debug Switch
        if($PSBoundParameters.containskey("Debug")) {
            $DebugPreference = $PreviousDebugPreference
        }
    }
}