Creating course upload files
  • 07 Jun 2024
  • 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.

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


The course full name.


The course short name.


The course ID number.


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


The idnumber of the category to add the course to.


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'.


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


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.


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


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


The course summary.


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


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


The default language for the course.


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


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


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


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


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


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


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


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


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.


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


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

Course action fields

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


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


Provide the new shortname you want to give to the course. Note that the Allow renames setting must be enabled in the Import options settings.


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


The shortname of a course to import content from.


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

Renaming courses

One way to use the course upload feature is to rename courses in bulk. You can update the shortname for all courses included in the CSV file by including the new names in the rename field.

Your CSV file would look similar to this:

original-shortname,System Course 1,1,updated-shortname

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:


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


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

Course format options

Field nameDescription


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


For the demo, topics, weeks formats only.


For the demo, topics, weeks formats only.


For the social format only.


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


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:


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:

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.