Automating Canvas LMS Avatar Uploads with PowerShell

James_Wells

Hello Instructure Community,

I was tasked with scripting our Canvas avatar uploads. After a good few weeks of work, I have a solution that I hope will assist others in doing the same.

Here is how it works:

The script queries your Canvas instance for users and looks for a local image file that matches their SIS ID.

• It looks for an image matching the user's primary SIS ID If a match isn't found, it grabs the user's secondary Canvas logins and looks for a match against any alternative SIS IDs attached to their account.
• Once a match is found, the script ensures the required 'Profile Pictures' folder exists in the user's Canvas files. The script will completely clear out any existing files in this folder and lock the user from changing their avatar once it has been set by the script.
• The avatar is then uploaded to that folder and assigns it as the user's active avatar.
• Once completed. the script generates a detailed .csv file in the same folder the script is run from to log information about the upload.

For the script to successfully map an image to a Canvas user, the local image file must be named using the user's SIS ID (i.e. [SIS_ID].[extention]).

The script is configured to look for .jpg files but if your photos are .png files, you will need to change the $SCRIPT:imageFileExtension variable.

Before you run this script, update the configuration variables at the very top of the file to match your environment and ensure your test in your test instance to ensure the script works for your needs.

James_Wells

# --------------------------------------------------------------------

# CONFIGURATION VARIABLES

# --------------------------------------------------------------------

$SCRIPT:canvasApiToken          = "Your API Token" 

$SCRIPT:canvasApiHeader         = @{"Authorization"="Bearer " + $SCRIPT:CanvasApiToken}

$SCRIPT:canvasApiUrl            = 'CanvasURL:443/api/v1'

$SCRIPT:imageFolder             = "Local Path To File"

$SCRIPT:imageFileExtension      = "jpg"

$SCRIPT:imageFileContentType    = 'image/jpg'

$SCRIPT:avatarUrlTemplate       = 'CanvasURL.images/thumbnails/.+/.+'

$SCRIPT:avatarUrlPath           = 'CanvasURL/images/thumbnails/'

$SCRIPT:avatarDefaultUrl        = 'CanvasURL/images/messages/avatar-50.png'

$SCRIPT:validAvatarUrlPattern   = "CanvasURL.images/thumbnails/\d+/{0}$"

$SCRIPT:canvasProfileFolderName = 'profile pictures'

$SCRIPT:canvasProfileFolderParentPath = 'my files'

$SCRIPT:canvasProfileFolderPath = '{0}/{1}' -f $SCRIPT:canvasProfileFolderParentPath, $SCRIPT:canvasProfileFolderName


# --------------------------------------------------------------------

# API FUNCTIONS

# --------------------------------------------------------------------

Function Invoke-CanvasApiRequest (

    $uri,

    $method = 'GET',

    $contentType,

    $inFile,

    $body

) {

    # Ensure URI is properly formatted

    if($uri[0] -NE '/') { $uri = "/{0}" -f $uri}

    $targetUri = "{0}{1}" -f $SCRIPT:canvasApiUrl, $uri


    # Standard parameters for Invoke-WebRequest

    $params = @{

        Method          = $method

        Headers         = $SCRIPT:canvasApiHeader

        UseBasicParsing = $true

    }


    # Conditionally add optional parameters

    if($null -ne $contentType) { $params.ContentType = $contentType}

    if($null -ne $body)        { $params.Body         = $body}

    if($null -ne $inFile)      { $params.InFile       = $inFile}


    do {

        $params.Uri = $targetUri

        Write-Debug ("{0}: {1}" -f $method.toUpper(), $targetUri)


        try {

            $apiResponse = Invoke-WebRequest @params

        } catch [System.Net.WebException] {

            # Extract and throw the actual Canvas error message from the response body

            if ($_.Exception.Response) {

                $stream = $_.Exception.Response.GetResponseStream()

                $reader = New-Object System.IO.StreamReader($stream)

                $errBody = $reader.ReadToEnd()

                Throw "Canvas API Error ($($_.Exception.Response.StatusCode)): $errBody"

            } else {

                Throw $_

            }

        }


        # Convert JSON response to PowerShell objects

        if ($apiResponse.Content) {

            $jsonData = ConvertFrom-Json $apiResponse.Content

            if ($jsonData -is [Array]) {

                $jsonData | Write-Output

            } else {

                Write-Output $jsonData

            }

        }


        # Handle Pagination: Check if a 'next' link exists in the response headers

        $targetUri = $null

        if ($apiResponse.Headers.ContainsKey('Link')) {

            $linkHeader = $apiResponse.Headers['Link']

            if ($linkHeader -match '<([^>]+)>;\s*rel="next"') {

                $targetUri = $Matches[1]

            }

        }


    } while (-not [String]::IsNullOrWhiteSpace($targetUri) -and $method -eq 'GET')

}


