Data specification for provisioning IU guests and non-credit courses, sections, and enrollments in Canvas and Expand

On this page:

Before you begin

Campus units that offer non-credit courses or maintain their own course student information systems can make arrangements with the UITS LMS Development team to automate the provisioning of courses, enrollments, and guest users in Canvas or IU Expand. To request access to this service, complete the Canvas/Expand Provisioning App and API Request form.

There are two options for transmitting your Canvas data to UITS:

  • Upload files via a secure API. This method works best for automated batch jobs that run on a regular schedule. It can also be used for manual uploads with a properly configured REST client. For details, see About the Canvas and Expand Provisioning API.
  • Upload files with the Canvas and Expand Provisioning app in Canvas. This method is recommended for campus units and external partners who plan to upload their data manually. For details, see About the Canvas and Expand Provisioning app.

To use the Canvas and Expand provisioning services, your department's provisioning data must conform to the formatting requirements outlined below. These standards are based on Canvas's SIS Import Format Documentation, with modifications to accommodate specific use cases at IU.

Create users

Canvas accounts are automatically provisioned for all users within 24 hours of creation of their University account, so you should not need to include IU students, faculty, or staff in the users.csv file. Campus units can, however, use the users.csv file to provision accounts for individuals without a University account. If the user does not yet have an IU Guest account, when the file is processed, both an IU Guest account and a Canvas account will be created. The optional service column can be used to send users to Canvas or IU Expand after they log in.

