This topic explains the conventions and requirements for D2L Standard CSV file formats.
Accepted formats for D2L Standard CSV files
The file formats accepted by D2L Standard CSV are:
- Orgs
- Users
- Enrollments
- Manager Dashboard and Learning Groups Attributes
- Manifest (required when using version 1.1 or higher or D2L Standard CSV)
Zip archive format for D2L Standard CSV files
CSV files must be combined into a zip archive. The recommended naming convention for a zip archive is:
- D2LStdCSV-{YYYYmmddHHMMSS}.zip
|
Note: You can only upload .zip (case sensitive, lowercase only) archives to SFTP. |
Files are processed in alphabetical order. D2L recommends individual files in the archive be ordered as follows:
- orgs
- users
- enrollments
- attributes
Recommended naming conventions for D2L Standard CSV files
The recommended naming convention for individual files within a .zip archive is:
- 01 - Other - {YYYYmmddHHMMSS}.csv
- 02 - Departments - {YYYYmmddHHMMSS}.csv
- 03 - Semesters - {YYYYmmddHHMMSS}.csv
- 04 - Templates - {YYYYmmddHHMMSS}.csv
- 05 - Offerings - {YYYYmmddHHMMSS}.csv
- 06 - Sections - {YYYYmmddHHMMSS}.csv
- 07 - Users - {YYYYmmddHHMMSS}.csv
- 08 - Enrollments - {YYYYmmddHHMMSS}.csv
- 09 - Attributes - {YYYYmmddHHMMSS}.csv
- manifest.json
|
Note: The 01 - Other CSV is used to process custom org units outside the standard D2L org structure and requires D2L Standard CSV version 2.0 or higher. |
Common CSV file content rules
- Values in files are case-sensitive.
- An empty value is represented with two commas with no spaces between them. For example:
- ,, indicates blank value
- , , indicates a space character, which is parsed as an invalid value.
-
The CSV files must have a header (first line) that must be an exact match (casing and commas).
- CSV files must be UTF-8 encoded.
- CSV files should contain differential SIS data (deltas) rather than complete SIS data drops.
-
Sending an UPDATE action when the object does not exist results in a CREATE request. Common behavior is to use only UPDATE and DELETE actions.
- CSV files and the manifest must be contained in the zip archive.
- A manifest is required when using version 1.1 or higher of D2L Standard CSV. The manifest is a JSON file that announces the version of D2L Standard CSV you are using. For more information, view the Manifest topic.
-
As a best practice, do not include Personally Identifiable Information (PII), such as social security numbers in Org Defined IDs for users.
Rules for Org Units
Org unit types listed below are supported by D2L Standard CSV:
- Other org units (custom org units outside of the standard D2L org structure is supported in D2L Standard CSV version 2.0 or higher)
- Departments
- Semesters
- Course Templates
- Course Offerings
- Sections
Processing these org units creates the org structure in your Brightspace instance.
Rules:
- Brightspace can accept as many Org Units as needed.
- Orgs must be sent at least once to instruct D2L Standard CSV on which org units it can control. Once the integration controls an org unit, all future changes to that org unit must be made only through the D2L Standard CSV integration to ensure accurate ownership of the data.
- If sending many Org Unit Types in one CSV file, ensure that hierarchy is respected in the file (for example, Departments should be sent before Course Templates). Failing to send a parent Org Unit before the creation of the child will result in the child Org Unit failing.
- If sending user relationships, ensure that the auditors and/or parent-guardian hierarchy is respected in the file (for example, parents/guardians must be sent before learners). Failing to do so results in the relationship failing.
- The naming convention for org unit name and code should follow that described in your SIS.
- Org Unit names and codes can be fed as-is through the CSV files if they respect Brightspace's illegal character requirements and are unique across different Org Units.
- Org unit codes are limited to 50 characters. If they are longer, the org unit code is automatically truncated to 50, and could lead to duplication of org unit codes in Brightspace or failure to create an org unit.
- Org unit codes do not support the following characters: , : % & # * ? < > | \ " ' and leading or trailing spaces.
D2L Standard CSV can do the following:
- Create a new org unit if it doesn’t exist.
- Map to an existing org unit if it was created by a source other than D2L Standard CSV and the option to map to existing is selected in the configuration.
- Update the name of an org unit that it controls.
- Assign and remove custom org units as parents to other custom org units, departments, semesters, course templates, course offerings and course sections (applicable to D2L Standard CSV version 2.0 or higher).
- Course template: assign and update parent Department based on the Department code.
- Course offering: assign and update parent course template and semester based on the parent code.
- Course offering: Update all course details including course offering name and dates. Inactivate Course Offering.
- Course section: Deleting a course section automatically unenrolls users from the deleted section.
- Delete an org unit that it controls.
D2L Standard CSV cannot do the following:
- Delete manually created org units unless they are mapped with D2L Standard CSV.
- Delete an org unit if it has children linked to it (children must be deleted first). One exception occurs if sections are set up for deletion in the interface - course offerings can be deleted if a section is linked to it.
Rules for Users
User records can create, update, inactivate, or delete users in Brightspace. The user record type can also create, update, or delete parent-child relationships in Brightspace.
Rules
- Users must be sent at least once to instruct the integration on which ones it’s able to create, update, delete, and manage enrollments for.
- First Name and Last Name do not support the following characters: \ / : * ? " < > | @ , ;
- Username and Org Defined ID do not support the following characters: / : * ? " < > | ' , ;
- Email address does not support the following characters: ( ) < > [ ] | \ ; : , “
D2L Standard CSV can:
- Create a new user and enroll them in the organization.
- Map a user to an existing user with the same Org Defined ID or Username.
- Update Username, First Name, Last Name, Password, and Email.
- Update Preferred First Name and Preferred Last Name (D2L Standard CSV version 2.0 or higher).
- Update Sortable Last Name (D2L Standard CSV version 2.1 or higher).
- Update Pronouns (D2L Standard CSV version 3.0 or higher).
- Password is not required and recommended not to be sent if using Single-Sign-On (SSO).
- Update the org level role.
- Activate, inactivate, or delete a user.
- Create, update, or delete parent/guardian-child relationships for Brightspace Parent & Guardian (D2L Standard CSV version 1.1 or higher).
- Update an auditor-auditee relationship (D2L Standard CSV version 2.0 or higher).
D2L Standard CSV does not:
- Update Org Defined ID; however, this can be done manually in the IPSIS administration interface.
- Delete manually created users unless they are mapped with D2L Standard CSV.
|
Note: For users in countries including the Netherlands, Belgium and Sri Lanka, some surnames (such as Van der Speigle or Van Gogh) have one or more prefixes (known in Dutch as Tussenvoegsel) that are part of the formal last name. In some cases, the sortable last name should not include those prefixes. Administrators can indicate if a user's Legal Last Name differs from the Sortable Last Name. If clients include a Sortable Last Name, Brightspace uses Sortable Last Name when alphabetizing user lists. Sortable Last Name is available in D2L Standard CSV version 2.1 or higher. |
Rules for Enrollments
Processing the enrollment records enrolls or unenrolls users in a specific org unit in Brightspace.
Rules:
Enrollment records should be sent when changes are made to the information system.
- An unenrollment should be sent only once. Resending the same unenrollment record leads to a warning in your IPSIS log.
- When using sections in course offerings, provide enrollment records only for sections. Enrollment into the course offering is implied and handled by IPSIS.
- Sending enrollment records for both course offerings and sections but sending unenrollments for just sections can lead to users being incorrectly re-enrolled into course offerings during course merging.
D2L Standard CSV can:
- Enroll and unenroll users in org units (version 2.0 or higher), course offerings, and sections.
- Enroll and unenroll from just course sections (version 1.0 and 1.1).
Rules for Manager Dashboard and Learning Groups Attributes
Using D2L Standard CSV, Manager Dashboard and Learning Groups Attributes can:
- Establish the reporting structure that is used within Manager Dashboard.
- Allow automatic membership rules to be created in Learning Groups.
Manager Dashboard and Learning Groups Attributes via D2L Standard CSV does not:
- Create new user accounts.