Automate departmental enrollments for non-credit courses in Canvas

On this page:


Before you begin

Campus units with their own course registration and/or student information systems can make arrangements with the UITS LMS Development team to automate the provisioning of courses, enrollments, and guest users in Canvas. To learn more, contact the UITS LMS Development team.

For you to take advantage of IU's automated provisioning service, provisioning data must conform to the standards below. This information is based on Canvas's SIS Import Format Documentation, with modifications to accommodate specific use cases at IU.

Note:
Campus units are not permitted to create their own accounts (that is, nodes in the organizational hierarchy) or terms, as described in the Canvas documentation mentioned above. If your unit needs a custom term or a new account in the organizational hierarchy, contact the UITS LMS Development team.

Filename conventions

After you create your provisioning files, you will transmit them to a UITS Secure FTP (SFTP) server, as explained in the Transmit your files section below, where they will be processed by a batch job that runs at regular intervals.

If two unprocessed files of the same type are pushed to the drop location, they will be processed in alphabetical order.

To avoid overwriting previous versions and ensure that files are processed in the correct order, include both the file type and a unique identifier in each filename. UITS recommends using the following format:

filetype.YYYY-MM-DD_HH-MM-SS.csv

Replace filetype with the type of data the file contains (for example, users, courses, sections, enrollments) and replace YYYY-MM-DD_HH-MM-SS with the date and time of the file's creation.

For example:

courses.2018-12-03_23-30-15.csv

If you decide to use a different unique identifier, be sure to use only letters, numbers, hyphens, and underscores in your filename. Do not use spaces or special characters (for example, ~ ! @ # $ % ^ & * ( ) ` ; : < > ? , [ ] { } ' " / \).

Create users

Canvas accounts are automatically provisioned for all users with an IU Network ID within 24 hours of the creation of the ID, 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 Network ID. 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.

  • 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/create
    first_name (required) First name of guest
    last_name (required) Last name of guest
    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.

Example

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

Create 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 user interface, this is called the SIS ID.

    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.
    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).

Example

course_id,short_name,long_name,account_id,term_id,status,start_date,end_date
1516-IN-IUSM-G730-154778,1516-IN-IUSM-G730-154778,OB/GYN CLERKSHIP,IUSM-Clerkships,1516,active,,
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 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.

    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.
    course_id (required)
    The course identifier (from courses.csv) with which the section is associated
    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

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 enrollments

The enrollments.csv file associates users with specific courses or sections.

  • 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
    user_id (required)
    For users with an IU Network ID, 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.
    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; if none is specified, the default section for the course will be used. Required if course_id is missing.
    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.

Example

course_id,user_id,role,section_id,status
1516-IN-IUSM-N720-154219,0009999999,teacher,1516-IN-IUSM-N720-154219,active
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

Transmit your files

To transmit your provisioning files to UITS, you will place your files in a designated directory on a UITS SFTP server. You can do this manually with an SFTP client, or you can automate the process by writing a custom provisioning application that prepares and transmits the files as described below.

Request access to the SFTP servers

Access to the secure UITS SFTP servers is restricted to specific IU usernames and IP addresses. To request access for one or more users, contact the UITS LMS Development team with the following information:

  • Directory name: The name you'd like for the directory where you will drop your files. Typically this is a 5-8 letter abbreviation of the school or department that you represent (for example, BLCHEM, SICE, IUSO).
  • For each user account or group account that will need access to the SFTP servers, provide the following:
    • Name: The full name of the user.
    • IU username or IU group account username. If your department will be creating an automated provisioning application, UITS recommends using an IU group account instead of a personal account for authentication.
    • Static IP address (or IP range) of the workstation or server that will be used to log into the SFTP servers with the specified username. If you don't have a static IP address or a fixed range, an IT Pro in your school or department will need to make arrangements for access to IU's Groups VPN, which associates specific IP ranges with ADS security groups. For more, see Use the IU Groups VPN to restrict remote access to your team's administrative resources.

The LMS Development team will notify you when your designated directory has been established on the test and production SFTP servers.

Prepare your files for transmission

Each .csv file transferred to the SFTP server must have a corresponding .done file; for example, enrollment file enrollment.2018-12-03_23-30-15.csv must have a corresponding enrollment.2018-12-03_23-30-15.done file. The purpose of .done files is explained in the next section.

Connect to the SFTP server and transfer your files

Notes:
  • UITS recommends conducting a trial run with a small data set on the test server before you upload provisioning files to the production SFTP server. After you upload your sample data, the LMS Development team will work with you to confirm that all files were processed correctly and provisioned in the Canvas test environment.
  • When conducting a trial run, do not use legitimate guest email addresses in the users.csv file to create IU Guest accounts. Doing so will make it impossible to provision IU Guest accounts for the same email addresses in production.

To transmit your provisioning files to UITS for processing:

  1. Open a connection to the SFTP server using the following settings:
    • Host name: You will be given the host names for the test and production servers once your account is established.
    • File protocol: SFTP
    • Port number: 22
    • User name: Your IU username
    • Password: Your IU passphrase (do not save the password with the connection settings)
      Note:
      If you intend to automate the upload process, you will not use your IU username and passphrase to log in. Instead you'll be given a local account that can be paired with a secured key pair for authentication. For more, see Set up SSH public-key authentication to connect to a remote system.
  2. If your connection is successful, you will be placed in the root directory. Navigate to the designated directory for your school or department, located under the LMS/dept directory.
  3. Transfer all CSV files for the current run using drag and drop or the following command:
    mput *.csv
    
  4. Transfer the corresponding .done files using drag and drop or the following command:
    mput *.done
    

The presence of the .done files lets the LMS Development team know that the transmission of your CSV files is complete and that it is safe to begin processing those files.

This is document bfqc in the Knowledge Base.
Last modified on 2018-10-18 11:15:31.

Contact us

For help or to comment, email the UITS Support Center.