13 KiB
SIS Import Format Documentation
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:
- The first row will be interpreted as a header defining the ordering of your columns. This header row is mandatory.
- Fields that contain a comma must be surrounded by double-quotes.
- Fields that contain double-quotes must also be surrounded by double-quotes, with the internal double-quotes doubled. Example: Chevy "The Man" Chase would be included in the CSV as "Chevy ""The Man"" Chase".
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
Batch Mode
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 created via previous SIS imports. Manually created courses, for example, won't be deleted even if they don't appear in the new SIS import.
users.csv
| Field Name | Data Type | Default | Description |
|---|---|---|---|
| user_id | text | required | A unique identifier used to reference users in the enrollments table. This identifier must not change for the user, and must be globally unique. In the user interface, this is called the SIS ID. |
| login_id | text | required | The name that a user will use to login to Instructure. If you have an authentication service configured (like LDAP), this will be their username from the remote system. |
| password | text | If the account is configured to use LDAP or an SSO protocol then this isn't needed. Otherwise this is the password that will be used to login to Canvas along with the 'login_id' above. If the user already has a password (from previous SIS import or otherwise) it will not be overwritten |
|
| first_name | text | Given name of the user. | |
| last_name | text | Last name of the user. | |
| text | The email address of the user. This might be the same as login_id, but should still be provided. | ||
| status | enum | active | active, deleted |
When a student is 'deleted' all of its enrollments will also be deleted and they won't be able to log in to the school's account. If you still want the student to be able to log in but just not participate, leave the student 'active' but set the enrollments to 'completed'.
Sample:
user_id,login_id,password,first_name,last_name,email,status 01103,bsmith01,,Bob,Smith,bob.smith@myschool.edu,active 13834,jdoe03,,John,Doe,john.doe@myschool.edu,active 13aa3,psue01,,Peggy,Sue,peggy.sue@myschool.edu,active
A column to be added in the future:
| Field Name | Data Type | Default | Description |
|---|---|---|---|
| local_account | boolean | false | If true, and if the account (as found by the login_id) is not found, this user will be sent an invitation via their email address. They will choose their password when the click the invitation link. |
accounts.csv
| Field Name | Data Type | Default | Description |
|---|---|---|---|
| account_id | text | required | A unique identifier used to reference accounts in the enrollments data. This identifier must not change for the account, and must be globally unique. In the user interface, this is called the SIS ID. |
| parent_account_id | text | The account identifier of the parent account. If this is blank the parent account will be the root account. | |
| name | text | required | The name of the account |
| status | enum | active | active, deleted |
Any account that will have child accounts must be listed in the csv before any child account references it.
Sample:
account_id,parent_account_id,name,status A001,,Humanities,active A002,A001,English,active A003,A001,Spanish,active
terms.csv
| Field Name | Data Type | Default | Description |
|---|---|---|---|
| term_id | text | required | A unique identifier used to reference terms in the enrollments data. This identifier must not change for the account, and must be globally unique. In the user interface, this is called the SIS ID. |
| name | text | required | The name of the term |
| status | enum | active | active, deleted |
| start_date | date | The date the term starts. The format should be: YYYY-mm-DD HH:MM:SS | |
| end_date | date | The date the term ends. The format should be: YYYY-mm-DD HH:MM:SS |
Any account that will have child accounts must be listed in the csv before any child account references it.
Sample:
term_id,name,status,start_date,end_date T001,Winter2011,active,, T002,Spring2011,active,2010-9-03 00:00:00,2010-12-14 00:00:00-06:00 T003,Fall2011,active,,
courses.csv
| Field Name | Data Type | Default | Description |
|---|---|---|---|
| course_id | text | required | A unique identifier used to reference courses in the enrollments data. This identifier must not change for the account, and must be globally unique. In the user interface, this is called the SIS ID. |
| short_name | text | required | A short name for the course |
| long_name | text | required | A long name for the course. (This can be the same as the short name, but if both are available, it will provide a better user experience to provide both.) |
| account_id | text | The account identifier from accounts.csv, if none is specified the course will be attached to the root account | |
| term_id | text | The term identifier from terms.csv, if no term_id is specified the default term for the account will be used | |
| status | enum | active | active, deleted, completed |
| start_date | date | The date the term starts. The format should be: YYYY-mm-DD HH:MM:SS | |
| end_date | date | The date the term ends. The format should be: YYYY-mm-DD HH:MM:SS |
Sample:
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
sections.csv
| Field Name | Data Type | Default | Description |
|---|---|---|---|
| section_id | text | required | A unique identifier used to reference sections in the enrollments data. This identifier must not change for the account, and must be globally unique. In the user interface, this is called the SIS ID. |
| course_id | text | required | The course identifier from courses.csv |
| name | text | required | The name of the section |
| status | enum | active | active, deleted |
| start_date | date | The date the term starts. The format should be: YYYY-mm-DD HH:MM:SS | |
| end_date | date | The date the term ends. The format should be: YYYY-mm-DD HH:MM:SS | |
| account_id | text | The account identifier from accounts.csv, if none is specified the course will be attached to the root account |
Sample:
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,,
enrollments.csv
| Field Name | Data Type | Default | Description |
|---|---|---|---|
| course_id | text | required if section_id missing | The course identifier from courses.csv |
| user_id | text | required | The User identifier from users.csv |
| role | text | required | student, teacher, ta, observer, designer |
| section_id | text | required if course_id missing | The section identifier from sections.csv, if none is specified the default section for the course will be used |
| status | enum | active | active, deleted, completed |
| associated_user_id | text | For observers, the user identifier from users.csv of a student in the same course that this observer should be able to see grades for. Ignored for any role other than observer |
When an enrollment is in a 'completed' state the student is limited to read-only access to the course.
Sample:
course_id,user_id,role,section_id,status E411208,01103,student,1B,active E411208,13834,student,2A,active E411208,13aa3,teacher,2A,active
This new column will be implemented some time in the future:
| Field Name | Data Type | Default | Description |
|---|---|---|---|
| exclusive_section | boolean | false | If true, then any enrollments for this user in this course NOT in the section specified in section_name will be deleted. |
groups.csv
| Field Name | Data Type | Default | Description |
|---|---|---|---|
| group_id | text | required | A unique identifier used to reference groups in the group_users data. This identifier must not change for the group, and must be globally unique. |
| account_id | text | The account identifier from accounts.csv, if none is specified the group will be attached to the root account. | |
| name | text | required | The name of the group. |
| status | enum | available | available, closed, completed, deleted |
Sample:
group_id,account_id,name,status G411208,A001,Group1,available G411208,,Group2,available G411208,,Group3,deleted
groups_membership.csv
| Field Name | Data Type | Default | Description |
|---|---|---|---|
| group_id | text | required | The group identifier from groups.csv |
| user_id | text | required | The user identifier from users.csv |
| status | enum | accepted | accepted, deleted |
Sample:
group_id,user_id,status G411208,U001,accepted G411208,U002,accepted G411208,U003,deleted
xlists.csv
| Field Name | Data Type | Default | Description |
|---|---|---|---|
| xlist_course_id | text | required | The course identifier from courses.csv |
| section_id | text | required | The section identifier from sections.csv |
| status | enum | active | active, deleted |
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.
Sample:
xlist_course_id,section_id,status E411208,1B,active E411208,2A,active E411208,2A,active