iPilot

1.0.4

Public/Get-iPilotTeamsUser.ps1

Function Get-iPilotTeamsUser {
    <#
        .Synopsis
        Displays iPilot user(s)

        .Description
        Returns iPilot users in iPilot domain with optional filters.

        .Parameter FilterByFirstName
        Filter results by user's First Name.

        .Parameter FilterByLastName
        Filter results by user's Last Name.

        .Parameter FilterByTelephoneNumber
        Filter results by TelephoneNumber (10-digits or less for a partial match).

        .Parameter FilterByUserPrincipalName
        Filter results by user's User Principal Name.

        .Parameter FilterByNote
        Filter results by user's iPilot Note field value.

        .Parameter FilterByStatus
        Filter results by iPilot status.

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

        .Parameter iPilotDomain
        iPilot Domain Name.

        .Parameter NumberOfRecords
        Number of records returned by API (limit 100)

        .Example
        # Get avilable numbers with the status set to Configured using API Version v1 in the contoso.com iPilot domain
        Get-iPilotTeamsUser -FilterByStatus Configured -iPilotDomain contoso.com

        .Example
        # Get avilable numbers with the Sales Note in the contoso.com iPilot domain with Verbose output
        Get-iPilotTeamsUser -FilterByNote -Note "Sales" -iPilotDomain contoso.com -Verbose
    #>
    Param (
        [System.String]
            $FilterByUserPrincipalName,
        [ValidateSet("All","Assigned","Configured","Configured-AA","FailedToAssign","FailedToGrantPolicy","FailedToUnassign","InvalidUPN","NotConfigured","PendingAssign","PendingStopped","PendingStopped-AA","PendingUnassign","Queued","Queued-AA","Stopped","Stopped-AA","Unassigned","Unassigned-AA")]
        [System.String]
            $FilterByStatus = "All",
        [System.String]
            $FilterByFirstName,
        [System.String]
            $FilterByLastName,
        [ValidateRange(1,9999999999)]
        [System.Int64]
            $FilterByTelephoneNumber,
        [System.String]
            $ApiUrl = "https://api.nuwave.com", 
        [System.String]
            $ApiKey, 
        [System.String]
            $ApiVersion = "v1",
        [System.String]
            $iPilotDomain,
        [System.Int16]
            $NumberOfRecords = [System.Int16]::MaxValue,
        [System.Management.Automation.PSCredential]
            $Credential,
        [Switch]
            $Verbose,
        [Switch]
            $Debug
     )

    Begin {

        # UserPrincipalName validation
        if ($FilterByUserPrincipalName -and $FilterByUserPrincipalName -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
        $GetiPilotUsersRequestUri = "$ApiUrl/$ApiVersion/msteams/$iPilotDomain/users?limit=$NumberOfRecords&page=1"
        if ($Instance) {
            $GetiPilotUsersRequestUri += "&instance=$Instance"
        }
        Write-Verbose "GetiPilotUsersRequestUri: $GetiPilotUsersRequestUri"

        #region Add each filter to the Uri
            $Filter = $NULL
            Add-Type -AssemblyName System.Web

            # First Name
            if ($FilterByFirstName) {
                $FilterByFirstName = [System.Web.HttpUtility]::UrlPathEncode($FilterByFirstName) 
                Write-Verbose "Filtering by Status set to $FilterByFirstName"
                $Filter += "&firstname=$FilterByFirstName"
            }

            # Last Name
            if ($FilterByLastName) {
                $FilterByLastName = [System.Web.HttpUtility]::UrlPathEncode($FilterByLastName) 
                Write-Verbose "Filtering by Last Name set to $FilterByLastName"
                $Filter += "&lastname=$FilterByLastName"
            }

            # TelephoneNumber
            if ($FilterByTelephoneNumber) {
                Write-Verbose "Filtering by telephone number containing: $FilterByTelephoneNumber"
                $Filter += "&telephoneNumber=$FilterByTelephoneNumber"
            }

            # UserPrincipalName
            if ($FilterByUserPrincipalName) {
                $FilterByUserPrincipalNameEndcoded = [System.Web.HttpUtility]::UrlPathEncode($FilterByUserPrincipalName) 
                Write-Verbose "Filtering by UserPrincipalName: $FilterByUserPrincipalNameEndcoded (Unencoded: $FilterByUserPrincipalName)"
                $Filter += "&upn=$FilterByUserPrincipalNameEndcoded"
            }

            # Note
            if ($FilterByNote) {
                $FilterByNote = [System.Web.HttpUtility]::UrlPathEncode($FilterByNote) 
                Write-Verbose "Filtering by Note set to $FilterByNote"
                $Filter += "&note=$FilterByNote"
            }

            # Status
            if ($FilterByStatus) {

                # Convert status to API value
                $FilterByStatusEncoded = switch ($FilterByStatus) {
                    All {"ALL"}
                    Assigned {"ASSIGNED"}
                    Configured {"CONFIGURED"}
                    Configured-AA {"CONFIGURED TO AA & CQ"}
                    FailedToAssign {"FAILED_TO_ASSIGN"}
                    FailedToGrantPolicy {"FAILED_TO_GRANT_POLICY"}
                    FailedToUnassign {"FAILED_TO_UNASSIGN"}
                    InvalidUPN {"INVALID_UPN"}
                    NotConfigured {"NOT_CONFIGURED"}
                    #Pending {"PENDING"}
                    PendingAssign {"PENDING_ASSIGN"}
                    PendingStopped {"PENDING_STOPPED"}
                    PendingStopped-AA {"PENDING_STOPPED-AA"}
                    PendingUnassign {"PENDING_UNASSIGN"}
                    Queued {"QUEUED"}
                    Queued-AA {"QUEUED-AA"}
                    Stopped {"STOPPED"}
                    Stopped-AA {"STOPPED-AA"}
                    Unassigned {"UNASSIGNED"}
                    Unassigned-AA {"UNASSIGNED-AA"}
                }

                # All status filter
                if ($FilterByStatusEncoded -eq "ALL") {
                    Write-Verbose "All status filter specified, using no status filter"
                } else {
                    Write-Verbose "Filtering by Status set to $FilterByStatusEncoded (Unencoded: $FilterByStatus)"
                    $Filter += "&status=$FilterByStatusEncoded"    
                }
            }     
            
        #endregion Add each filter to the Uri

        # Splat Invoke-RestMethod parameters
        $RequestURI = $GetiPilotUsersRequestUri + $Filter
        Write-Verbose "Request Uri: $RequestURI"
        Write-Verbose "Request Method: Get"
        $GetiPilotUsersInvokeParams = @{
            Uri = $RequestURI
            Method = "Get"
            ContentType = "application/json"
            Headers = @{
                "X-Access-Token" = $global:IP_iPilotOAuthToken.access_token
                "x-api-key"      = $global:IP_iPilotApiKey
            }
        } 

        # Execute the REST API
        Try {
            $GetiPilotUsersResponse = Invoke-RestMethod @GetiPilotUsersInvokeParams -ErrorAction Stop
        } Catch {
            Write-Error "Failed to retreive iPilot User(s)`nStatus: $($GetiPilotUsersResponse.status)`nURL: $($GetiPilotUsersRequestUri). Error: $($_)"
            break
        }

        # Return Available Numbers
        if ($GetiPilotUsersResponse.Count -ge 1) {

            Write-Debug "GetiPilotUsersResponse:`n$($GetiPilotUsersResponse | Out-String)"

            # Change output to PascalCase
            $Users = $GetiPilotUsersResponse | 
                Select-Object @{Name = 'Id' ; Expression = {$_.id}},
                @{Name = 'UserPrincipalName' ; Expression = {$_.upn}},
                @{Name = 'FirstName' ; Expression = {$_.firstName}},
                @{Name = 'LastName' ; Expression = {$_.lastName}},
                @{Name = 'Note' ; Expression = {$_.note}},
                @{Name = 'Status' ; Expression = {$_.status}},
                @{Name = 'TelephoneNumber' ; Expression = {$_.telephoneNumber}}
            return $Users
        } else {
            Write-Error "No users found using the specified filters."
        }

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

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