Submit a ticket My Tickets
Welcome
Login

Introduction to NexSIS

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:

  1. Your external system exports up to five CSV files: one for users, one for courses, one for enrollments, metalinks, and/or course completions.

  2. You upload the CSV files directly to the web server through secure file transfer protocol (SFTP method) or through the NexSIS Files page.

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


  1. To begin, go to Site Administration, then Plugins, then Enrollments, and then Manage enroll plugins

  2. Find NexSIS in the table of plugins and click the crossed-out eye icon to enable the plugin


Picture of NexSIS settings in Manage enroll plugins menu with crossed-out eye icon circled in orange


  1. Once the plugin is enabled, click the Settings link


Picture of NexSIS settings in Manage enroll plugins menu with Settings link circled in orange


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.


Picture of Bulk user actions menu with example user selected and Download selected from the list of actions and circled in orange



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.


Custom user profile field Common settings Short name with example text filled in and circled in orange


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 must equal the value of the unique identifier selected for the Course ID field setting in the General tab (i.e. shortname or idnumber). 



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


Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.