This page explains how to create and build CSV files in the D2L Standard CSV format. It provides:
-
Common file content rules and recommended file naming conventions.
-
Accepted D2L Standard CSV files required for integration with IPSIS.
-
Sample structures and formats for each CSV file type.
Common CSV file content rules
- CSV files must be UTF-8 encoded.
- CSV files should contain differential SIS data (deltas) rather than complete SIS data drops.
- Values in files are case-sensitive. The instructions will detail the required case.
- An empty value is represented with two commas with no spaces between them. (for example, ,, indicates blank value, whereas , , 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) to that listed in the examples in the sections below.
- Subsequent lines in the file contain the data to be processed (created, updated, deleted)
- Sending an UPDATE action when the object does not exist results in a CREATE request. Common behavior is to use only the UPDATE or DELETE actions.
- A manifest is required when using version 1.1 or higher of D2L Standard CSV.
Accepted D2L Standard CSV 1.0 and 1.1 file formats
The file formats accepted by D2L Standard CSV 1.0 and 1.1. are:
- Orgs
- Users (V1 or V1.1)
- Enrollments
- Manifest (Required for V1.1)
- Manager Dashboard and Learning Groups Attributes
Files are to be uploaded in a zip archive. The recommended naming convention is:
- D2LStdCSV-{YYYYmmddHHMMSS}.zip
Note: Only .zip (case sensitive, lowercase only) archives are permitted to be uploaded to SFTP.
Files are processed in alphabetical order. It is recommended to send orgs, users, enrollments, then attributes.
Recommended CSV file naming conventions
The recommended naming convention for individual D2L Standard CSV files are:
- 01-Departments- {YYYYmmddHHMMSS}.csv
- 02-Semesters- {YYYYmmddHHMMSS}.csv
- 03-Templates-{YYYYmmddHHMMSS}.csv
- 04-Offerings-{YYYYmmddHHMMSS}.csv
- 05-Sections-{YYYYmmddHHMMSS}.csv
- 06-Users-{YYYYmmddHHMMSS}.csv
- 07-Enrollments-{YYYYmmddHHMMSS}.csv
- 08-Attributes-{YYYYmmddHHMMSS}.csv
- manifest.json
About Org Units and Org Unit Types
You can use D2L Standard CSV to create an organizational structure in Brightspace. This structure is based upon the Org Units defined in a CSV file and mapped to objects in Brightspace. Note the following best general practices when sending org unit information:
-
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 Type before the creation of the child results in the child Org Unit failing.
-
If sending user relationships, ensure that parents/guardians hierarchy is respected in the file. For example, parents/guardians should be sent before learners. Failing to do so results in the relationship failing.
-
The Org Unit naming conventions (Name/Code) should follow that described in your SIS. Brightspace can accept as many Org Units as needed, Org Unit names and codes can be fed as-is through the CSV files as long as names or codes respect Brightspace illegal character requirements and are unique across different Org Unit. Org unit codes are truncated if more than 50 characters, this could lead to duplication of org unit codes in Brightspace or failure to create an org unit. Illegal characters include :%&#*?<>|\"' and leading or trailing spaces.
Departments, Semesters, Course Templates, Course Offerings and Course Sections
Processing these Org Units creates the org structure in your Brightspace environment. These must be sent at least once to instruct D2L Standard CSV on which org units it is able to control. Once IPSIS 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.
You should only resend Org Units when a new Department or Semester needs to be added or updated in the org structure in the learning environment.
D2L Standard CSV can:
- Create a new Org Unit if it doesn’t exist
- Map to an existing Org Unit if it was created by a different source then D2L Standard CSV
- Update the name of an Org Unit that it controls
- 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, dates
- Course Section: Deleting a course section automatically unenrolls users from the deleted section
- Delete an Org Unit that it controls
D2L Standard CSV will not:
- Update Org Unit codes
- Delete manually created Org Units unless they been mapped with D2L Standard CSV
- Delete an Org Unit if it has children linked to it (children must be deleted first)
- Exception: if in the UI sections have been set up to be deleted, Course Offerings can be deleted if a Section is linked to it
Supported Org Unit types
The D2L Standard CSV integration creates, updates, and deletes specific Org Units types.
The following Org Unit types are supported by D2L Standard CSV 1.0 and 1.1:
- Departments
- Semesters
- Course Templates
- Course Offerings
- Sections
Note: Any Org Unit types not listed must be managed outside the D2L Standard CSV integration.
Users
Processing the user type creates, updates, inactivates or deletes users in Brightspace. Depending on the version of the User file you use, the user type could also create, update, or delete the parent-child relationship in Brightspace. Users must be sent at least once to instruct IPSIS on which User profiles it is able to create, update, or delete and manage enrollments of.
Illegal characters: \ / : ? " < > | ' , ;
D2L Standard CSV can:
- Create a new user if it doesn’t already exist
- Update username, First Name, Last Name, Password, and Email
- Update the Org level role
- Activate, inactivate, or delete a user
- Create, update, or delete a parent-child relationship (v 1.1)
- If a user exists with same OrgDefinedID then it can be mapped to the existing user
- Update a parent-child relationship for Brightspace Parent & Guardian
OR
- If a user exists with same ‘Username’ then it can be mapped to the existing user
D2L Standard CSV will not:
- Update OrgDefinedId
- Delete manually created users unless they have been mapped with D2L Standard CSV
Note: Brightspace Parent & Guardian allows authorized parents and guardians to log in to Brightspace to see their child's classroom activity feed, shared Portfolio items, upcoming online assignments, upcoming quizzes, grade items, and course grades. This helps parents engage with their young learners and maintain awareness of their upcoming work. For more information on Brightspace Parent & Guardian click here.
Enrollments
Processing the enrollment type enrolls or unenrolls users in Brightspace at the course section level. Enrollments should be sent when changes are made in the information system to accurately reflect those changes in Brightspace. An unenrollment should only be sent once. Resending the same unenrollment will cause warnings in your IPSIS log.
D2L Standard CSV can:
- Enroll users in course sections
- Un-enroll users in course sections
D2L Standard CSV will not:
- Enrolls users at other org levels
JSON manifest file
When a new feature is added to D2L Standard CSV that results in a breaking change to the file format, D2L releases the change by updating a manifest file. The manifest is a JavaScript Object Notation (JSON) file that declares the version of D2L Standard CSV that you are using. Below is the expected data structure to be included in the JSON file:
{
"version":"1.1"
}
Important: The manifest file must be included with every zip package of CSV files sent to IPSIS. If a manifest file is not included, the version defaults to 1.0. The file must be named manifest.json in lowercase. The version in the JSON file must match the version of IPSIS that your CSV outputs are currently aligned to.
Orgs
Orgs - Department
The following lists 3 rows of sample content for a Department (along with the required header line). File consists of 11 mandatory columns, each must be populated with a valid value or left empty depending on the file format.
type,action,code,name,start_date,end_date,is_active,department_code,template_code,semester_code,offering_code
department,UPDATE,sampledeptA,sample Department A,,,,,,,
department,UPDATE,sampledeptB,sample Department B,,,,,,,
department,UPDATE,sampledeptC,sample Department C,,,,,,,
Column
|
Field
|
Required
|
Possible Values |
Notes
|
1 |
type |
Required |
department |
Must be lowercase |
2 |
action |
Optional |
CREATE, UPDATE, DELETE |
Case insensitive. If not specified, default is UPDATE |
3 |
code |
Required |
|
The course you use must be a unique value to identify any one specific Org Unit and is case sensitive. it can be any alphanumeric value, however should not include commas.
Codes with more than 50 characters will be truncated.
|
4 |
name |
Required |
|
Name of Department |
5 |
start_date |
N/A |
|
Ignored |
6 |
end_date |
N/A |
|
Ignored |
7 |
is_active |
N/A |
|
Ignored |
8 |
department_code |
N/A |
|
Ignored |
9 |
template_code |
N/A |
|
Ignored |
10 |
semester_code |
N/A |
|
Ignored |
11 |
offering_code |
N/A |
|
Ignored |
Orgs - Semester
The following lists 3 rows of sample content for a Semester (along with the required header line). File consists of 11 mandatory columns, each must be populated with a valid value or left empty depending on the file format.
type,action,code,name,start_date,end_date,is_active,department_code,template_code,semester_code,offering_code
semester,UPDATE,FA2015,Fall 2015,,,,,,,
semester,UPDATE,WI2016,Winter 2016,,,,,,,
semester,UPDATE,SU2016,Summer 2016,,,,,,,
Column
|
Field
|
Required
|
Possible Values |
Notes
|
1 |
type |
Required |
semester
|
Must be lowercase |
2 |
action |
Optional |
CREATE, UPDATE, DELETE |
Case insensitive. If not specified, default is UPDATE |
3 |
code |
Required |
|
The course you use must be a unique value to identify any one specific Org Unit and is case sensitive. it can be any alphanumeric value, however should not include commas.
Codes with more than 50 characters will be truncated.
|
4 |
name |
Required |
|
Name of Semester |
5 |
start_date |
N/A |
|
Ignored |
6 |
end_date |
N/A |
|
Ignored |
7 |
is_active |
N/A |
|
Ignored |
8 |
department_code |
N/A |
|
Ignored |
9 |
template_code |
N/A |
|
Ignored |
10 |
semester_code |
N/A |
|
Ignored |
11 |
offering_code |
N/A |
|
Ignored |
Orgs - Course Template
The following lists 3 rows of sample content for a course template Org Unit (along with the required header line). File consists of 11 mandatory columns, each must be populated with a valid value or left empty depending on the file format.
type,action,code,name,start_date,end_date,is_active,department_code,template_code,semester_code,offering_code
course template,UPDATE,templatecode1,template name1,,,,parentdeptcode1,,,
course template,UPDATE,templatecode2,template name2,,,,parentdeptcode1,,,
course template,UPDATE,templatecode3,template name3,,,,parentdeptcode9,,,
Column
|
Field
|
Required
|
Possible Values |
Notes
|
1 |
type |
Required |
course template |
Must be lowercase |
2 |
action |
Optional |
CREATE, UPDATE, DELETE |
Case insensitive. If not specified, default is UPDATE |
3 |
code |
Required |
|
The code you use must be a unique value to identify any one specific Org Unit and is case sensitive. It can be any alphanumeric value, however should not include comma’s.
Codes with more than 50 characters will be truncated.
|
4 |
name |
Required |
|
Name of course template |
5 |
start_date |
N/A |
|
Ignored |
6 |
end_date |
N/A |
|
Ignored |
7 |
is_active |
N/A |
|
Ignored |
8 |
department_code |
Required |
|
Department Org Unit code |
9 |
template_code |
N/A |
|
Ignored |
10 |
semester_code |
N/A |
|
Ignored |
11 |
offering_code |
N/A |
|
Ignored |
Orgs - Course Offering
The following lists 3 rows of sample content for a course offering (along with the required header line). File consists of 11 mandatory columns, each must be populated with a valid value or left empty depending on the file format.
type,action,code,name,start_date,end_date,is_active,department_code,template_code,semester_code,offering_code
course offering,UPDATE,offering_code1,offering name 1,2015-07-07,2015-10-23,1,,templatecode2,Semestercode1,
course offering,UPDATE,offering_code2,offering name 2,2015-07-07,2015-10-23,1,,templatecode2,Semestercode1,
course offering,UPDATE,offering_code3,offering name 3,2015-07-07,2015-10-23,1,,templatecode3,Semestercode1,
Column
|
Field
|
Required
|
Possible Values |
Notes
|
1 |
type |
Required |
course offering |
Must be lowercase |
2 |
action |
Optional |
CREATE, UPDATE, DELETE |
Case insensitive. If not specified, default is UPDATE.
|
3 |
code |
Required |
|
The code you use must be a unique value to identify any one specific Org Unit and is case sensitive. It can be any alphanumeric value, however should not include commas.
Codes with more than 50 characters will be truncated.
|
4 |
name |
Required |
|
Name of course offering. Course names with commas need to be wrapped in double quotes
"course,name"
|
5 |
start_date |
Optional |
yyyy-mm-dd yyyy-mm-ddThh:mm:ss.fff
|
If no time is specified default time is T00:00:00.000 |
6 |
end_date |
Optional |
yyyy-mm-dd yyyy-mm-ddThh:mm:ss.fff
|
If no time is specified default time is T00:00:00.000 |
7 |
is_active |
Optional |
1. 0. TRUE, FALSE |
If not specified, default is 1. Case insensitive. |
8 |
department_code |
N/A |
|
Ignored |
9 |
template_code |
Required |
|
Course template Org Unit code |
10 |
semester_code |
Required |
|
Semester Org Unit code |
11 |
offering_code |
N/A |
|
Ignored |
Orgs - Course Section
The following lists 3 rows of sample content for a course section (along with the required header line). File consists of 11 mandatory columns, each must be populated with a valid value or left empty depending on the file format.
type,action,code,name,start_date,end_date,is_active,Department_code,template_code,Semester_code,offering_code
course section,UPDATE,sample_section1,section name 1,,,,,,,offering_code1
course section,UPDATE,sample_section2,section name 2,,,,,,,offering_code1
course section,UPDATE,sample_section3,section name 3,,,,,,,offering_code2
Column
|
Field
|
Required
|
Possible Values |
Notes
|
1 |
type |
Required |
course section |
Must be lowercase |
2 |
action |
Optional |
CREATE, UPDATE, DELETE |
Case insensitive. If not specified, default is UPDATE |
3 |
code |
Required |
|
The code you use must be a unique value to identify any one specific Org Unit and is case sensitive. It can be any alphanumeric value, however should not include commas.
Codes with more than 50 characters will be truncated
|
4 |
name |
Required |
|
Name of course offering |
5 |
start_date |
N/A |
|
Ignored |
6 |
end_date |
N/A |
|
Ignored |
7 |
is_active |
N/A |
|
Ignored |
8 |
department_code |
N/A |
|
Ignored |
9 |
template_code |
N/A |
|
Ignored |
10 |
semester_code |
N/A |
|
Ignored |
11 |
offering_code |
Required |
|
Course offering org code |
Users
Users (Version 1.0 - excluding relationships)
The following lists 2 rows of sample content for a user (along with the required header line). File consists of 10 mandatory columns, each must be populated with a valid value or left empty depending on the file format.
type,action,username,org_defined_id,first_name,last_name,password,is_active,role_name,email
user,UPDATE,TEST1,orgdeftest1,first,last,,1,Instructor,test1@somedomain.edu
user,UPDATE,john.smith,55120,John,Smith,,1,Learner,john.smith@yourdomain.edu
Column
|
Field
|
Required
|
Possible Values |
Notes
|
1 |
type |
Required |
user |
Must be lowercase. |
2 |
action |
Optional |
CREATE, UPDATE, DELETE |
Case insensitive. If not specified, default is UPDATE. |
3 |
username |
Required |
|
Username |
4 |
org_defined_id |
Required |
|
The code you use for the OrgDefinedId must be a unique value used to identify any one specific user only. D2L recommends using SIS SourceID.
|
5 |
first_name |
Required |
|
|
6 |
last_name |
Required |
|
|
7 |
password |
Optional |
|
If a password is not specified, Brightspace will generate a password.
If a password is not specified and you are logging in using native authentication, on the Brightspace login page, click Forgot your password? to reset your password.
|
8 |
is_active |
Required |
1, 0, TRUE, FALSE |
Case insensitive. |
9 |
role_name |
Required |
|
Role name at the organization level |
10 |
email |
Optional |
|
|
Users (Version 1.1 - including relationships)
The following lists 3 rows of sample content for a user (along with the required header line). File consists of 10 mandatory columns, each must be populated with a valid value or left empty depending on the file format.
type,action,username,org_defined_id,first_name,last_name,password,is_active,role_name,email, relationships
user,UPDATE,TEST1,orgdeftest1,first,last,,1,Parent,test1@somedomain.edu
user,UPDATE,TEST1,guardian.test,first,last,,1,Parent,test1@somedomain.edu
user,UPDATE,sam.child,orgdefinedtest2,First2,Last2,,1,Learner,email3@email.com,"[{""Type"": ""Parent"", ""Id"": ""orgdeftest1""}, {""Type"": ""Guardian"", ""Id"": ""guardian.test""}]"
Column
|
Field
|
Required
|
Possible Values |
Notes
|
1 |
type |
Required |
user |
Must be lowercase. |
2 |
action |
Optional |
CREATE, UPDATE, DELETE |
Case insensitive. If not specified, default is UPDATE. |
3 |
username |
Required |
|
Username |
4 |
org_defined_id |
Required |
|
The code you use for the OrgDefinedId must be a unique value used to identify any one specific user only. D2L recommends using SIS SourceID.
|
5 |
first_name |
Required |
|
|
6 |
last_name |
Required |
|
|
7 |
password |
Optional |
|
If a password is not specified, Brightspace will generate a password.
If a password is not specified and you are logging in using native authentication, on the Brightspace login page, click Forgot your password? to reset your password.
|
8 |
is_active |
Required |
1, 0, TRUE, FALSE |
Case insensitive. |
9 |
role_name |
Required |
|
Role name at the organization level |
10 |
email |
Optional |
|
|
11 |
relationships |
Optional |
Parent, Guardian |
JSON object including relationship type and OrgDefinedId of parent/guardian.
Explicitly updates, to remove a relationship, relationship should not be in file.
|
Enrollments
The following lists 3 rows of sample content for an enrollment (along with the required header line). File consists of 5 mandatory columns, each must be populated with a valid value or left empty depending on the file format.
type,action,child_code,role_name,parent_code
enrollment,UPDATE,orgdeftest1,Instructor,test_section_code1
enrollment,UPDATE,56795,Learner,test_section_code2
enrollment,DELETE,56418,Learner,test_section_code3
Column
|
Field
|
Required
|
Possible Values |
Notes
|
1 |
type |
Required |
user |
Must be lowercase. |
2 |
action |
Optional |
CREATE, UPDATE, DELETE |
Case insensitive. If not specified, default is UPDATE. |
3 |
child_code |
Required |
|
OrgDefinedId |
4 |
role_name |
Required |
|
Course level role. This role can be different than the role used when creating a user. |
5 |
parent_code |
Required |
|
Course section org code |