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:
- Go to Site administration > Courses > Upload courses.
- Either drag and drop the CSV file, or click the Choose a file button to select the file in the file picker.
- Select appropriate import settings carefully, then click the Preview button.
- Check there are no errors in the preview.
- Scroll down and configure the course process settings and default course values.
- When you are happy, click the Upload courses button.
- 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.
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.
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 | Description |
|---|---|
| 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. |
idnumber | 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. |
| visible | If you want the course to be visible, set this as 1 or 0 if you want the course to be hidden. |
| startdate | The time that the course starts. Please note that this value is passed to the PHP function strtotime to generate a timestamp. |
| summary | The summary of the course. |
| format | The course format to use, this must be a valid course format plugin name. E.g. weeks, topics. |
| theme | The theme to use. |
| lang | The language to use. |
| newsitems | The number of news items. |
| showgrades | If you wish to show the gradebook to learners use 1 or to hide it use 0. |
| showreports | To show the activity report use 1 or to hide is use 0. |
| legacyfiles | To enable the legacy course files use 1 or to not use these use 0. |
| maxbytes | The 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. |
| groupmodeforce | If you wish to force the group mode use 1, otherwise enter 0. |
| enablecompletion | To enable the activity completion use 1 or if you do not wish to use this use 0. |
| audiencevisible | 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. |
| coursetype | 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.
Field | Description |
|---|---|
| enrolment_[number] | The name of the enrolment method, e.g. manual. |
| enrolment_[number]_delete | If 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]_disable | To 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]_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, e.g. learner. |
| enrolment_[number]_password | The course enrolment key. |
So for example you might have:
enrolment_1,enrolment_1_role,enrolment_2,enrolement_2_startdate
manual,learner,self,20170629
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:
shortname,fullname,category,enrolment_1,enrolment_1_role,enrolment_2,enrolement_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.
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 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.
Field | Description |
|---|---|
| delete | To delete the course set this field to 1. |
| rename | The shortname to rename the course to. |
| backupfile | An absolute path to a backup file (.mbz) to import in the course. |
| templatecourse | The short name of a course to import the content from. |
| reset | To 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.
Setting | Description | Notes |
|---|---|---|
| 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.
Setting | Description | Notes |
|---|---|---|
| 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.
The Totara Academy has a whole course dedicated to using Courses and categories in Totara Learn.
