Use this topic to understand 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 of D2L Standard CSV)
Sample D2L Standard CSV files
Sample CSV files are available for download in the IPSIS Learning Center course. This course provides up-to-date examples and guidance to help you get started with D2L Standard CSV.
We recommend visiting the course to access the latest sample files and related resources.
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 Secure File Transfer Protocol (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 a blank value.
- , , indicates a space character, which is parsed as an invalid value.
- The CSV files must have a header (first line) that is an exact match (casing and commas).
- CSV files must be UTF-8 encoded.
- CSV files should contain differential Student Information System (SIS) data (deltas) rather than complete SIS data drops.
- Sending an UPDATE action when the object does not exist results in a CREATE request. Typically, only UPDATE and DELETE actions are used.
- 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 identifies the version of D2L Standard CSV being used. For more information, refer to 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; supported in 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. After the integration controls an org unit, all future changes must be made through the integration.
- If sending many org unit types in one CSV file, ensure that hierarchy is respected (for example, send departments before course templates).
- If sending user relationships, ensure that hierarchy is respected (for example, send parents or guardians before learners).
- The naming convention for org unit name and code should follow that described in your SIS.
- Org unit names and codes can be used as-is if they meet Brightspace character requirements and are unique.
- Org unit codes are limited to 50 characters. Longer values are truncated and can cause duplication or failures.
- Org unit codes do not support the following characters: , : % & # * ? < > | \ " ' or leading/trailing spaces.
D2L Standard CSV can do the following:
- Create a new org unit if it does not exist.
- Map to an existing org unit if mapping is enabled in configuration.
- Update the name of an org unit that it controls.
- Assign and remove parent relationships between org units.
- Assign and update parent department for course templates.
- Assign and update parent course template and semester for course offerings.
- Update course offering details, including name and dates, and inactivate offerings.
- Delete course sections and automatically unenroll users.
- Delete an org unit that it controls.
D2L Standard CSV cannot do the following:
- Update org unit codes.
- Delete manually created org units unless they are mapped.
- Delete an org unit that has children linked to it.
Rules for users
User records can create, update, inactivate, or delete users in Brightspace and manage relationships.
Rules:
- Users must be sent at least once to establish management by the integration.
- First Name and Last Name do not support the following characters: \ / : * ? " < > | @ , ;
- Username and Org Defined ID do not support the following characters: / : * ? " < > | ' , ;
- Email addresses do not support the following characters: ( ) < > [ ] | \ ; : , "
D2L Standard CSV can:
- Create users and enroll them.
- Map users to existing accounts.
- Update user details.
- Update preferred and sortable names (version dependent).
- Update pronouns (version 3.0 or higher).
- Activate, inactivate, or delete users.
- Manage parent or guardian relationships.
- Update auditor relationships.
D2L Standard CSV does not:
- Update Org Defined ID through CSV.
- Delete manually created users unless mapped.
Rules for enrollments
Processing enrollment records enrolls or unenrolls users in org units.
Rules:
- Send enrollment records when changes occur in the source system.
- Send an unenrollment only once.
- When using sections, provide enrollment records only for sections.
- Avoid sending different roles for sections under the same offering.
- Customers should avoid sending different roles for sections under the same offering. This will result in the role being overwritten in the offering and in one of the sections as the LMS doesn't allow the section role to be different than the offering.
D2L Standard CSV can:
- Enroll and unenroll users in org units and sections.
Rules for Manager Dashboard and Learning Groups Attributes
Using D2L Standard CSV, Manager Dashboard and Learning Groups Attributes can:
- Establish reporting structures.
- Enable automatic membership rules in Learning Groups.
Manager Dashboard and Learning Groups Attributes via D2L Standard CSV does not:
- Create new user accounts.