Submit a ticket My Tickets
Welcome
Login

Introduction to NexSIS

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:

  1. Your SIS exports up to three CSV files: one for users, courses, and/or enrollments.

  2. Upload CSV directly to the web server

  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 and put it out of your mind.


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

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

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.

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.

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.

 

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.

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 actionsselecting 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 shortname 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,samsmucker,Sam,Smucker,sam.smucker@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

enrol,C554,STU3141,student

unenrol,C802,STU3176,teacher

...

 

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 logsPlease 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



Did you find it helpful? Yes No

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