Totara 12 will no longer be fully supported from October 2023. Urgently consider upgrading to a later version.

Help documentation for up-to-date versions is available here.

Although it is possible to manually create courses in the system, you may wish to create courses via a file upload, especially if you want to create multiple courses at once. It is possible for Site administrators to do this, as well as anyone with the tool/uploadcourse:uploadcourses capability which by default is the Manager and Course creator roles (when assigned at system level).

Any Managers or Course creators with the right permissions will be able to create courses, they will also be able to delete a course (even if they do not have the capability course:delete set to allow).

Upload courses

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 to select the file in the file picker.
  3. Select appropriate import settings carefully, then click the Preview button.
  4. Check there are no errors in the preview.
  5. Scroll down and configure the course process settings and default course values
  6. When you are happy, click the Upload courses button. 
  7. You will be presented with a confirmation screen where you can click Continue to conclude the upload. 

When using the web interface, use the Preview option to see if any errors were detected in the previewed rows. If you proceed with the upload and there was something wrong detected with a course, it will be ignored.

It is also possible to use the command-line tool admin/tool/uploadcourse/cli/uploadcourse.php.

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 shortnamefullname, and either categorycategory_idnumber, or category_path.

Creating the text file

The text file to upload courses must be a CSV file. It accepts the following columns which are divided in two categories, the course information and the course actions.

Course information fields

Most of these settings are available on the settings page of a course, therefore please refer to Course settings for more information.

You'll notice that some of the settings in the table below 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 lower-case. 

Field name
shortname The short name of the course which must be unique. This field is mandatory.
fullname The full name of the course, this field is mandatory.


The ID number of the course, this must be unique.
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 'Science-Fiction' which is located under the category 'Movies', the value to provide is: Movies / Science-Fiction. Note that the separator must be [space]/[space]. If you want to place the course in the top-level category 'Movies, the value to provide is: Movies.
visibleIf you want the course to be visible, set this as 1 or 0 if you want the course to be hidden.
startdateThe time that the course starts. Please note that this value is passed to the PHP function strtotime to generate a timestamp.
summaryThe summary of the course.
formatThe course format to use, this must be a valid course format plugin name. E.g. weeks, topics.
themeThe theme to use.
lang The language to use.
newsitems The number of news items.
showgradesIf you wish to show the gradebook to learners use 1 or to hide it use 0.
showreports To show the activity report use or to hide is use 0.
legacyfilesTo enable the legacy course files use or to not use these use 0.
maxbytesThe maximum upload size of the course in bytes. Use 0 for the site limit.
groupmode Use the following: 0 for no groups, 1 for separate groups, 2 for visible groups.
groupmodeforceIf you wish to force the group mode use 1, otherwise enter 0.
enablecompletionTo enable the activity completion use 1 or if you do not wish to use this use 0.

Course audience visibility can be set using the following: 0 for only visible to enrolled users, 1 for visible to enrolled users and members of selected audiences (audiences will need to be set manually), 2 for visible to all, and 3 for not visible.


The course type can be set using the following: 0 for e-learning, 1 for blended, and 2 for face to face/seminar.

By default, the value for coursetype is E-learning. This is only for the scenario where the coursetype field is missing from the CSV file or the field is empty.

Enrolment fields

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. 

enrolment_[number]The name of the enrolment method, e.g. manual.
enrolment_[number]_deleteIf you wish to delete this enrolment method from the course use 1. If this field is set to 1 then all the other properties will be ignored.
enrolment_[number]_disableTo disable this enrolment method from the course set this field to 1. If this field is set to 1, all the other properties will be ignored.
enrolment_[number]_startdateThe enrolment start date. This value is passed to the PHP function strtotime().
enrolment_[number]_enddateThe enrolment end date. This value is passed to the PHP function strtotime().
enrolment_[number]_enrolperiodNumber of seconds, or if not a value understood by strtotime() such as '4 days'.
enrolment_[number]_roleThe role short name, e.g. learner.
enrolment_[number]_passwordThe course enrolment key.

So for example you might have:


Where the file is setting enrolment_1 as manual enrolment method and the default role as learner. In this example, enrolment_2 is then 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.

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 to Learner role (role_student) to padawan, the Editing Trainer (role_editingteacher) to master, and the Trainer role (role_teacher) to jedi.

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.

delete To delete the course set this field to 1.
renameThe shortname to rename the course to.
backupfile An absolute path to a backup file (.mbz) to import in the course.
templatecourseThe short name of a course to import the content from.
resetTo reset the course set this field to 1.

Upload settings

The settings below will appear after you click the Preview button, they allow you to configure the desired settings for the course upload. 

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 modeIf you allow courses to be updated, you also have to tell the tool what to update the courses with.-
Allow deletesWhether the delete field is accepted or not.-
Allow renamesWhether the rename field is accepted or not.-
Allow resetsWhether 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. This means the full path to your course, for example /home/yourtotara/public_html/totara27/transfert/backup.mbz. If you are unsure of this, look at include_path in Site administration > Server > PHP info. 

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.

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.

On this page

The Totara Academy has a whole course dedicated to using Courses and categories in Totara Learn. 

Provide feedback about this page using the link in the bottom right of this page. 

Still have questions? Why not post them in the forums of the Totara Community?

  • No labels