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 three options for transmitting your Canvas data to UITS:

  • Upload files to a directory on a secure FTP server. This method works best for automated batch jobs that run on a regular schedule. It can also be used for manual uploads, but requires significant advanced setup. For details, see Transmit your files via SFTP.
    Note:
    This option has been deprecated and is not available to new customers.
  • 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.

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, such as the following:

~ ! @ # $ % ^ & * ( ) ` ; : < > ? , [ ] { } ' " / \

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.

  • 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

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

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 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.
    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.
    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 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, contact the UITS LMS Development team.

  • 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
    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
    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

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.

Example

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

Transmit your files via SFTP

If you need to transmit provisioning data at regular intervals as part of an automated process, you can upload your files to the UITS secure FTP server.

Important:
The secure FTP transmission method has been deprecated and is only available to Canvas provisioning customers with existing DTT/DTP accounts. New customers who wish to automate provisioning jobs should use the Canvas and Expand Provisioning API.

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 2021-09-10 11:38:52.