Note:
When running provisioning jobs in the Canvas test (iu.test.instructure.com) or beta (iu.beta.instructure.com) environments, do not upload a users.csv file with information for real external users. Doing so will send guest account invitations to each user for the IU Login test environment, which they should not be using. You can use your own personal email accounts for testing guest account creation in the test environment.
  • Filename: users.unique_id.csv
  • File format: Comma-separated values with the following column headings and values:
    Column heading Value
    user_id (required)
    Leave this column blank. When this field is processed, it will be populated with the IU Guest account sequence ID, a unique ID assigned to each IU Guest account.
    login_id (required)
    Email address of the guest account to add or create
    first_name (required)
    First name of guest. This field is restricted to the ISO/IEC 8859-1 character set. Note that apostrophes must be straight ('), not curly (’).
    last_name (required)
    Last name of guest This field is restricted to the ISO/IEC 8859-1 character set. Note that apostrophes must be straight ('), not curly (’).
    email (required)
    Email address of guest; this should be identical to login_id.
    status (required)
    Leave this column blank. Every Canvas account will be created with "active" status.
    service (optional)
    Optionally, to control where the user is sent after creating the IU Guest account:
    • Use c or C for Canvas.
    • Use e or E for IU Expand.
    If you omit the column or leave it blank, users are sent to Canvas by default.

Example

See the example below; you can also download the template.

user_id,login_id,first_name,last_name,email,status,service
 ,joeschmoe1234@gmail.com,Joe,Schmoe,joeschmoe1234@gmail.com,,e
 ,tomjones4321@gmail.com,Tom,Jones,tomjones4321@gmail.com,,c

Notification messages

When each new Guest account is created, a generic notification is sent to the recipient with instructions for how to activate the account. You can also send an optional custom email message to each new guest Canvas user by uploading a text file named message.properties along with your users.csv file. For instructions on how to format the message.properties file and preview the custom email message before sending, see Send custom notifications to Canvas Guest account recipients.

Create or update courses

Departments can provision non-credit courses and credit courses that are not part of the standard SIS provisioning process.

  • Filename: courses.unique_id.csv
  • File format: Comma-separated values with the following column headings and values:
    Column heading Value
    course_id (required)
    A unique identifier used to reference courses in the enrollments data. This identifier must be globally unique. In the Canvas user interface, this is called the SIS ID for the course. Only Canvas superadmins can view or edit SIS IDs.

    At IU, course_ids for SIS-provisioned courses take the form SEMESTER-CAMPUS-SUBJECT-COURSE_NUMBER-SECTION_NUMBER (for example, FA15-IN-ENG-W131-99999). Departments that create their own course_ids are responsible for ensuring that they do not conflict with other course_ids in the system by developing a naming scheme that incorporates the department name or abbreviation into the section number portion of the ID.

    To view, set, or edit the Canvas course_id or section_id for non-credit courses, use the Course Attribute Editor app.
    short_name (required)
    A short descriptive name for the course
    long_name (required)
    A long descriptive name for the course enclosed in double quotation marks (for example, "long name for course"). This can be the same as the short name, but if both are available, users will have a better experience when you provide both.
    account_id (required)
    The account identifier for the node in the institutional hierarchy in which the course will be placed (for example, BL-BUKD, IUSM-IN)
    term_id
    A unique four-digit identifier for the term during which the course will be offered; for standard SIS Term IDs, see Current Term Processing Dates (downloadable Excel file).

    Note: The term must be available in Canvas before it can be referenced in the courses.csv file.
    status (required)
    Status of the course; accepted values are "active", "deleted", or "completed". Use "active" unless you want to delete or conclude the course.
    start_date
    The course start date; if the start_date is set, it will override the term start date. The date should be in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
    end_date
    The course end date; if the end_date is set, it will override the term end date. The date should be in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
    blueprint_course_id
    The SIS ID of a pre-existing Blueprint course; when provided, the current course will be set up to receive updates from the Blueprint course. The Blueprint Courses feature is required. To remove the Blueprint course link, pass dissociate in place of the ID. If the Blueprint course does not have an SIS ID, a Canvas superadmin can add one for you.

Example

See the example below; you can also download the template.

course_id,short_name,long_name,account_id,term_id,status,start_date,end_date,blueprint_course_id
1516-IN-IUSM-G730-154778,1516-IN-IUSM-G730-154778,OB/GYN CLERKSHIP,IUSM-Clerkships,1516,active,,,obgyn_bp
1516-IN-IUSM-K710-154046,1516-IN-IUSM-K710-154046,PEDIATRICS CLERKSHIP,IUSM-Clerkships,1516,active,,,
1516-IN-IUSM-M720-154304,1516-IN-IUSM-M720-154304,INTMED CLERKSHIP,IUSM-Clerkships,1516,active,,,

Create or update sections

For users to be enrolled into a course, the course must have at least one section. By default, when you attempt to enroll a user into a course with no sections, Canvas automatically generates a section with the same name as the course. Sections generated in this manner do not have a unique identifier that allows them to be called and manipulated via the Canvas API. For this reason, even though the sections.csv file is optional, generating at least one section for each course is recommended. A sections.csv file is required for you to add multiple sections to a single course shell.

  • Filename: sections.unique_id.csv
  • File format: Comma-separated values with the following column headings and values:
    Column heading Value
    section_id (required)
    A unique identifier used to reference sections in the enrollments data. Each section ID must be globally unique, but can be identical to the corresponding course ID. In the Canvas user interface, this is called the SIS ID for the section. Only Canvas superadmins can view or edit SIS IDs.

    At IU, section_ids for SIS-provisioned sections are identical to course_ids, taking the form SEMESTER-CAMPUS-SUBJECT-COURSE_NUMBER-SECTION_NUMBER (for example, FA15-IN-ENG-W131-99999). Departments that create their own section_ids are responsible for ensuring that they do not conflict with other section_ids in the system by developing a naming scheme that incorporates the department name or abbreviation.

    To view, set, or edit the Canvas course_id or section_id for non-credit courses, use the Course Attribute Editor app.
    course_id (required)
    The course identifier (from courses.csv) with which the section is associated. In the Canvas user interface, this is called the SIS ID for the course.

    To view, set, or edit the Canvas course_id or section_id for non-credit courses, use the Course Attribute Editor app.
    name (required) The name of the section
    status (required)
    Status of the section; accepted values are "active" and "deleted". Use "active" unless you want to delete the section.
    start_date
    The section start date; if the start_date is set, it will override the course and term start dates. The date should be in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
    end_date
    The section end date; if the end_date is set, it will override the course and term end dates. The date should be in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).

Example

See the example below; you can also download the template.

section_id,course_id,name,status,start_date,end_date
1516-MU-IUSM-N720-154932,1516-IN-IUSM-N720-154219,MU 04-25,active,,
1516-MU-IUSM-N720-154931,1516-IN-IUSM-N720-154219,MU 03-29,active,,
1516-MU-IUSM-N720-154930,1516-IN-IUSM-N720-154219,MU 02-29,active,,

Create or update enrollments

The enrollments.csv file associates users with specific courses or sections. The courses and sections referenced by the enrollments.csv file must have assigned SIS IDs. If you need assistance determining the SIS ID or assigning an SIS IDs to a Canvas course or section, email the UITS LMS Development team at lmsreq@iu.edu.

  • Filename: enrollments.unique_id.csv
  • File format: Comma-separated values with the following column headings and values:
    Column heading Value
    course_id (required)
    The course identifier from courses.csv or the SIS ID for an existing course.

    To view, set, or edit the Canvas course_id or section_id for non-credit courses, use the Course Attribute Editor app.
    user_id (required)
    For users with a University account, accepted values are the user's 10-digit University ID (also known as the student ID or emplID) or IU username. For IU Guest account holders, enter the email address associated with the user's guest account.
    role (required)
    User role in the course or section; accepted values are "student", "teacher", "ta", "observer", "designer", "Librarian", or a custom role defined by the account.
    section_id (required)
    The section identifier from sections.csv or the SIS ID for an existing section.

    To view, set, or edit the Canvas course_id or section_id for non-credit courses, use the Course Attribute Editor app.
    status (required)
    Status of the enrollment; accepted values are "active", "deleted", or "completed". Use "active" to add or keep an enrollment, "deleted" to remove an enrollment, or "completed" to conclude an enrollment and leave the user in the course.
    limit_section_privileges (optional)
    This column controls a user's ability to interact with one or all sections in the course. If the value is set to "true", the user will only be able to access other users in this section of the course; if the value is "false" or empty, the user will be able to interact with everyone in all sections of this course. While this can be an extremely useful setting for large classes with multiple sections, it has no impact on single-section courses. Review Student privacy in Canvas courses with cross-listed sections before using this column for managing student enrollments. Setting the wrong value could open your course to FERPA violations.

Example

See the example below; you can also download the template.

course_id,user_id,role,section_id,status,limit_section_privileges
1516-IN-IUSM-N720-154219,0009999999,teacher,1516-IN-IUSM-N720-154219,active,true
1516-IN-IUSM-N720-154219,astudent,student,1516-IN-IUSM-N720-154226,active
1516-IN-IUSM-N720-154219,joeschmoe1234@gmail.com,student,1516-IN-IUSM-N720-154226,deleted
1516-IN-IUSM-X720-154693,tomjones4321@gmail.com,student,1516-TH-IUSM-X720-154740,active

Create enrollments for listings in IU Expand

You can also use this process to enroll users in Canvas courses offered through IU Expand. To enroll users in an IU Expand listing, do not upload the standard enrollments.csv file described above. Instead format the file as described in this section.

  • Filename: expand.unique_id.csv
  • File format: Comma-separated values with the following column headings and values:
    Column heading Value
    user_id (required)
    For users with a University account, accepted values are the user's 10-digit University ID (also known as the student ID or emplID) or IU username. For IU Guest account holders, provide the user's IU Login name, which should be the same as the user's email address.
    listing_id (required)

    This is the internal numeric identifier for the listing in IU Expand. To determine the ID for an Expand listing:

    1. As an Expand Admin, navigate to the "Listings" page.
    2. Locate and open the listing of the course into which you want to enroll users. The URL for the listing should look something like this: 
      https://expand.iu.edu/admin#/products/99999/details

      The number following "products/" and preceding "/details" in the URL is the listing ID.
    send_email (optional)

    This column controls if an email is sent to the student for an Expand course, notifying them that they have been enrolled in the course.

    Setting the value to "true" sends a notification to the student. If the value is "false" or empty, then no email notification is sent.

Example

See the example below; you can also download the template.

user_id,listing_id,send_email
0009999999,27475,false
astudent,24954,true
joeschmoe1234@gmail.com,27475
tomjones4321@gmail.com,27475

This is document bfqc in the Knowledge Base.
Last modified on 2024-02-21 09:33:19.