Function Get-CanvasUser(

    $canvasId

) {

    <#

    Fetches basic user profile data from Canvas using their Canvas ID.

    #>

    $uri  = "/users/{0}" -f $canvasId

    return Invoke-CanvasApiRequest -Uri $uri

}


Function Get-UserInfo (

    [int] $userCanvasId

) {

    <#

    Gathers detailed user ID information and attempts to map the user 

    to a local image file based on their primary or secondary SIS IDs.

    #>

    $user = Get-CanvasUser -canvasId $userCanvasId


    # Build an array to hold all possible IDs, starting with the primary ones

    $possibleIds = New-Object System.Collections.ArrayList

    if (-not [string]::IsNullOrWhiteSpace($user.sis_user_id)) { [void]$possibleIds.Add($user.sis_user_id) }

    if (-not [string]::IsNullOrWhiteSpace($user.integration_id)) { [void]$possibleIds.Add($user.integration_id) }


    # Fetch the deeper login objects to find hidden secondary SIS IDs

    try {

        $logins = Invoke-CanvasApiRequest -Uri "/users/$($userCanvasId)/logins"

        if ($null -ne $logins) {

            $logins | Where-Object { -not [string]::IsNullOrWhiteSpace($_.sis_user_id) } | ForEach-Object {

                if ($possibleIds -notcontains $_.sis_user_id) { 

                    [void]$possibleIds.Add($_.sis_user_id) 

                }

            }

        }

    } catch {

        Write-Verbose "Could not retrieve secondary logins for user ID: $userCanvasId"

    }


    $foundFileName = $null


    # Iterate through all gathered IDs to see which one has a matching local image file

    foreach ($id in $possibleIds) {

        if ([string]::IsNullOrWhiteSpace($id)) { continue }


        $testFileName = "$id.$($SCRIPT:imageFileExtension)"

        $testFilePath = Join-Path $SCRIPT:imageFolder $testFileName


        if (Test-Path -Path $testFilePath) {

            $foundFileName = $testFileName

            break # Stop as soon as we find a match

        }

    }


    # Fallback if no file matches (prevents script crashes later on)

    if ($null -eq $foundFileName) {

        $foundFileName = "$($user.sis_user_id).$($SCRIPT:imageFileExtension)"

    }


    # Append the found local image details directly to the user object for easier passing

    $user | Add-Member -NotePropertyName ImageFileName -NotePropertyValue $foundFileName -Force

    $user | Add-Member -NotePropertyName ImageFolder -NotePropertyValue $SCRIPT:imageFolder -Force


    return $user

}


Function New-CanvasUserFolder (

    [int]       $userCanvasId,

    [string]    $folderName,

    [string]    $parentFolderPath

) {

    <#

    Creates a new hidden/locked folder in the user's Canvas files.

    This is required because Canvas expects avatars to live in 'profile pictures'.

    #>

    $parentFolderPath = $parentFolderPath.Trim('/')


    $uri = "/users/$userCanvasId/folders?as_user_id=$userCanvasId"


    $body = @{

        name               = $folderName

        parent_folder_path = $parentFolderPath

        hidden             = 'true'

        locked             = 'true'

    }


    Write-Verbose "Creating missing folder '$folderName' for user $userCanvasId..."

    Return Invoke-CanvasApiRequest -method 'POST' -uri $uri -body $body

}


