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 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, [Switch] $Wait, [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:IP_iPilotDomain -and !$iPilotDomain) { throw "Run Get-iPilotTeamsDomain or provide domain using -iPilotDomain" } elseif (!$iPilotDomain) { $iPilotDomain = $global:IP_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:IP_Instance) { $InitializeiPilotSessionSplat += @{ Instance = $global:IP_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 ($global:IP_Instance) { $RemoveiPilotUserRequestUri += "?instance=$global:IP_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:IP_iPilotOAuthToken.access_token "x-api-key" = $global:IP_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.`n Status: $($InvokeRestMethodError.Response.StatusCode.value__)`n URL: $($RemoveiPilotUserRequestUri)`n Exception: $($Error[0])`n Status:$($RemoveiPilotUserResponse.status)`n Error:$($RemoveiPilotUserResponse.data | Format-Table | Out-String)" } elseif ($InvokeRestMethodError.Response.StatusCode.value__ -eq 404) { Write-Error "iPilot OAuth token invalid. Unauthorized. Please re-authenticate with Get-iPilotOAuthToken.`n Status: $($InvokeRestMethodError.Response.StatusCode.value__)`n URL: $($RemoveiPilotUserRequestUri)`n Exception: $($Error[0])`n Status:$($RemoveiPilotUserResponse.status)`n Error:$($RemoveiPilotUserResponse.data | Format-Table | Out-String)" } elseif ($InvokeRestMethodError.Response.StatusCode.value__ -eq 400) { Write-Error "$($InvokeRestMethodError.Response.StatusDescription)`n Status: $($InvokeRestMethodError.Response.StatusCode.value__)`n URL: $($RemoveiPilotUserRequestUri)`n Exception: $($Error[0])`n Status:$($RemoveiPilotUserResponse.status)`n Error:$($RemoveiPilotUserResponse.data | Format-Table | Out-String)" } elseif ($InvokeRestMethodError.Response.StatusCode.value__ -eq 406) { Write-Error "$($InvokeRestMethodError.Response.StatusDescription)`n Status: $($InvokeRestMethodError.Response.StatusCode.value__)`n URL: $($RemoveiPilotUserRequestUri)`n Exception: $($Error[0])`n Status:$($RemoveiPilotUserResponse.status)`n Error:$($RemoveiPilotUserResponse.data | Format-Table | Out-String)" } else { Write-Error "iPilot user $($UserPrincipalName) could not be deprovisioned.`n Status: $($InvokeRestMethodError.Response.StatusCode.value__)`n URL: $($RemoveiPilotUserRequestUri)`n Exception: $($Error[0])`n Status:$($RemoveiPilotUserResponse.status)`n Error:$($RemoveiPilotUserResponse.data | Format-Table | Out-String)" } break } # Return Available Numbers if ($RemoveiPilotUserResponse.statuscode -eq 200) { Write-Output "Successfully triggered deprovisioning of iPilot User.`nUPN: $UserPrincipalName`nTelephoneNumber: $TelephoneNumber)" # Wait for user to be removed, else exit immediately if ($Wait.IsPresent) { Do { $User = Get-iPilotTeamsUser -FilterByUserPrincipalName $UserPrincipalName if ($User.Status -eq "FAILED_TO_UNASSIGN") { Write-Error "Failed to unassign $UserPrincipalName from $($TelephoneNumber.TelephoneNumber)" exit 1 } if ($User.Status -notlike "No data found*") { Write-Output "$UserPrincipalName status is $($User.Status), waiting 30 seconds to refresh status" Start-Sleep -Seconds 30 } } While ($User.Status -like "No data found*") } } else { Write-Error "Failed to remove iPilot User.`n UPN: $UserPrincipalName`n TelephoneNumber: $TelephoneNumber`n Status:$($RemoveiPilotUserResponse.status)`n Error:$($RemoveiPilotUserResponse.data | Format-Table | Out-String)" } # Verbose Switch if($PSBoundParameters.containskey("Verbose")) { $VerbosePreference = $PreviousVerbosePreference } # Debug Switch if($PSBoundParameters.containskey("Debug")) { $DebugPreference = $PreviousDebugPreference } } } |