iPilot

1.0.4

Public/Remove-iPilotDepartmentAssignment.ps1

Function Remove-iPilotDepartmentAssignment {
    <#
        .Synopsis
        Unassign user from an iPilot department

        .Parameter DepartmentName
        Department's Name.

        .Parameter UserPrincipalName
        User Principal Name

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

        .Parameter ApiKey
        iPilot API Key supplied by NuWave.

        .Parameter iPilotDomain
        iPilot Domain Name.

        .Parameter Credential
        Credentials for iPilot API

        .Example
        # Remove jdoe@contoso.com's membership from the Sales department
        Remove-iPilotDepartmentAssignment -UserPrincipalName jdoe@contoso.com -DepartmentName "Sales"
    #>
    Param (
        [System.String] 
        [Parameter(Mandatory = $true,
                   ValueFromPipeline=$true)] 
            $UserPrincipalName,
        [Parameter(
            Mandatory = $true,
            HelpMessage = 'Allowed characters: Alphanumeric, spaces, and hyphens')]
            [ValidatePattern('^[a-zA-Z0-9 ]+$')]
            [System.String] $DepartmentName,
        [System.String]
            $ApiUrl = $global:IP_ApiUrl, 
        [System.String]
            $ApiVersion = "v1",
        [System.String]
            $ApiKey = $global:IP_ApiKey,
        [System.String] 
            $iPilotDomain,
        [System.Management.Automation.PSCredential] 
            $Credential
     )

    Begin {
        # DepartmentName validation
        If ($DepartmentName | Select-String '^[a-zA-Z0-9 ]+$') {
            throw "Check the DepartmentName. Only alphanumeric, spaces and dashes allowed"
        }
        
        # UserPrincipalName validation
        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

        # Build iPilot API Request
        $RemoveiPilotDepartmentAssignmentRequestUri = "$ApiUrl/$ApiVersion/msteams/$iPilotDomain/departments" 

        #region Build Request Body

            Write-Verbose "Request Uri: $RemoveiPilotDepartmentAssignmentRequestUri"
            Write-Verbose "Request Method: Post"

            # Add UPN and TelephoneNumber to Body
            $RemoveiPilotDepartmentAssignmentRequestBody = @{
                departmentName = $DepartmentName
                upn = $UserPrincipalName
            }

            # Specify Instance
            if ($global:IP_Instance) {
                $RemoveiPilotDepartmentAssignmentRequestBody += @{
                    "instance"= $global:IP_instance
                }
            }
                    
        #endregion Build Request Body

        # Splat Invoke-RestMethod Parameters
        $RemoveiPilotDepartmentAssignmentInvokeParams = @{
            Uri = $RemoveiPilotDepartmentAssignmentRequestUri
            Method = "Post"
            ContentType = "application/json"
            Headers = @{
                "X-Access-Token" = $global:IP_iPilotOAuthToken.access_token
                "x-api-key"      = $global:IP_iPilotApiKey
            }
            Body = $RemoveiPilotDepartmentAssignmentRequestUserBody | ConvertTo-Json
        }

        # Execute the REST API
        Try {
            $RemoveiPilotDepartmentAssignmentResponse = Invoke-RestMethod @RemoveiPilotDepartmentAssignmentInvokeParams -ErrorAction Stop
        } Catch {
            Write-Error "Failed to remove department assignment for $UserPrincipalName from $DepartmentName`n`nURL: $($RemoveiPilotDepartmentAssignmentRequestUri)`nBody: $($RemoveiPilotDepartmentAssignmentRequestBody | Format-Table | Out-String)`n Error: $($_.Exception.Message)"
            break
        }

        # Return User object
        if ($RemoveiPilotDepartmentAssignmentResponse.statuscode -eq 200) {
            Write-Output "Successfully unassigned $UserPrincipalName from $DepartmentName"
        } else {
            Write-Error "Failed to remove department assignment for $UserPrincipalName from $DepartmentName.`n`nURL: $($RemoveiPilotDepartmentAssignmentRequestUri)`nBody: $($RemoveiPilotDepartmentAssignmentRequestBody | Format-Table | Out-String)"
        }

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

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