Uploading Courses in Bulk

Owned by Luc Richard
Last updated: Aug 09, 2024
9 min read

The learning environment allows System Administrators to create multiple courses at once using a CSV file. This is particularly useful during the implementation phase, when you need to migrate courses from your old system to the Dual Code learning environment. In addition to creating new courses, the Upload Courses functionality may also be used to update or delete courses, or import content from another course.

To upload one or more courses:

  1. Go to Site Administration > Courses > Upload courses

  2. Either drag and drop the CSV file or click the 'Choose a file' button and select the file in the file picker

  3. Select appropriate import options carefully, then click the preview button.

NOTE: It is recommended that you use the "Preview" option to see if any errors were detected in the previewed rows. If you proceed with the upload and there were something wrong detected with a course, it will be ignored.

Valid Upload File for Testing

The text file to upload courses must be a CSV file. It can be created using Microsoft Excel or any other application, as long as it can be saved to a CSV format. Here is an example of a simple valid upload file.

shortname,fullname,category_path,summary
WHMIS,Workplace Hazardous Materials Information System,Classroom,This is my summary
Workplace Violence,Preventing Violence in the Workplace,Online,"This is my summary, with a comma"

Notice there are no spaces between the items. It is also very important to notice the last example (Workplace Violence) where the summary text is placed in quotation marks ("This is my summary, with a comma"). This is essential to ensure that the commas in the summary are not interpreted by the course upload tools as the end of a field. Be aware that quotation marks can be used to enclose some fields (such as fullname) but not others (such as shortname).

Creating the File for Import

The CSV file accepts the following columns which are divided in two categories, the course information, and the course actions.

Course Information Fields

