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 $InitializeiPilotSessionSplat = @{ ApiUrl = $ApiUrl ApiVersion = $ApiVersion ApiKey = $ApiKey Credential = $Credential } if ($global:Instance) { $InitializeiPilotSessionSplat += @{ Instance = $global:Instance } } if ($VerbosePreference -eq "Continue") { $InitializeiPilotSessionSplat += @{ Verbose = $true } } if ($DebugPreference -eq "Continue") { $InitializeiPilotSessionSplat += @{ Debug = $true } } Initialize-iPilotSession @InitializeiPilotSessionSplat # 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)" if ($Instance) { $RemoveiPilotUserRequestUri += "?instance=$Instance" } Write-Verbose "RemoveiPilotUserRequestUri: $RemoveiPilotUserRequestUri" #region Build Request Body 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 } } } |