SIS Import Notification Tool

kyle_cole
Instructure
Instructure
‎08-22-2023 12:00 PM
0
1027

IMPORTANT DISCLAIMER: This is a homemade solution and is not Instructure supported. 

 

Encountering SIS Import problems can be frustrating, especially when dealing with failures or accidental deletions of numerous objects. Unfortunately, Canvas lacks built-in mechanisms for notifying about hanging imports, failed imports, or significant changes. To bridge this gap, I took the initiative to utilize Google Apps Script in conjunction with the Canvas API. Through this approach, I've devised a solution to address these concerns effectively.

What does it do?

This will run the SIS Import Data Retrieval and Email Notification function every hour thanks to the trigger that is made when you run “Setup” in the "Canvas 🐼" menu.

  • SIS Import Data Retrieval:
    • The sisImportAPI function fetches data about the three latest SIS imports using the Canvas API.
    • The fetched data is processed and inserted into specific ranges in the active sheet.
  • Email Notifications:
    • The sendEmail function processes rows in the active sheet to determine whether notifications should be sent.
    • Notifications are sent if an import has been running longer than the specified notification time, if its workflow state is certain values, if it has failed, or if it has a high number of state changes.
    • Different email subjects and content are constructed based on the conditions.
  • Import Abortion:
    • The abortImport function allows the user to abort a specific SIS import by providing its ID. It sends a PUT request to the Canvas API to initiate the abortion.
  • Abort All Pending Imports:
    • The abortAllPending function is similar to abortImport, but it sends a PUT request to abort all pending SIS imports.

What you will need:

  • Instructure URL: Your .instructure URL, like canvas.instructure.com, is necessary for API calls. Retrieve it from your admin settings under Canvas Cloud Information. Although vanity URLs are an option, using the Instructure URL is recommended for API consistency.
  • API Token: Generate an API token with appropriate permissions. Admins can create API tokens using this guide: How do I manage API access tokens as an admin? This token allows you to perform actions, such as user merging.
  • Notification Email: Specify the email address where notifications should be sent.
  • Import Duration: Estimate how long SIS imports typically take. Set a notification threshold for import duration. If it's too low, you'll receive frequent notifications for short imports. Utilize the SIS Import API to access import start and end times. Access the import details at https://your-canvas-domain/api/v1/accounts/self/sis_imports/. A JSON formatter browser extension (like JSON Formatter for Chrome) helps make sense of the API response.
  • State Change Threshold: Define the maximum number of state changes that trigger notifications. This number should be less than or equal to the total number of state changes you wish to be notified about.

By setting up these components thoughtfully, you can ensure efficient and relevant SIS import notifications.

Video:

 

Lastly, here is the link to the sheet and the code used to make this happen. If you have any questions or run into any issues, post in the comments below. 



Link to Google Sheet: SIS Import Notification

Links to Apps Script: https://github.com/KyleCole90/Canvas-Scripts/blob/main/Apps%20Scripts/SIS%20Import%20Notifcation.gs