Function Get-CanvasUserFolders (

    [int]       $userCanvasId,

    [string]    $folderName,

    [string]    $parentFolderPath

) {

    <#

    Retrieves a specific folder within a user's Canvas files space.

    #>

    $uri           = "/users/$userCanvasId/folders?as_user_id=$userCanvasId"

    $canvasFolders = Invoke-CanvasApiRequest -uri $uri


    if(-NOT [String]::IsNullOrWhiteSpace($folderName)) {

        if(-NOT [String]::IsNullOrWhiteSpace($parentFolderPath)) {

            $parentFolderPath = $parentFolderPath.TrimEnd('/', '\')

            $folderPath    = "$parentFolderPath/$folderName"

            $canvasFolders = $canvasFolders | Where-Object {$_.Full_Name -EQ $folderPath}

        } else {

            $canvasFolders = $canvasFolders | Where-Object {$_.Name -EQ $folderName}

        }

    }


    Return $canvasFolders

}


Function Send-CanvasFileUpload (

    [int]       $userCanvasId,

    [string]    $inputFileName,

    [string]    $inputFolderPath,

    [int]       $toFolderId,    

    [string]    $contentType,

    [boolean]   $checkQuota = $true

) {

    <#

    Executes the  3-step Canvas file upload protocol.

    Check quota (optional but recommended).

    Tell Canvas a file is coming to get a unique upload URL.

    Post the actual file data to the provided URL.

    #>

    $inputFolderPath = $inputFolderPath.TrimEnd('/', '\')

    $inputFilePath = "$inputFolderPath\$inputFileName"


    if(-not (Test-Path -Path $inputFilePath)) {

        Throw "No file found locally at target path: $inputFilePath"

    }


    $fileSizeBytes = (Get-Item $inputFilePath).Length


    # Check if the user has enough file storage space

    if($checkQuota) {

        $uri = "/users/$userCanvasId/files/quota?as_user_id=$userCanvasId"

        $quotaResponse = Invoke-CanvasApiRequest -uri $uri

        $quotaRemaining = $quotaResponse.quota - $quotaResponse.quota_used


        if ($quotaRemaining -LT $fileSizeBytes) {

            Throw "ERROR: User storage quota exceeded. Upload blocked."

        }

    }


    # Notify Canvas of the upload to get the temporary upload URL

    $notifyBody = @{

        name         = $inputFileName

        size         = $fileSizeBytes 

        content_type = $contentType

        on_duplicate = 'rename'

    }


    $uri            = "/folders/$toFolderId/files?as_user_id=$userCanvasId"

    $notifyResponse = Invoke-CanvasApiRequest -method 'POST' -URI $uri -body $notifyBody


    if ($null -eq $notifyResponse -OR [String]::IsNullOrWhiteSpace($notifyResponse.upload_url)) {

        Throw "ERROR: Canvas refused to provide an upload URL endpoint."

    }


    # Execute the upload using cURL .

    $curlArgs = @(

        '-s', '-X', 'POST',

        $notifyResponse.upload_url,

        '-F', "filename=$inputFileName",

        '-F', "content-type=$contentType",

        '-F', "file=@$inputFilePath"

    )


    Write-Verbose "Triggering cURL media handshake..."

    $curlResponse = & C:\Windows\System32\curl.exe @curlArgs


    if ([string]::IsNullOrWhiteSpace($curlResponse)) {

        Throw "ERROR: cURL returned a completely blank response."

    }


    $uploadResponse = $curlResponse | Convertfrom-Json

    if ($null -eq $uploadResponse) {

        Throw "ERROR: File upload registration payload parsed as null."

    }


    return $uploadResponse

}


Function Set-CanvasUserAvatar(

    [int]       $userCanvasId,

    [string]    $fileUuid

) {

    # Fetch all available avatars for the user to find the token matching our target file

    $uri              = "/users/$userCanvasId/avatars?as_user_id=$userCanvasId"

    $availableAvatars = Invoke-CanvasApiRequest -uri $uri

    $wantAvatar       = $availableAvatars | Where-Object { $null -ne $_.uuid -and $_.uuid -EQ $fileUuid }


    if ($null -eq $wantAvatar) {

        Throw "The requested file UUID ($fileUuid) was not found as an available avatar image for user $userCanvasId."

    } 


    # Assign the avatar using the token Canvas generated for that file

    $uri               = "/users/$($userCanvasId)?user[avatar][token]=$($wantAvatar.token)"

    $setAvatarResponse = Invoke-CanvasApiRequest -method 'PUT' -uri $uri


    # Verify the assignment was successful by checking the new avatar_url pattern

    if ($setAvatarResponse.avatar_url -MATCH ($SCRIPT:validAvatarUrlPattern -f $fileUuid) ) {

        Write-Debug "OK, avatar assigned successfully."

        return $true

    } else {

        Write-Debug "ERROR: There was a problem assigning the avatar for UUID: $fileUuid."

        return $false

    }

}


Function Sync-CanvasAvatar (

    [string]    $userCanvasId

) {

    <#

    Creates required folders, cleans up old avatars, uploads the new image, and sets it.

    #>

    Write-Host  "    > Getting info for Canvas user: $userCanvasId"

    $user       = Get-UserInfo -userCanvasId $userCanvasId

    Write-Host  "    > Current Avatar: $($user.avatar_url)"


    $folderParams = @{

        userCanvasId     = $user.id

        folderName       = $SCRIPT:canvasProfileFolderName

        parentFolderPath = $SCRIPT:canvasProfileFolderParentPath

    }


    # Check if the required "profile pictures" folder exists

    $profilePicturesFolder = Get-CanvasUserFolders @folderParams | Select-Object -First 1


    if ($null -eq $profilePicturesFolder) {

        Write-Host "    > The 'profile pictures' folder doesn't exist yet. Creating it..." -ForegroundColor Cyan

        $profilePicturesFolder = New-CanvasUserFolder -userCanvasId $user.id -folderName $SCRIPT:canvasProfileFolderName -parentFolderPath $SCRIPT:canvasProfileFolderParentPath


        if ($null -eq $profilePicturesFolder -or [string]::IsNullOrWhiteSpace($profilePicturesFolder.id)) {

            Throw "Critical Error: Could not retrieve or create the 'profile pictures' folder."

        }

    }


    # Ensure we have the active folder object, then delete existing files inside it 

    # to prevent storage quota bloat over multiple syncs.

    $profilePicturesFolder = Get-CanvasUserFolders @folderParams | Select-Object -First 1


    if ($null -ne $profilePicturesFolder) {

        $existingFilesUri = "/folders/$($profilePicturesFolder.id)/files?as_user_id=$($user.id)"

        $existingFiles = Invoke-CanvasApiRequest -Uri $existingFilesUri


        if ($null -ne $existingFiles) {

            Write-Host "    > Cleaning up existing files in the profile pictures folder..."

            foreach ($file in $existingFiles) {

                Write-Verbose "    > Deleting old avatar file: $($file.filename)"

                $deleteUri = "/files/$($file.id)?as_user_id=$($user.id)"

                Invoke-CanvasApiRequest -method 'DELETE' -Uri $deleteUri | Out-Null

            }

        }

    }


    # Prepare and trigger the file upload

    $uploadParams = @{

        userCanvasId    = $user.id

        inputFileName   = $user.imageFileName

        inputFolderPath = $user.imageFolder

        toFolderId      = $profilePicturesFolder.id

        contentType     = $SCRIPT:imageFileContentType

    }


    Write-Host "    > Uploading profile image file..."

    $uploadResponse = Send-CanvasFileUpload @uploadParams


    if($null -eq $uploadResponse -OR $uploadResponse.upload_status -NE 'success') {

        Throw "Unable to upload file for user."

    }


    # Fetch the newly uploaded file's metadata from Canvas to get its UUID

    $uri = "/folders/$($profilePicturesFolder.id)/files?search_term=$($user.imageFileName)&as_user_id=$($user.id)"

    $avatarImage = Invoke-CanvasApiRequest -Uri $uri | 

                   Where-Object { $_.filename -eq $user.imageFileName } | 

                   Sort-Object created_at -Descending | 

                   Select-Object -First 1


    if($null -eq $avatarImage) {

        Throw "Could not find valid avatar image for user $($user.name) [$($user.sis_user_id)]."

    }


    # Finally, assign the newly uploaded file as the active avatar

    Write-Host "    > Assigning user's avatar..."

    $assignmentResult = Set-CanvasUserAvatar -userCanvasId $user.id -fileUuid $avatarImage.uuid

    if(-not $assignmentResult) {

        Throw "Avatar image assignment failed."

    }

}



# ====================================================================

# EXECUTION LOOP

# ====================================================================


Write-Host "Starting API synchronization cycle..." -ForegroundColor Cyan

Write-Host "Fetching accounts across instance root hierarchy tree..." -ForegroundColor Cyan


# Define where the final CSV report will be saved (same directory as script)

$csvExportPath = Join-Path $PSScriptRoot "CanvasAvatarSyncReport.csv"


# Fetch users from the root account 

$reportData = Invoke-CanvasApiRequest -Uri '/accounts/1/users?per_page=100' | 

    Where-Object { $null -ne $_.login_id -and $_.login_id -ne '' } | 

    ForEach-Object {

        $user = $_


        Write-Host "`n--------------------------------------------------" -ForegroundColor DarkCyan

        Write-Host "Processing User: $($user.name) | Canvas ID: $($user.id) | Login: $($user.login_id)" -ForegroundColor Cyan


        # Initialize tracking variables for the current user

        $matchedSisId = $null

        $expectedPhotoName = $null

        $expectedLocalPath = $null

        $allFoundSisIds = New-Object System.Collections.ArrayList


        # Check the primary SIS ID 

        $primarySis = $user.sis_user_id

        if (-not [string]::IsNullOrWhiteSpace($primarySis)) {

            [void]$allFoundSisIds.Add($primarySis)

            Write-Host " -> Primary SIS ID: $primarySis"


            $testPath = Join-Path $SCRIPT:imageFolder "$primarySis.$($SCRIPT:imageFileExtension)"

            if (Test-Path -Path $testPath) {

                $matchedSisId = $primarySis

                $expectedPhotoName = "$matchedSisId.$($SCRIPT:imageFileExtension)"

                $expectedLocalPath = $testPath

                Write-Host " -> [MATCH] Image found for Primary SIS ID: $expectedPhotoName" -ForegroundColor Green

            }

        } else {

            Write-Host " -> Primary SIS ID: [None/Empty]"

        }


        # If the primary ID didn't have a matching file (or was empty), query the logins.

        if ($null -eq $expectedLocalPath) {

            Write-Host " -> Image not found for Primary SIS ID. Checking secondary logins..." -ForegroundColor DarkGray

            try {

                $logins = Invoke-CanvasApiRequest -Uri "/users/$($user.id)/logins"

                if ($null -ne $logins) {

                    # Extract unique SIS IDs that differ from the primary one

                    $altSisIds = $logins | Where-Object { -not [string]::IsNullOrWhiteSpace($_.sis_user_id) -and $_.sis_user_id -ne $primarySis } | Select-Object -ExpandProperty sis_user_id -Unique


                    if ($altSisIds.Count -gt 0) {

                        $altSisIdsJoined = $altSisIds -join ", "

                        Write-Host " -> Secondary SIS ID(s) found: $altSisIdsJoined" -ForegroundColor Magenta


                        foreach ($altId in $altSisIds) {

                            [void]$allFoundSisIds.Add($altId)

                            $testPath = Join-Path $SCRIPT:imageFolder "$altId.$($SCRIPT:imageFileExtension)"


                            # Check if local file exists for this secondary ID

                            if (Test-Path -Path $testPath) {

                                $matchedSisId = $altId

                                $expectedPhotoName = "$matchedSisId.$($SCRIPT:imageFileExtension)"

                                $expectedLocalPath = $testPath

                                Write-Host " -> [MATCH] Image found for Secondary SIS ID: $expectedPhotoName" -ForegroundColor Green

                                break # Stop searching once we find a match

                            }

                        }

                    } else {

                        Write-Host " -> No secondary SIS IDs found for this user." -ForegroundColor DarkGray

                    }

                }

            } catch {

                Write-Host " -> [ERROR] Could not fetch secondary logins for user $($user.id)." -ForegroundColor Red

            }

        }


        # Track default parameters for the final report

        $statusMessage = "No matching local file found for any attached SIS IDs."

        $executionOutcome = "Skipped"


        #

        # If we found a local file path during either pass, trigger the sync process

        if ($null -ne $expectedLocalPath) {

            try {

                Write-Host " -> Synchronizing photo asset to Canvas..." -ForegroundColor Yellow

                Sync-CanvasAvatar -userCanvasId $user.id 

                Write-Host " -> [SUCCESS] Avatar changed successfully." -ForegroundColor Green


                $executionOutcome = "Success"

                $statusMessage = "Avatar changed successfully using ID: $matchedSisId."

            } catch {

                # Catch any errors 

                $errorMessage = $_.Exception.Message

                Write-Host " -> [FAILED] Sync failed: $errorMessage" -ForegroundColor Red


                $executionOutcome = "Failed"

                $statusMessage = $errorMessage

            }

        } else {

            # Display all IDs checked if the sync was skipped

            $allChecked = if ($allFoundSisIds.Count -gt 0) { $allFoundSisIds -join ", " } else { "None" }

            Write-Host " -> [SKIPPED] No image file matched any of the user's known SIS IDs ($allChecked)." -ForegroundColor Yellow

        }



        # Build an object for the current user and emit it to $reportData

        [PSCustomObject]@{

            CanvasUserID  = $user.id

            Name          = $user.name

            LoginID       = $user.login_id

            PrimarySisID  = $primarySis

            MatchedSisID  = if ($null -ne $matchedSisId) { $matchedSisId } else { "None" }

            AllKnownSisIDs= $allFoundSisIds -join ", "

            TargetFile    = if ($null -ne $expectedPhotoName) { $expectedPhotoName } else { "N/A" }

            Outcome       = $executionOutcome

            Details       = $statusMessage

        }

    }


Write-Host "`n==================================================" -ForegroundColor DarkCyan


# Export the collected custom objects ($reportData) directly to a CSV file.

if ($null -ne $reportData) {

    $reportData | Export-Csv -Path $csvExportPath -NoTypeInformation -Encoding UTF8

    Write-Host "Canvas Enterprise Global Avatar Sync Process Complete!" -ForegroundColor Green

    Write-Host "Report exported to: $csvExportPath" -ForegroundColor Green

} else {

    Write-Host "Process ended. No accounts were processed by the sync filter loop." -ForegroundColor Yellow

}