iPilot

1.0.4

Public/Set-iPilotDepartmentAssignment.ps1

Function Set-iPilotDepartmentAssignment {
    <#
        .Synopsis
        Assign 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
        # Add jdoe@contoso.com as a member of the Sales department
        Set-iPilotDepartmentAssignment -UserPrincipalName jdoe@contoso.com -DepartmentName "Sales"
    #>
    Param (
        [Parameter(
            Mandatory = $true,
            ValueFromPipeline = $true)] 
        [System.String] $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
        Try {
            New-Object System.Net.Mail.MailAddress($UserPrincipalName) > $null
        }
        Catch {
            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
        $SetPilotDepartmentAssignmentRequestUri = "$ApiUrl/$ApiVersion/msteams/$iPilotDomain/departments" 
        if ($Instance) {
            $SetPilotDepartmentAssignmentRequestUri += "?instance=$Instance"
        }
        Write-Verbose "SetPilotDepartmentAssignmentRequestUri: $SetPilotDepartmentAssignmentRequestUri"

        #Build Request Body
        Write-Verbose "Request Method: Post"

        # Add DepartmentName and UserPrincipalName to Body
        $SetPilotDepartmentAssignmentRequestBody = @{
            departmentName = $DepartmentName
            upn            = $UserPrincipalName
        }

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

        # Execute the REST API
        Try {
            $SetPilotDepartmentAssignmentResponse = Invoke-RestMethod @SetPilotDepartmentAssignmentInvokeParams -ErrorAction Stop
        }
        Catch {
            Write-Error "Failed to assign $UserPrincipalName to $DepartmentName`n`nURL: $($SetPilotDepartmentAssignmentRequestUri)`nBody: $($SetPilotDepartmentAssignmentRequestBody | Format-Table | Out-String)`n Error: $($_.Exception.Message)"
            break
        }

        # Return User object
        if ($SetPilotDepartmentAssignmentResponse.statuscode -eq 200) {
            Write-Output "Successfully unassigned $UserPrincipalName from $DepartmentName"
        }
        else {
            Write-Error "Failed to assign $UserPrincipalName to $DepartmentName`n`nURL: $($SetPilotDepartmentAssignmentRequestUri)`nBody: $($SetPilotDepartmentAssignmentRequestBody | Format-Table | Out-String)`n Error: $($_.Exception.Message)"
        }

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

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