Overview
The connection between an external system (like a Student Information System (SIS), a Human Resource Information System (HRIS), or a Customer Relationship Management system (CRM)) and Moodle is one of integration and data exchange. This integration enhances efficiency, accuracy, and the overall user experience by ensuring that data is consistent and up-to-date across both systems while minimizing manual administrative tasks.
External systems like the SIS, a HRIS or a CRM are comprehensive databases that store and manage user-related data, including personal information, enrollment records, grades/ performance records, attendance, job history and more. These systems serve as the central repository for information pertinent to the student or employee.
For clients using a SIS/ HRIS/ CRM and Moodle, there is often a desire for the systems to sync and work together in a seamless and effortless manner and for this integration they choose NexSIS.
Moodle US has developed NexSIS in order to make it easy to sync student/teacher, employee/ manager, course, and enrollment data from an external system to your Moodle site. The external system is commonly a Student Information System (SIS), but it could be any system that can export data in Comma-Separated Value (CSV) format, as NexSIS only accepts CSV files.
Once your external system 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 steps:
Your external system exports up to five CSV files: one for users, one for courses, one for enrollments, metalinks, and/or course completions.
You upload the CSV files directly to the web server through secure file transfer protocol (SFTP method) or through the NexSIS Files page.
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.
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. If you need help with the API tab, please see the API specific documentation.
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 when navigating to Site Administration > Reports > 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.
Note: if you are processing very large files it is not recommended that you set log retention period to 0 due to the large amount of data that would retain. |
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 | This is the field in your file that NexSIS uses to uniquely identify courses (i.e. are you identifying courses to sync to Moodle by ID number or shortname?
Note: In Moodle, course shortnames must be unique, but idnumbers do not need to be unique.
Note: If your idnumber field is not unique, please consider using shortname. |
User ID field | idnumber, username, email | This is the field in your file that NexSIS uses to uniquely identify users.
Note: In Moodle, usernames must be unique; emails can optionally be unique; idnumbers do not have to be unique.
Note: If your idnumber field is not unique, please consider using username. |
Default role | Student, Parent, Non-editing Teacher, Teacher, Manager | The role that will be assigned to users when processing the enrollments.csv file or using the enroll API endpoint if no explicit role is provided in the roleid column.
Note: the menu of options displayed to you in your Moodle site will show all roles that have ‘course’ as a context in which they can be assigned. |
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 enroll 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 unenroll action | Unenroll 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 enroll API endpoint. |
User drop action | Keep user (ignore delete action), Suspend user, Full delete user | What to do when a user is marked as dropped or deleted in the users.csv file. 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. However, if you set this to ‘Yes’ then NexSIS can 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
| Supply one email address or a comma separated list of email addresses
| If supplied, allows a user or users to receive an 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.
Note: Added in NexSIS version 1.6.1. |
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. Italicized items represent an example of text that might be entered in the field. You may replace any of the italicized 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 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 Infrastructure team member to fill it in correctly. |
Path to archive files | /path/to/archive/folder | The location on the web server, typically set to a file location within the SFTP directory, that NexSIS will save compressed archives of files that have already been processed.
If this field is blank, ask a Moodle US Infrastructure 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.
Note: 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 equal the value of the unique identifier selected for the Course ID field setting in the General tab (i.e. shortname or idnumber). |
Action column | Add, create, update | 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: 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.
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 equal 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.
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.
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 equal 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 equal 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.
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.
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 or upload them through the NexSIS Files page, you'll need to make sure the files are in the proper format. Each of the five 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 described in the table below.
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. |
You can also force users to change their passwords upon first login by adding the following additional field.
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. This should be the system ID, which can be referenced in the URL for the category. 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. This must be a valid course format plugin name. (i.e. weeks, topics) |
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. This value should be the short name of the course. |
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 default name for this file is “enrollments.csv”. Each row of the file defines a single user enrollment for a single course. The available columns for this file are:
Column | Required? | Description |
action | Yes | Action to perform on the enrollment method (e.g. enroll or unenroll)
|
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 enrollments.csv file might look like this:
action,courseid,userid,roleid,timestart,timeend
enroll,C554,STU3141,student,,
unenroll,C802,STU3176,teacher,,
enroll,C557,STU3275,student,2023-01-01T00:00:00,2023-09-01T00:00:00
…
Metalink file
Note: The course meta link plugin (enrol_meta) must be installed and enabled as a valid enrollment method. 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 file allows you to add a 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”. This functionality is available starting in version 1.6.0 of NexSIS. The available columns for course_completions.csv are listed below.
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. This can be done through secure file transfer protocol (SFTP method) or through using the NexSIS Files page to upload your files. To transfer the files via secure file transfer protocol (SFTP method) you will need credentials provided to you by Moodle US.
You will be given a directory where you can transfer your csv files. 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. You should keep the frequency of the scheduled task in mind - you do not want to have a situation where your task runs too frequently for the processing of the file which results in overwritten CSVs.
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 Files Page
This page is available starting in NexSIS 1.6.5. This page can be found by navigating to Site administration, then Plugins, and then NexSIS Files. This page can be used as a File transfer method for uploading files to Moodle US's server. It can be used in addition to or as an alternative to secure file transfer protocol (SFTP). This page also shows the status of existing files in your file directory.
After the files have been uploaded, NexSIS processes and archives the files during its next scheduled sync. 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:
https://supportus.moodle.com/support/solutions/articles/80001029823-nexsis-api
