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,
"error_count": 0,
"warning_count": 0
}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.
// - 'aborted': The SIS import was aborted.
// - '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",
// The errors_attachment api object of the SIS import. Only available if there are
// errors or warning and import has completed.
"errors_attachment": null,
// The user that initiated the sis_batch. See the Users API for details.
"user": null,
// 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",
// Enables batch mode against all terms in term file. Requires change_threshold to
// be set.
"multi_term_batch_mode": false,
// When set the import will skip any deletes.
"skip_deletes": false,
// 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
url: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
url: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 cannot be used with diffing. |
|
| batch_mode_term_id | string |
Limit deletions to only this term. Required if batch mode is enabled. |
|
| multi_term_batch_mode | boolean |
Runs batch mode against all terms in terms file. Requires change_threshold. |
|
| skip_deletes | boolean |
When set the import will skip any deletes. This does not account for objects that are deleted during the batch mode cleanup process. |
|
| 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 applying the difference between the two. See the SIS CSV Format documentation for more details. Diffing cannot be used with batch_mode |
|
| 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. |
|
| diffing_drop_status | string |
If diffing_drop_status is passed, this SIS import will use this status for enrollments that are not included in the sis_batch. Defaults to 'deleted'
Allowed values: |
|
| change_threshold | integer |
If set with batch_mode, the batch cleanup process will not run if the number of items deleted is higher than the percentage set. If set to 10 and a term has 200 enrollments, and batch would delete more than 20 of the enrollments the batch will abort before the enrollments are deleted. The change_threshold will be evaluated for course, sections, and enrollments independently. If set with diffing, diffing will not be performed if the files are greater than the threshold as a percent. If set to 5 and the file is more than 5% smaller or more than 5% larger than the file that is being compared to, diffing will not be performed. If the files are less than 5%, diffing will be performed. See the SIS CSV Format documentation for more details. Required for multi_term_batch_mode. |
Get SIS import status SisImportsApiController#show
GET /api/v1/accounts/:account_id/sis_imports/:id
url: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>'Restore workflow_states of SIS imported items SisImportsApiController#restore_states
PUT /api/v1/accounts/:account_id/sis_imports/:id/restore_states
url:PUT|/api/v1/accounts/:account_id/sis_imports/:id/restore_states
This will restore the the workflow_state for all the items that changed their workflow_state during the import being restored. This will restore states for items imported with the following importers: accounts.csv terms.csv courses.csv sections.csv group_categories.csv groups.csv users.csv admins.csv This also restores states for other items that changed during the import. An example would be if an enrollment was deleted from a sis import and the group_membership was also deleted as a result of the enrollment deletion, both items would be restored when the sis batch is restored.
Request Parameters:
| Parameter | Type | Description | |
|---|---|---|---|
| batch_mode | boolean |
If set, will only restore items that were deleted from batch_mode. |
|
| undelete_only | boolean |
If set, will only restore items that were deleted. This will ignore any items that were created or modified. |
Example Request:
curl https://<canvas>/api/v1/accounts/<account_id>/sis_imports/<sis_import_id>/restore_states \
-H 'Authorization: Bearer <token>'Abort SIS import SisImportsApiController#abort
PUT /api/v1/accounts/:account_id/sis_imports/:id/abort
url:PUT|/api/v1/accounts/:account_id/sis_imports/:id/abort
Abort a SIS import that has not completed.
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
url: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>'