Most of those settings are available on the settings page of a course. Please refer to course settings for more information. Field names must be lower-case.

  • shortname: The shortname for the course

  • fullname: The full name for the course

  • idnumber: The ID number for the course

  • category: The ID of the category to place the course in. This takes precedence over category_idnumber and category_path.

  • category_idnumber: The ID number of the category to place the course in. This takes precedence over category_path.

  • category_path: The path of the category to place the course in. If you want to place the course in a category named "Clinical" which is located under the category "Classroom", the value to provide is: Classroom / Clinical. Note that the separator must be [space]/[space]. Also note that the category MUST exist, it will not be created. If you want to place the course in the top-level category "Clinical", the value to provide is: Clinical

  • visible: Use the value 1 if the course is visible, 0 if hidden

  • startdate: The time at which the course starts. The format should be DD.MM.YYYY. For example, to set a start time of December 1st 2014, use 01.12.2014

  • summary: The summary of the course

  • format: The course format to use, this must be a valid course format plugin name. The existing valid values are "topics", "weeks", "singleactivity" and "grid"

  • showgrades: Use the value 1 to show the gradebook to students, 0 to hide it.

  • showreports: Use the value 1 to show the activity reports, 0 to hide it.

  • maxbytes: The maximum upload size of the course in bytes. Use 0 for the site limit.

  • groupmode: Use the value 0 for No groups, 1 for Separate groups and 2 for Visible groups.

  • groupmodeforce: Use the value 1 to force the group mode, otherwise enter 0.

  • enablecompletion: Use the value 1 to enable the activity completion, 0 not to.

  • sitecertificate: Used to specify the name of the certificate of completion to attach to the course.

  • expiration: Specifies whether or not the learning record generated by the course will expire. The valid values are “never”, “time” and “date”.

    • Never means the learning record will never expire

    • Time means the learning record will expire after a certain amount of time (in days, months or years)

    • Date means the learning record will expire at a specific date as defined by “expiration_date”

  • expiration_time_unit: Specifies the unit when “expiration_type” is set to “time”. The valid values are “day”, “month” and “year” (all singular).

  • expiration_time_number: Specify the number of units (as per “expiration_time_unit”). Must be a positive integer.

    • For example, if you wanted the learning record to expire 1 year after it was issued, you would set the following:

      • expiration_type = time

      • expiration_unit = year

      • expiration_number = 1

  • expiration_time_round_up: Specifies, when expiration = time, whether to round up the expiration date to the last day of the month. The valid values are 0 (do not round up) and 1 (round up).

    • For example, a user completes a course for the first time on March 15, 2024. The learning record for the course is set to expire every 365 days. If expiration_time_round_up is set to 0, then the expiration date for the learning record will be March 15, 2025. If expiration_time_round_up is set to 1, then the expiration date for the learning record will be March 31, 2025 because March 31st is the last day of the month of March.

  • expiration_date_month: The month that the learning record issued by the course will expire. This valid values are from 1 to 12, where 1 is January, 2 is February, etc.

  • expiration_date_day: The day that the learning record issued by the course will expire. The valid values are from 1 to 31 (depending on the month in question).

  • expiration_date_frequency: How frequently (in years) the learning record will expire when expiration = date. The valid values are from 1 to 10, where one means “every year”, 2 means “every 2 years”, etc.

  • recertification: Specifies whether or not the user can get recertify (e.g. get another learning record after already having received one). The valid values are “anytime”, “never” and “specific”.

    • Anytime means the user can get recertified anytime they want

    • Never means that the user can never get recertified (unless an administrator intervenes and or expires their previous learning records for the course in question)

    • Specific means that means that you will define a specific recertification window / timeframe using the “recertification_unit” and “recertification_value” fields

  • recertification_unit: Specifies the unit when “recertification” is set to “specific”. The valid values are “day”, “month” and “year” (all singular).

  • recertification_number: Specify the number of units (as per “recertification_unit”). Must be a positive integer.

    • For example, if you wanted the users to be able to start the recertification process 90 days before their next due date for the course, you would set the following:

      • recertification = specific

      • recertification_unit = day

      • recertification_number = 90

  • recertification_ontime: Specifies, when the user completes the course on time (e.g. before or on their due date), if the expiration date newly issued learning record (when a user gets recertified) will be based on the date the user completes the course, or the date of the previous learning record. The valid values are “completion” and “expiration”.

    • For example, let’s assume a user needs to complete the “First Aid” every 2 years. They completed it in early 2022 and their due date is currently March 31st, 2024. The user completes “First Aid” on February 15, 2024. If “recertification_ontime” is set to “completion”, the next due date for the user in question will be “February 15, 2026”. However if “recertification_ontime” is set to “expiration”, their next due date will be March 31st 2026 (to maintain the original due date of March 31st from two years earlier).

  • recertification_overdue: Specifies, when a user completes the course late (e.g. missed their due date), if the expiration date newly issued learning record (when a user gets recertified) will be based on the date the user completes the course, or the date of the previous learning record. The valid values are “completion” and “expiration”.

    • For example, let’s assume a user needs to complete the “First Aid” every 2 years. They completed it in early 2022 and their due date is currently March 31st, 2024. The user completes “First Aid” on April 15, 2024. If “recertification_overdue” is set to “completion”, the next due date for the user in question will be “April 15, 2026”. However if “recertification_overdue” is set to “expiration”, their next due date will be March 31st 2026 (to maintain the original due date of March 31st from two years earlier).

Custom Fields

As of version 3.9, it is possible to include custom fields in courses. For example, a "duration" field is added by default to all installations so that an instructor can specify the expectation duration for a course. To upload information to custom fields, the convention is to add the word "customfield_" followed by the short name of the field.

For example, to upload the duration a course, the field name in the CSV file would be "customfield_duration". The field is simply a text field, so the value would be "1:00" for a 1 hour course. It is important that you follow this convention, which is HH:MM. Typing "1 hour" or "60 minutes" may result is display issues in certain reports and web pages.

Below are the conventions for uploading different file types.

Field Type

Field Name

Field Value

Sample Value

Additional Notes

Field Type

Field Name

Field Value

Sample Value

Additional Notes

Checkbox

customfield_[shortname]

0 = unchecked

1 = checked

1



Date and time

customfield_[shortname]

YYYY-MM-DD HH:MM

2021-06-28 14:00



Dropdown menu

customfield_[shortname]

Value of selection

10

