SIS Imports API
API for importing data from Student Information Systems
A SisImportData object looks like:
{
// The type of SIS import
"import_type": "instructure_csv",
// Which files were included in the SIS import
"supplied_batches": ["term", "course", "section", "user", "enrollment"],
// The number of rows processed for each type of import
"counts": null
}A SisImportCounts object looks like:
{
"accounts": 0,
"terms": 3,
"abstract_courses": 0,
"courses": 121,
"sections": 278,
"xlists": 0,
"users": 346,
"enrollments": 1542,
"groups": 0,
"group_memberships": 0,
"grade_publishing_results": 0,
// the number of courses that were removed because they were not included in the
// batch for batch_mode imports. Only included if courses were deleted
"batch_courses_deleted": 11,
// the number of sections that were removed because they were not included in the
// batch for batch_mode imports. Only included if sections were deleted
"batch_sections_deleted": 0,
// the number of enrollments that were removed because they were not included in
// the batch for batch_mode imports. Only included if enrollments were deleted
"batch_enrollments_deleted": 150
}A SisImport object looks like:
{
// The unique identifier for the SIS import.
"id": 1,
// The date the SIS import was created.
"created_at": "2013-12-01T23:59:00-06:00",
// The date the SIS import finished. Returns null if not finished.
"ended_at": "2013-12-02T00:03:21-06:00",
// The date the SIS import was last updated.
"updated_at": "2013-12-02T00:03:21-06:00",
// The current state of the SIS import. - 'created': The SIS import has been
// created.
// - 'importing': The SIS import is currently processing.
// - 'cleanup_batch': The SIS import is currently cleaning up courses, sections,
// and enrollments not included in the batch for batch_mode imports.
// - 'imported': The SIS import has completed successfully.
// - 'imported_with_messages': The SIS import completed with errors or warnings.
// - 'failed_with_messages': The SIS import failed with errors.
// - 'failed': The SIS import failed.
"workflow_state": "imported",
// data
"data": null,
// The progress of the SIS import. The progress will reset when using batch_mode
// and have a different progress for the cleanup stage
"progress": "100",
// Only imports that are complete will get this data. An array of
// CSV_file/warning_message pairs.
"processing_warnings": [["students.csv", "user John Doe has already claimed john_doe's requested login information, skipping"]],
// An array of CSV_file/error_message pairs.
"processing_errors": [["students.csv", "Error while importing CSV. Please contact support."]],
// Whether the import was run in batch mode.
"batch_mode": true,
// The term the batch was limited to.
"batch_mode_term_id": "1234",
// Whether UI changes were overridden.
"override_sis_stickiness": false,
// Whether stickiness was added to the batch changes.
"add_sis_stickiness": false,
// Whether stickiness was cleared.
"clear_sis_stickiness": false,
// The identifier of the data set that this SIS batch diffs against
"diffing_data_set_identifier": "account-5-enrollments",
// The ID of the SIS Import that this import was diffed against
"diffed_against_import_id": 1
}Get SIS import list SisImportsApiController#index
GET /api/v1/accounts/:account_id/sis_imports
Returns the list of SIS imports for an account
Example:
curl 'https://<canvas>/api/v1/accounts/<account_id>/sis_imports' \
-H "Authorization: Bearer <token>"Request Parameters:
| Parameter | Type | Description | |
|---|---|---|---|
| created_since | DateTime |
If set, only shows imports created after the specified date (use ISO8601 format) |
Import SIS data SisImportsApiController#create
POST /api/v1/accounts/:account_id/sis_imports
Import SIS data into Canvas. Must be on a root account with SIS imports enabled.
For more information on the format that's expected here, please see the “SIS CSV” section in the API docs.
Request Parameters:
| Parameter | Type | Description | |
|---|---|---|---|
| import_type | string |
Choose the data format for reading SIS data. With a standard Canvas install, this option can only be 'instructure_csv', and if unprovided, will be assumed to be so. Can be part of the query string. |
|
| attachment | string |
There are two ways to post SIS import data - either via a multipart/form-data form-field-style attachment, or via a non-multipart raw post request. 'attachment' is required for multipart/form-data style posts. Assumed to be SIS data from a file upload form field named 'attachment'. Examples: If you decide to do a raw post, you can skip the 'attachment' argument, but you will then be required to provide a suitable Content-Type header. You are encouraged to also provide the 'extension' argument. Examples: |
|
| extension | string |
Recommended for raw post request style imports. This field will be used to distinguish between zip, xml, csv, and other file format extensions that would usually be provided with the filename in the multipart post request scenario. If not provided, this value will be inferred from the Content-Type, falling back to zip-file format if all else fails. |
|
| batch_mode | boolean |
If set, this SIS import will be run in batch mode, deleting any data previously imported via SIS that is not present in this latest import. See the SIS CSV Format page for details. |
|
| batch_mode_term_id | string |
Limit deletions to only this term. Required if batch mode is enabled. |
|
| override_sis_stickiness | boolean |
Many fields on records in Canvas can be marked “sticky,” which means that when something changes in the UI apart from the SIS, that field gets “stuck.” In this way, by default, SIS imports do not override UI changes. If this field is present, however, it will tell the SIS import to ignore “stickiness” and override all fields. |
|
| add_sis_stickiness | boolean |
This option, if present, will process all changes as if they were UI changes. This means that “stickiness” will be added to changed fields. This option is only processed if 'override_sis_stickiness' is also provided. |
|
| clear_sis_stickiness | boolean |
This option, if present, will clear “stickiness” from all fields touched by this import. Requires that 'override_sis_stickiness' is also provided. If 'add_sis_stickiness' is also provided, 'clear_sis_stickiness' will overrule the behavior of 'add_sis_stickiness' |
|
| diffing_data_set_identifier | string |
If set on a CSV import, Canvas will attempt to optimize the SIS import by comparing this set of CSVs to the previous set that has the same data set identifier, and only appliying the difference between the two. See the SIS CSV Format documentation for more details. |
|
| diffing_remaster_data_set | boolean |
If true, and diffing_data_set_identifier is sent, this SIS import will be part of the data set, but diffing will not be performed. See the SIS CSV Format documentation for details. |
Get SIS import status SisImportsApiController#show
GET /api/v1/accounts/:account_id/sis_imports/:id
Get the status of an already created SIS import.
Examples:
curl 'https://<canvas>/api/v1/accounts/<account_id>/sis_imports/<sis_import_id>' \
-H "Authorization: Bearer <token>"Abort SIS import SisImportsApiController#abort
PUT /api/v1/accounts/:account_id/sis_imports/:id/abort
Abort an already created but not processed or processing SIS import.
Example Request:
curl https://<canvas>/api/v1/accounts/<account_id>/sis_imports/<sis_import_id>/abort \
-H 'Authorization: Bearer <token>'Abort all pending SIS imports SisImportsApiController#abort_all_pending
PUT /api/v1/accounts/:account_id/sis_imports/abort_all_pending
Abort already created but not processed or processing SIS imports.
Example Request:
curl https://<canvas>/api/v1/accounts/<account_id>/sis_imports/abort_all_pending \
-H 'Authorization: Bearer <token>'