Users.psm1

<#
.SYNOPSIS
    This function waits for a user to become available on MS Online.
.DESCRIPTION
    This function waits for a user to become available on MS Online.
    This function assumes that the connection to MS Online has already been
    previously established before this function was called.
    Returns the retrieved user object.
.PARAMETER userPrincipalName
    The user to wait for
.PARAMETER waitLimit
    The maximum amount of time to wait (in seconds)
    Defaults to 1 minute (60 seconds)
#>

function Block-UntilMSOnlineUserAvailable {
    param (
        # The user to wait for
        [Parameter(Mandatory=$true)]
        [String]$userPrincipalName,

        # The maximum amount of time to wait (in seconds)
        # Defaults to 1 minute (60 seconds)
        [Parameter(Mandatory=$false)]
        $waitLimit = 60
    )

    # Keep trying to retrieve the user
    $user = $null
    for ($waitCount = 0; ; $waitCount += 1) {
        # Waited too long for user
        if ($waitCount -eq $waitLimit) {
            Write-Error "Waited the maximum amount of time for '$($userPrincipalName)' to become available."
            return $null
        }

        # Try to retrieve the user
        $user = Get-MsolUser -SearchString $userPrincipalName -ErrorAction SilentlyContinue

        # Check if retrieved user is valid
        if ($null -ne $user -and $user.UserPrincipalName -eq $userPrincipalName) {
            return $user
        }

        # Wait for 1 second then try again
        Start-Sleep -Seconds 1
    }

    # Didn't manage to retrieve the user
    return $null
}