The system does not verify / validate the value to see if it exists in the list of valid values for the field. In other words, if the list of valid values are 1-5 and you enter 10 in the CSV, the value of 10 will still be uploaded but you will not be able to see it when viewing the course information because "10" is not considered a valid value.

Also, the field is case sensitive. So if the valid values are A-Z and you enter lowercase a in the CSV, the value of a will still be uploaded but it will not be considered different than uppercase A.

Short text

customfield_[shortname]

Text

Hello World

If entering commas in your text, you must wrap the value in quotes.

HTML is NOT supported in this field.

Text area

customfield_[shortname]

Text

Hello World. Goodbye !!

If entering commas in your text, you must wrap the value in quotes.

HTML is supported in this field.

Enrolment Fields

Some fields can be constructed to enable and configure enrolment methods. The fields must be named enrolment_[number] for the enrolment method name, and enrolment_[number]_property for its properties.

  • enrolment_[number]: The name of the enrolment method (e.g. manual)

  • enrolment_[number]_delete: 1 to delete this enrolment method from the course. If set to 1 all the other properties will be ignored.

  • enrolment_[number]_disable: 1 to disable this enrolment method from the course. If set to 1 all the other properties will be ignored.

  • enrolment_[number]_startdate: The enrolment start date. This value is passed to the PHP function strtotime().

  • enrolment_[number]_enddate: The enrolment end date. This value is passed to the PHP function strtotime().

  • enrolment_[number]_enrolperiod: Number of seconds, or if not a value understood by strtotime() such as "4 days".

  • enrolment_[number]_role: The role short name

  • enrolment_[number]_[property]: Where property is understood by the specified enrolment method

  • enrolment_[number]_password: The course enrolment key (if understood by the specified enrolment method)

Note: The "Upload courses" is not compatible with all enrolment methods.

The following is a sample excerpt from a file where you would want to enable "manual" registration but disable "self" registration.

shortname,enrolment_1,enrolment_1_role,enrolment_1_enrolperiod,enrolment_2,enrolment_2_disable
WHMIS,manual,student,1 month,self,1

Role Renaming

To rename some roles for a specific course, you can use the following pattern:

  • role_[shortname]: The new name of the role [shortname]

The following is a sample excerpt from a file where you would want to rename the student and teacher roles.

shortname,role_student,role_editingteacher
WHMIS,Apprentice,Master

NOTE: The short name for the teacher role is editingteacher and the short name for the non-editing teacher is teacher.

Course Action Fields

  • delete: Use the value 1 to delete the course

  • rename: The shortname to rename the course to

  • templatecourse: The short name of a course to import the content from

  • reset: Use the value 1 to reset the course

Mandatory Fields

  • shortname: This field is mandatory for every operation, with the only exception of creating new courses.

  • fullname: Required when creating a new course.

  • category, category_idnumber, category_path: One of these is required when creating a course. category (with the idnumber of the category in the field) is required when renaming a course.

Import options

To prevent unexpected behaviour, you have to specify what you want the tool to be able to do.

  • Upload mode: This allows you to specify if courses can be created and/or updated.

  • Update mode: If you allow courses to be updated, you also have to tell the tool what to update the courses with.

  • Allow deletes: Whether the delete field is accepted or not

  • Allow renames: Whether the rename field is accepted or not

  • Allow resets: Whether the reset field is accepted or not

Course process

This allows you to specify actions to be taken for every course uploaded.

  • Shortname template: If you are creating courses without a shortname, you can use this field to automatically generate a shortname. This field accepts two placeholders: %i for the ID number, %f for the summary.

  • Restore file: A backup file (.mbz) to import in the course after create/update.

  • Restore from course: The shortname of a course to import content from after create/update.

  • Reset after upload: Whether to reset the course after creating/updating it.

Default Course Values

Those are values that can be set in the web interface for all the fields that are not specified in the CSV file. Note that they are always used when creating a course, but only when specified during update (see Update mode).

Increasing Speed

When importing the content of a backup file, or another course, you are advised to enable the setting keeptempdirectoriesonbackup. This will considerably speed up the process of the upload if you are importing multiple times from the same source.