Creating course upload files
  • 28 Mar 2023
  • 6 minutes to read

Creating course upload files


Article Summary

If you want to bulk upload courses to your site, you will need to create a CSV file.

Example file

Below is an example of an upload file, where the course short name, full name, and category are all set. Note that there are no spaces between the items.

shortname,fullname,category
courserestored,Course restored,1
courserestored2,Course restored 2,1
courserestored3,Course restored 3,1
courserestored4,Course restored 4,1

In the above example the first row (shortname,fullname,category) sets out the column headings.

The first entry (or column) in each proceeding row is then the course shortname, so in this example the course shortnames are: courserestored, courserestored2,  courserestored3,  courserestored4.

The next column is the full name for the course, this is what would be displayed at the top of the course. In this example the desired full names are: Course restored, Course restored 2, Course restored 3, Course restored 4.

In this example the last column is the course category, which always uses the category ID rather than the category name. So for this example the category ID is 1 which is used for a category called Miscellaneous (although you can't tell that from the example as you only use the category ID and not the name). Categories must already exist in order to use them in a course upload. If you put a category ID that does not exist you will receive an error, Could not resolve category by ID during the upload preview, meaning that any courses in that category will not be created. 

Whatever other fields you include (see below) the file requires the fields shortname, fullname, and either category, category_idnumber, or category_path.

Creating the text file

The text file to upload courses must be a CSV file. When creating your file you can use the following columns.

Course information fields

Most of these settings are available in the course settings. Note that some of these settings can be enabled or disabled using either 1 (enabled) or 0 (disabled). This is useful if you want a certain setting enabled for some of the courses you are uploading but not all of them. If you do not want to change the default setting for any of the courses you are uploading then you would simply not include the field in the file, as none of the fields controlled in this way are mandatory to include in the file.

Field names must be lowercase.
Field nameDescription

fullname

The course full name.

shortname

The course short name.

idnumber

The course ID number.

category

The ID of the category in the Totara database. This takes precedence over category_idnumber and category_path.

category_idnumber

The idnumber of the category to add the course to.

category_path

The full path of the category to which the course will be added. If you have a top-level category with the shortname 'Engineering' and a subcategory called 'Machine Learning' to which you want to add the course, then you would set category_path to 'Engineering / Machine Learning'.

visible

If using traditional visibility, set this to 1 to make the course visible, and 0 to make it hidden.

audiencevisible

If using audience-based visibility, the following values apply: 0 for enrolled users, 1 for enrolled users and selected audiences, for all users, and for no users.

startdate

The date on which the course starts, e.g. dd/mm/yyyy.

enddate

The date on which the course ends, e.g. dd/mm/yyyy.

summary

The course summary.

format

The course format. This must be a valid format that has been enabled on your site.

theme

The name of the theme the course will be forced to use.

lang

The default language for the course.

newsitems

The number of news items to display in the news block when used.

showgrades

Set to 1 to enable learners to view the gradebook, and 0 to hide the gradebook.

showreports

Set to to enable activity reports, and to hide them.

legacyfiles

Set to to enable legacy course files, and to leave it disabled (recommended).

maxbytes

Set the maximum upload size (in bytes) for files within the course. Set to to use the site limit.

groupmode

Set the group mode for the course. Use for no groups, for separate groups, and for visible groups.

groupmodeforce

Set to to force the group mode, and to to allow activities to choose the group mode.

enablecompletion

Set to to enable completion tracking for trackable roles, and to disable completion tracking.

completionstartonenrol

Set to to start tracking completion when a user is first enrolled, or set to to only start tracking completion when required by a trackable event.

coursetype

The course type. Set to 0 for e-learning, 1 for blended, 2 for seminar.

tags

A comma-separated list of tags to add to the course.

Import options

These settings take precedence over the Course process parameters, which relate to what happens to the course such as renaming, templates, and resets.

Field nameDescription

delete

If set to 1 (and the course exists), it will be deleted.

rename

If set to 1 (and the course exists), its shortname will be updated from the CSV file.

backupfile

An absolute path to a backup file to import into the course.

templatecourse

The shortname of a course to import content from.

reset

If set to 1 (and the course exists), it will be reset during this process.

Note that the following course attributes will not be restored when uploading courses via CSV file: 

  • Course image
  • Icon
  • Collapsible sections
  • Section header colours
  • Completion progress tracking on view
  • Summary format
  • Calendar type

Role renaming

During the course upload, you can rename some roles by using the format role_[shortname] for the column heading, and then the new course short name in the course row. For example:

role_student,role_editingteacher,role_teacher
padawan,master,jedi

This would rename the Learner role (role_student) to padawan, the Editing Trainer role (role_editingteacher) to master, and the Trainer role (role_teacher) to jedi.

Field nameDescription

role_*

For renaming roles in the course, * is the role shortname from the defined role in the database.

Course format options

Field nameDescription

numsections

The number of course sections (for the demo, topics, and weeks formats).

hiddensections

For the demo, topics, weeks formats only.

coursedisplay

For the demo, topics, weeks formats only.

numdiscussions

For the social format only.

activitytype

The type of activity for a course using the single activity format.

Enrolment options

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

Field nameDescription

enrolment_*_*

To set enrolment options, the first wildcard (*) is a digit representing the enrolment instance, and the second wildcard is the name of the setting to set. The following settings can be used: delete, disable, startdate, enddate, enrolperiod, role, and other options presented by the enrolment instance type.

For example, you might have:

enrolment_1,enrolment_1_role,enrolment_2,enrolement_2_startdate
manual,learner,self,20170629

In this example, the file is setting enrolment_1 as the manual enrolment method, and the default role as learner. Then, enrolment_2 is set to the self-enrolment method, with a course start date of 2017-06-29 (or the 29th June 2017). 

This information would all come after the mandatory course shortname, fullname, and category, meaning a full example might be:

shortname,fullname,category,enrolment_1,enrolment_1_role,enrolment_2,enrolment_2_startdate
courserestored,Course restored,1,manual,learner,self,20170629
courserestored2,Course restored 2,1,manual,learner,manual,20170530
courserestored3,Course restored 3,1,self,editingtrainer,self,20181212
courserestored4,Course restored 4,1,self,learner,manual,20180107

Upload courses is not yet compatible with all enrolment methods.

Notes about behaviour

The course upload tool uses the restore functionality when you provide it with a backup file, and it does not turn on the Overwrite course configuration option. Settings such as completionprogressonview and numsections are not carried from the backup to the course for this reason. The course upload tool does not force Overwrite course configuration, because half of the settings come from the uploaded CSV file already. It does not take the course settings from the backup unless you check the Overwrite course configuration option.

When providing a backup to use as a template for uploaded courses, the course settings are not taken. They must be provided by the CSV file through the permitted parameters.

If you are using a course backup file and restore it as a new course, you will find that it restores as you expect it to. If however, you navigate to an existing course and select Restore into this course, it will then use the default settings for the restore. You will find when complete that the existing course has retained its settings (completionprogressonview for instance), and not taken those from the backup.

© Copyright 2024 Totara Learning Solutions. All rights reserved. Some content originally obtained via GPLv3 license and continues to be available under GPLv3. All other content is the sole copyright of Totara Learning Solutions. 


Was this article helpful?

Changing your password will log you out immediately. Use the new password to log back in.
First name must have atleast 2 characters. Numbers and special characters are not allowed.
Last name must have atleast 1 characters. Numbers and special characters are not allowed.
Enter a valid email
Enter a valid password
Your profile has been successfully updated.