doc/api/sis_csv.md
Instructure Canvas can integrate with an institution's Student Information Services (SIS) in several ways. The simplest way involves providing Canvas with several CSV files describing users, courses, and enrollments. These files can be zipped together and uploaded to the Account admin area.
Standard CSV rules apply:
All text should be UTF-8 encoded.
All timestamps are sent and returned in ISO 8601 format. All timestamps default to UTC time zone unless specified.
YYYY-MM-DDTHH:MM:SSZ
If the option to do a "full batch update" is selected in the UI, then this SIS upload is considered to be the new canonical set of data, and data from previous SIS imports that isn't present in this import will be deleted. This can be useful if the source SIS software doesn't have a way to send delete records as part of the import. This deletion is scoped to a single term, which must be specified when uploading the SIS import. Use this option with caution, as it can delete large data sets without any prompting on the individual records. Currently, this affects courses, sections and enrollments.
This option will only affect data that has been involved in a previous SIS job -- either created by a previous import, or referenced by a SIS job after a SIS ID was manually added. Manually created courses with no SIS ID, for example, won't be deleted even if they don't appear in the new SIS import.
During a term batch mode may be used often and if a partial file is sent, many
objects can become deleted. Using change_threshold=5 will only delete objects
if the number of objects to delete is less than 5% of the objects for the term.
For example: If change_threshold set to 5 and the term has 100 courses, and
batch_mode would delete more than 5 of the courses the batch will abort
before the courses are deleted.
The change_threshold can be set to any integer between 1 and 100.
change_threshold also impacts diffing mode.
Multi term batch mode is just like batch mode except against multiple terms. Multi term batch mode is run against all terms included in the same import for the batch. To use multi term batch mode you must also set a change_threshold. If you intend to remove all items with multi term batch mode, you can set the change_threshold to 100.
If your account has a SIS integration that is sending its entire data set on each import, rather than just sending what has changed, you can speed up the import process by enabling diffing mode. In diffing mode, a preprocessing step in Canvas will compare the current SIS import against the last successful SIS import with the same data set identifier, and only apply the difference between the two imports.
For instance, If user A is created by import 1, and then the name is changed for user A on import 2, Canvas will apply the new information for user A.
If user B is created by import 1, and then user B is omitted from import 2, Canvas will mark the user as deleted.
If user C is created by import 1, and the exact same information is specified for user C in import 2, Canvas will mark that nothing has changed for that CSV row and skip looking up user C entirely. This can greatly speed up SIS imports with thousands of rows that change rarely.
It is important to note that if any SIS data was changed outside of that previous CSV import, the changes will not be noticed by the diffing code. For example:
Diffing mode is enabled by passing the diffing_data_set_identifier
option in the "Import SIS Data" API call. This is a unique, non-changing
string identifier for the series of SIS imports that will be diffed
against one another. The string can contain any valid UTF-8, and be up
to 128 bytes in length. If an account has multiple SIS integrations that
want to take advantage of diffing, each integration can select a unique
data set identifier to avoid interfering with each other.
When choosing a data set identifier, it's important to include any relevant details to differentiate this data set from other import data sets that may come concurrently or later. This might include things such as source system, data type, and term id. Some examples of good identifiers:
Diffing mode by default marks objects as "deleted" when they are not included
for an import, but enrollments can be marked as 'completed' or 'inactive' if the
diffing_drop_status is passed. Likewise users removed between diffed batches
can be marked as 'suspended' if the diffing_user_remove_status is set to
suspended. If you prefer to leave removed objects alone in diffed imports,
pass skip_deletes=true instead of either of these (this will apply to all object
types, not just users and enrollments).
If changes are made to SIS-managed objects outside of the normal import
process, as in the example given above, it may be necessary to process a SIS
import with the same data set identifier, but apply the entire import
rather than applying just the diff. To enable this mode, set the
diffing_remaster_data_set=true option when creating the import, and it
will be applied without diffing. The next import for the same data
set will still diff against that import.
If using automated systems and diffing and there is an issue where the system
sends a partial or an empty file, diffing would see that all users not included
should be removed. Using change_threshold=10 will then not perform diffing if
the files being compared are greater than 10% different. The threshold can be
set to help prevent removing objects unintentionally. When set and the file is
over 10% different, the entire import file will be applied instead of diffing
against a previous batch and this batch will not be used for diffing any future
batches. The change_threshold can be set to any integer between 1 and 100.
If five consecutive SIS batches with the same diffing data set identifier
exceed the change threshold, future imports will fail. You will be required
to perform a remaster using the diffing_remaster_data_set=true option
to resume imports with that data set identifier.
change_threshold also impacts batch mode.
When a user makes a change to imported data in Canvas (e.g., changes a name), this change is "sticky" and is set as the new default. By default, these "sticky" changes are not overwritten on the next SIS import. This can be overridden by selecting the Override UI option, which allows Canvas to overwrite any "sticky" data updated in the Canvas UI. Otherwise, changes from an import with conflicting data would be disregarded and the existing user data would not be changed. See below for an indication of which fields have this "sticky" property
Sample:
<pre>user_id,login_id,authentication_provider_id,password,first_name,last_name,short_name,email,status 01103,bsmith01,,,Bob,Smith,Bobby Smith,[email protected],active 13834,jdoe03,google,,John,Doe,,[email protected],active 13aa3,psue01,7,,Peggy,Sue,,[email protected],active </pre>Any account that will have child accounts must be listed in the csv before any child account references it.
Sample:
<pre>account_id,parent_account_id,name,status A001,,Humanities,active A002,A001,English,active A003,A001,Spanish,active </pre>Sample:
<pre>term_id,name,status,start_date,end_date T001,Winter2011,active,, T002,Spring2011,active,2013-1-03 00:00:00,2013-05-03 00:00:00-06:00 T003,Fall2011,active,, </pre>Sample:
<pre>course_id,short_name,long_name,account_id,term_id,status E411208,ENG115,English 115: Intro to English,A002,,active R001104,BIO300,"Biology 300: Rocking it, Bio Style",A004,Fall2011,active A110035,ART105,"Art 105: ""Art as a Medium""",A001,,active </pre>Sample:
<pre>section_id,course_id,name,status,start_date,end_date S001,E411208,Section 1,active,, S002,E411208,Section 2,active,, S003,R001104,Section 1,active,, </pre>* course_id or section_id is required, role or role_id is required, and user_id or user_integration_id is required.
** deleted_last_completed is not a state, but it combines the deleted and completed states in a function that will delete an enrollment from a course if there are at least one other active enrollment in the course. If it is the last enrollment in the course it will complete it. This may be useful for when a user moves to a different section of a course in which there are section specific assignments. It offloads the logic required to determine if the enrollment is the users last enrollment in the given course or not.
When an enrollment is in a 'completed' state the student is limited to read-only access to the course.
If in an 'inactive' state, the student will be listed in the course roster for teachers, but will not be able to view or participate in the course until the enrollment is activated.
Sample:
<pre>course_id,user_id,role,section_id,status E411208,01103,student,1B,active E411208,13834,student,2A,active E411208,13aa3,teacher,2A,active </pre>Sample:
<pre>group_category_id,account_id,course_id,category_name,status GC08,A001,,First Group Category,active GC07,,,GC7,active GC10,,,GC10,deleted </pre>Sample:
<pre>group_id,account_id,name,status G411208,A001,Group1,available G411208,,Group2,available G411208,,Group3,deleted </pre>Sample:
<pre>group_id,user_id,status G411208,U001,accepted G411208,U002,accepted G411208,U003,deleted </pre>Sample:
<pre>tag_set_id,course_id,set_name,status TS08,C001,First Tag Set,active TS07,C001,TS7,active TS10,C001,TS10,deleted </pre>* tag_set_id or course_id is required for new tags.
Sample:
<pre>tag_id,tag_set_id,course_id,name,status T01,TS08,,Tag1,available T02,,C001,Tag2,available T03,,C001,Tag3,deleted </pre>Sample:
<pre>tag_id,user_id,status T01,U001,accepted T02,U002,accepted T03,U003,deleted </pre>xlists.csv is optional. The goal of xlists.csv is to provide a way to add cross-listing information to an existing course and section hierarchy. Section ids are expected to exist already and already reference other course ids. If a section id is provided in this file, it will be moved from its existing course id to a new course id, such that if that new course is removed or the cross-listing is removed, the section will revert to its previous course id. If xlist_course_id does not reference an existing course, it will be created. If you want to provide more information about the cross-listed course, please do so in courses.csv.
While the xlists.csv does not have any sticky fields, the sections.csv does have course_id as a sticky field. If the section's course_id is "sticky", the import will not cross list the section to another course unless it is run with the Override UI option on the sis import.
Sample:
<pre>xlist_course_id,section_id,status E411208,1B,active E411208,2A,active E411208,2A,active </pre>user_observers.csv is optional. The goal of user_observers.csv is to provide a way to create user_observers. These observers will automatically be enrolled as an observer for each of the students enrollments. When a user_observer is deleted the observer enrollments of the student are also deleted.
Sample:
<pre>observer_id,student_id,status u411208,u411222,active u411208,u411295,active u413405,u411385,deleted </pre>admins.csv is optional. When importing admins that already exist in canvas the admin will become managed by sis. An admin cannot be deleted by running a sis import unless the admin is already managed by sis. Batch mode does not apply to the admins.csv, but diffing mode does apply to the admins.csv. Admins that already exist in the account will receive a notification of the new admin if notification preferences are set to receive this type of notification.
Sample:
<pre>user_id,account_id,role,status E411208,01103,AccountAdmin,active E411208,13834,AccountAdmin,deleted E411208,13aa3,CustomAdmin,active </pre>* role or role_id is required.
* One of existing_user_id or existing_integration_id or existing_canvas_user_id is required.
logins.csv is optional. Logins can only be added to existing users. Logins can be removed using the users.csv.
Sample:
<pre>user_id,login_id,authentication_provider_id,password,existing_canvas_user_id,email 01103,bsmith01,,,Bob,Smith,Bobby Smith,98,[email protected] 13834,jdoe03,google,,John,Doe,,92,[email protected] 13aa3,psue01,7,,Peggy,Sue,,93,[email protected] </pre>* old_id or old_integration_id is required, new_id or new_integration_id is required.
change_sis_id.csv is optional. The goal of change_sis_id.csv is to provide a way to change sis_ids or integration_ids of existing objects. If included in a zip file this file will process first. All other files should include the new ids.
Sample:
<pre>old_id,new_id,old_integration_id,new_integration_id,type u001,u001a,user couse1,old_course1,course term1,fall17,term u001,,,<delete>,user ,,integration01,int01,section </pre>