Overview
Moodle US has developed a plugin called NexSIS that makes it easy to sync student, course, and enrollment data from an external system to your Moodle site. The external system is commonly a Student Information System (SIS), but it can be any system that can export data in Comma-Separated Value (CSV) format, as NexSIS only accepts CSV files.
Once your SIS is integrated with your Moodle site via the NexSIS plugin, the process of syncing data from one system to the other generally goes through the following process:
Your SIS exports up to four CSV files: one for users, courses, enrollments, metalinks, and/or course completions.
Upload CSV directly to the web server.
Your Moodle site detects the CSV files, updates the site with their content, and archives the file(s).
Note: This process can be entirely automated and set to run at regularly scheduled times. Once you complete the initial configuration of the integration, you can let it run automatically thereafter.
Plugin settings
Before you begin creating CSV files for NexSIS to use, you will need to configure the NexSIS plugin settings on your site.
To begin, go to Site Administration, then Plugins, then Enrollments, and then Manage enroll plugins
Find NexSIS in the table of plugins and click the crossed-out eye icon to enable the plugin
Once the plugin is enabled, click the Settings link
The NexSIS settings page is divided into four tabs: General, API, Files, and Ethos.
This guide will focus on the General and Files tabs.
General settings
The settings configured in the General tab affect the NexSIS plugin sitewide, which means that both API and flatfile integrations will check these settings when running.
Setting | Options | Explanation |
Log level | None, Fatal, Error, Warning, Info, Debug | How much information you want to see in the logs, which are found at Site Administration, then Reports, and then NexSIS logs. Setting this value to Debug will show the maximum available log information every time NexSIS runs. |
Log retention period
| Number of days
| Log retention period in days. The default is 30 days. Enter 0 to disable all log deletion.
|
Archive file retention period
| Number of days
| Archive file retention period in days. The default is 30 days. Enter 0 to disable all archive file deletion.
|
Course ID field | shortname, idnumber | The field NexSIS uses to uniquely identify courses. In Moodle, course shortnames must be unique, but idnumbers do not need to be unique. |
User ID field | idnumber, username, email | The field NexSIS uses to uniquely identify users. In Moodle, usernames must be unique; emails can optionally be unique; idnumbers do not have to be unique. |
Default role | Student (Can't view activity), Student, Parent, Non-editing Teacher, Teacher, Manager | The role that will be assigned to users when processing the enrollments.csv file or using the enrol API endpoint if no explicit role is provided in the roleid column. |
Ignore hidden courses | Yes or No | If set to yes, users will not be enrolled in courses that are hidden (and thus unavailable to students) when the enrollments.csv file is processed or when the enrol API endpoint is used. |
Do not update course name
| Yes or No
| If "Yes", the course full name and course short name will not be updated on the update course process.
|
Default course visibility | Inherit from course category, Hide, Show | The course visibility setting to use when creating new courses from the courses.csv file or the course API endpoint. |
External unenrol action | Unenrol user from course, Keep user enrolled, Disable course enrolment, Disable course enrolment and remove roles | What to do when a user is unenrolled from a course from the enrollments.csv file or the enrol API endpoint. |
User drop action | Keep user (ignore delete action), Suspend user, Full delete user | What to do when a user account is deleted from the users.csv file or the user API endpoint. Suspended users will no longer be able to access the Moodle site but their account and all of its data will still exist. Fully deleted users will lose all site data permanently. |
Unsuspend user on update
| Yes or No
| If a suspended user is updated, should NexSIS automatically unsuspend the user?
|
Control manual enrolments | Yes or No | Normally NexSIS can only unenroll users from courses if those users were initially enrolled with NexSIS. If set to yes, this setting allows NexSIS to unenroll users that were manually enrolled in courses. |
Overwrite roles by default | Yes or No
| By default, when updating an enrollment, NexSIS will delete all existing roles before adding the specified role. Setting this to No will cause NexSIS to append the role instead, maintaining any existing roles when updating an enrollment. |
Email if Error Occurs
| Email address of comma separated list of email addresses
| Added in NexSIS version 1.6.1. If supplied, allows user to receive email alert if a NexSIS issue is logged for level error and above. Supply one email address or comma separated list of email addresses. Each email address must be for a valid moodle user. NexSIS could still fail in ways that do not log and trigger an email alert. |
Files settings
The settings configured in the Files tab affect what NexSIS does every time the Enrollments file processing scheduled task is run. In the Options/Example column of this table, normal font represents the list of available options you can select from and italics font represents an example of text that might be entered in the field. You may replace any of the italics font examples with your own text in order to customize your site's NexSIS plugin.
Setting | Options/Example | Explanation |
Enable flat file integration(s) | Yes or No | Set this to yes in order to enable the "Enrollments file processing" (\enrol_nexsis\task\enrol_sync_task) scheduled task. This must be set to yes for NexSIS to process uploaded files. |
File delimiter | Comma, Tab, Pipe | The field delimiter symbol for the CSV files uploaded to NexSIS. |
Path to files | /mnt/saas-sftp01/home/clientname/incoming | The location on the web server that NexSIS will search for incoming files to be processed. If this field is blank, ask a Moodle US team member to fill it in correctly. |
Path to archive files | /path/to/archive/folder | The location on the web server that NexSIS will save compressed archives of files that have already been processed. If this field is blank, ask a Moodle US team member to fill it in correctly. |
Course | Options/Example | Explanation |
Course filename | courses.csv | The name of the CSV file containing course information NexSIS will search for. This value must exactly match the name of the file you upload to the server. |
Course ID column | courseid | The name of the column in the course CSV file containing the unique identifier for the courses. This column must include the value of the unique identifier selected for the Course ID field setting in the General tab (i.e. shortname or idnumber). |
Action column | action | The name of the column in the course CSV file containing the action directive that should be performed on each row. Values for this column must be selected from the available actions in the following Add actions and Drop actions fields. |
Add actions | add, create, update | The available values that can be supplied in the action column to perform the Add action. Note that no matter which value from the list is supplied, the result is the same: if the course does not exist, it will be created; if the course already exists, it will be updated to match this row in the CSV file. |
Drop actions | drop, remove, delete | The available values that can be supplied in the action column to perform the Drop action. Note that no matter which value from the list is supplied, the result is the same: if the course exists, it will be deleted. |
User File | Options/Example | Explanation |
User filename | users.csv | The name of the CSV file containing user information NexSIS will search for. This value must exactly match the name of the file you upload to the server. |
User ID column | userid | The name of the column in the user CSV file containing the unique identifier for the user. This column must include the value of the unique identifier selected for the User ID field setting in the General tab (i.e. idnumber, username, or email). |
Action column | action | The name of the column in the user CSV file containing the action directive that should be performed on each row. Values for this column must be selected from the available actions in the following Add actions and Drop actions fields. |
Add actions | add, create, update | The available values that can be supplied in the action column to perform the Add action. Note that no matter which value from the list is supplied, the result is the same: if the user does not exist, it will be created; if the user already exists, it will be updated to match this row in the CSV file. |
Drop actions | drop, remove, delete, suspend | The available values that can be supplied in the action column to perform the Drop action. Note that no matter which value from the list is supplied, the result is the same: if the user exists, the User drop action from the General tab will be performed. |
Enrollment File | Options/Example | Explanation |
Enrollment filename | enrollments.csv | The name of the CSV file containing enrollment information NexSIS will search for. This value must exactly match the name of the file you upload to the server. |
Enable Implicit Drops | Yes or No | If enabled, all existing enrollments in the Moodle site that do not appear in the enrollments CSV file will be automatically removed. If disabled, NexSIS will only unenroll users when it encounters a row in the CSV file with a valid Drop action. |
User ID column | userid | The name of the column in the enrollment CSV file containing the unique identifier for the users. This column must include the value of the unique identifier selected for the User ID field setting in the General tab (i.e. idnumber, username, or email). |
Course ID column | courseid | The name of the column in the enrollment CSV file containing the unique identifier for the courses. This column must include the value of the unique identifier selected for the Course ID field setting in the General tab (i.e. shortname or idnumber). |
Role column | role | The name of the column in the enrollment CSV file containing the shortname for the role to be assigned to the user upon enrollment. If this column is missing or blank, the Default role setting from the General tab will be applied. |
Action column | action | The name of the column in the enrollment CSV file containing the action directive that should be performed on each row. Values for this column must be selected from the available actions in the following Add actions and Drop actions fields. |
Add actions | add, enrol, enroll | The available values that can be supplied in the action column to perform the Add action. Note that no matter which value from the list is supplied, the result is the same: if the enrollment does not exist, it will be created; if the enrollment already exists, it will be updated to match this row in the CSV file. |
Drop actions | drop, remove, unenrol, unenroll | The available values that can be supplied in the action column to perform the Drop action. Note that no matter which value from the list is supplied, the result is the same: if the enrollment exists, the External unenrol action from the General tab will be performed. |
CSV file specifications
Before you send your CSV files to Moodle US's server, you'll need to make sure the files are in the proper format. Each of the three types of file has a certain set of required fields that must be included as well as optional fields that may be included, as per the NexSIS plugin settings above. The order of the fields does not matter. Each file must contain exactly one header row that lists the column headings.
User file
The default name for this file is "users.csv". Every row in the file defines a single user. The columns for the users.csv file are:
Column | Required? | Description |
action | Yes | The action to be performed on the user record, e.g. add or delete. |
userid | Yes | The external system identifier for the user to create, update, or delete. |
username | Yes | The Moodle username for the user. |
firstname | Yes | The user's first name. |
lastname | Yes | The user's last name. |
email | Yes | The user's email address. |
auth | No | The user's authentication method. The value for this column should match the name of the proper authentication plugin without a plugin prefix. For example, to specify that a user should authenticate via the Simple SAML plugin (named auth_simplesaml), set this value to simplesaml. |
lang | No | The default language for the user. Use the name for the language pack found at Site Administration, then Language, and then Language packs (e.g. en_us). |
password | No | The user's password. |
url | No | The user's Web page profile field. |
institution | No | The user's Institution profile field. |
department | No | The user's Department profile field. |
address | No | The user's Address profile field. |
city | No | The user's City profile field. |
country | No | The user's Country profile field. |
icq | No | The user's ICQ profile field. |
skype | No | The user's Skype profile field. |
yahoo | No | The user's Yahoo profile field. |
aim | No | The user's AIM profile field. |
msn | No | The user's MSN profile field. |
phone1 | No | The user's Phone profile field. |
phone2 | No | The user's Mobile phone profile field. |
policyagreed | No | Whether the user has agreed to the site policy. This value should be either true or false. |
suspended | No | Whether the user is suspended from the site (meaning they cannot login). This value should either be 0 for not suspended or 1 for suspended. |
middlename | No | The user's Middle name profile field. |
alternatename | No | The user's Alternate name profile field. |
tenant
| No | Moodle Workplace only, tool_tenant plugin required. Specify the Tenant ID of the tenant to allocate the user to.
|
One additional field you can include allows you to force users to change their passwords upon first login:
Column | Description |
changepassword | If set to 1, the user will be forced to change their password when they login for the first time. |
To determine the appropriate names to use for the column headings in the CSV file, you can download a CSV file with the correct headings for all fields in a user's profile by going to Site Administration, then Users, and then Bulk user actions, selecting at least one user, and choosing Download from the list of user actions.
It is possible to include custom user profile fields in your CSV files and update the values of those fields as well as the values of the default profile fields. In order to include custom user profile fields in the CSV, you will need to know the shortname value of the field. This is a unique identifier for the field, and it was determined when the profile field was created. To find this value, go to Site Administration, then Users, then Accounts, and then User profile fields, find the field in the list, click the gear icon in that field's row to go to its edit page, and you will see the Short name as the very first field on the page.
Once you have identified the custom profile field's shortname, you can include the field in your CSV files by creating a column named profile_field_shortname where “shortname” is the shortname value for the field. For example, in order to include the Fanciness level custom profile field from the screenshot above, you would need to create a column in the CSV file titled profile_field_fancy.
A sample users.csv file might look like this:
action,userid,username,firstname,lastname,email,auth
add,STU3141,samsmith,Sam,Smith,sam.smith@somewhere.com,ldap
delete,STU3176,sallysitwell,Sally,Sitwell,sally.sitwell@somewhere.com,ldap
...
Course file
The default name for this file is “courses.csv”. Every row defines a single course. The available columns for courses.csv are:
Column | Required? | Description |
action | Yes | Action to perform on the course record, e.g. add or delete. |
courseid | Yes | The external system identifier for the course to create, update, or delete. |
fullname | Yes | The full name of the course. |
shortname | Yes | The shortened or abbreviated name for the course. |
startdate | No | The start date and time of the course (in datetime format). |
enddate | No | The end date and time of the course (in datetime format). |
category | No | The category id number for the category the course belongs to. Use either this field or the categorypath field to specify the categorization of the course. |
categorypath | No | Where this course belongs in the category hierarchy (in uniform resource identifier or URI format). Use the full name of each course category, including spaces; if the course category does not already exist, it will be created. |
format | No | Moodle course format to use for the course. |
visible | No | Whether the course is visible or hidden. Enter 1 for visible and 0 for hidden. |
templateid | No | The identifier of a course template or shell to use when creating the course for the first time in Moodle. |
A sample courses.csv file might look like this:
action,courseid,fullname,shortname,startdate,categorypath
add,C554,Introduction to Psychology,PSYC101-01,2020-08-20T21:00:00:00,/Psychology
delete,C802,Artificial Intelligence II,COMP304-01,2020-08-20T21:00:00:00,/CompSci/Machine Learning
...
Enrollment file
This file must be titled “enrolments.csv”. Each row of the file defines a single user enrollment for a single course. The available columns for the enrolments.csv file are:
Column | Required? | Description |
action | Yes | Action to perform on the enrollment method, e.g. enrol or unenrol. |
courseid | Yes | The external system identifier for the course to be enrolled in or unenrolled from. |
userid | Yes | The external system identifier for the user to be enrolled or unenrolled. |
roleid | Yes | The shortname of the role to be assigned to the user, e.g. student or teacher. |
groupname | No | The identifier of the group the user should be assigned to. If the group doesn't already exist, it will be created. |
timestart | No | The start date and time for the enrollment to take effect (in datetime format). |
timeend | No | The end date and time for the enrollment to take effect (in datetime format). |
A sample enrolments.csv file might look like this:
action,courseid,userid,roleid,timestart,timeend
enrol,C554,STU3141,student,,
unenrol,C802,STU3176,teacher,,
enrol,C557,STU3275,student,2023-01-01T00:00:00,2023-09-01T00:00:00
…
Metalink file
This functionality is available starting in version 1.5.0 of NexSIS. The course meta link plugin must be enabled. Course meta links make it possible for users enrolled in one course to be automatically enrolled in one or more other courses. The default name for this file is “metalinks.csv”. Every row defines a single course meta link. The available columns for metalinks.csv are:
Column | Required? | Description |
parent_courseid | Yes | Parent course identifier |
metalink_courseid | Yes | Metalink course identifier |
action | Yes | Action to perform on the course meta link record, e.g. add or delete. |
group | No | Specify "none" for no groups, "new" to create a new group, or an existing Group ID Number to add to an existing group. |
groupname | No | For creating "new" groups only, specified by "new" value in the group column, specify the group name for the newly created group. |
groupid | No | For creating "new" groups only, specified by "new" value in the group column, specify the group id for the newly created group.
|
A sample metalinks.csv file might look like this:
parent_courseid,metalink_courseid,action,group,groupname,groupid
Math1,Math2,add,new,Math Students,M1
Math1,Math3,add,M1,,
Science1,History1,add,none,,
Science1,Science2,delete,,,
…
Course Completion File
This functionality is available starting in version 1.5.0 of NexSIS. This file allows you to add course completion timestamp for a user in a course, if a course completion timestamp does not already exist for the user in the course. The default name for this file is “course_completions.csv”. The available columns for course_completions.csv are:
Column | Required? | Description |
timestamp_course_completion | Yes | Course Completion Timestamp |
userid | Yes | The external system identifier for the user that will have a course completion added.
|
courseid | Yes | The external system identifier for the course the user is enrolled in that will have a course completion added. |
A sample course_completions.csv file might look like this:
timestamp_course_completion,userid,courseid
2022-11-01T08:00:00.000Z,STU3141,C554
2022-11-05T09:30:00.000Z,STU1546,C551
...
File transfer
Once you have produced CSV files in the correct format, you'll need to transfer them to Moodle US's server. You'll need to transfer the files via the secure file transfer protocol (SFTP method) using the credentials provided to you by Moodle US.
You will be given a directory to transfer your users.csv, courses.csv, and enrolments.csv files to. It is recommended that you create a scheduled task (using cron or a similar scheduling program) that sends the exported files from your SIS to Moodle US's SFTP server at regular intervals.
Once you have transferred the files to Moodle US's server, the NexSIS plugin completes the actions noted on the CSV files. In order to see notifications or error messages that arise while NexSIS imports the data to the Moodle site, you can go to Site Administration, then Reports, and then NexSIS logs. Please note that if you see an error that NexSIS has failed to import one of the files, NexSIS will simply retry importing the file next time it runs.
NexSIS API
If you’d like to learn more about the NexSIS API, you can read about that here:
http://assets.moonami.com.s3.amazonaws.com/nexsis-api-docs/index.html#nexsis-api-introduction
