iSAMS to Moodle Course Enrolment – Part 3

This is the third post about setting up iSAMS and Moodle to perform course and user enrolment synchronisation. Here are links to the other sections:

  1. Prerequisites and Assumptions
  2. Part 1 – Setting up your MSSQL Server
  3. Part 2 – Setting up your Apache / PHP server
  4. Part 3 – Setting up Moodle

Set up Moodle to read our iSAMS Data

So now we have a LAMP server configured ready for Moodle which can also read our MSSQL database with all the course enrolment data we are copying over from iSAMS; it is time to get Moodle configured.

Now we need to set a couple of things up in Moodle. First off we need to create a CRON job for the LDAP Authentication. If all of our users do not exist in Moodle before we synchronise with iSAMS we are going to run into problems!

I will assume you have configured LDAP Authentication already as per the documentation. If you have any errors with this the Moodle Authentication forum should be your first port of call.

We need to ensure that our LDAP authentication settings in Moodle are right for the scheduled job…

  1. Navigate to “Site Administration > Plugins > Authentication > LDAP Server” on your Moodle install
  2. Scroll down to the “Cron synchronisation script” section and set the “Removed ext user” setting to “Suspend internal”. This will ensure that if a user leaves the LDAP database and is ten reintroduced, they get matched up with their old Moodle account and data.
  3. Scroll to the bottom and click “Save changes”

Set up LDAP Import as a scheduled CRON Job

We now need to set up our Moodle server to perform the LDAP import of users at a specific time. To do this you will need to connect to your Moodle server over SSH. We are going to create a bash script to call the LDAP Sync script from Moodle. The benefit of doing it this way is that we can tell the script to save its output to a log file and then handle the log files with the standard log rotates. This way if anything goes wrong we have some log files to interrogate.

  1. Log into your Moodle server via SSH
  2. Elevate yourself to sudo by typing:
    sudo -s
  3. Enter your password when prompted
  4. Change directory to the level above where your Moodle install is:
    cd /var/www/
  5. Make a new directory for your scripts and a new directory for your script logs:
    mkdir ./scripts
    mkdir ./scripts-logs
  6. Create your “ldap-sync-script.sh” in the “scripts” directory:
    nano ./scripts/ldap-sync-script.sh
  7. Enter the following into nano (watch out for line breaks and change the directory names to match you set up!):
    #!/bin/bash
    date >> /var/www/scripts-logs/ldap-sync.log 2>&1
    sudo -u www-data /usr/bin/php /var/www/html/moodle/auth/ldap/cli/sync_users.php >> /var/www/scripts-logs/ldap-sync.log 2>&1
    echo "" >> /var/www/scripts-logs/ldap-sync.log 2>&1
    date >> /var/www/scripts-logs/ldap-sync.log 2>&1
    echo "--------------------------------------------------" >> /var/www/scripts-logs/ldap-sync.log 2>&1
  8. Save and exit Nano by typing “Ctrl + O”, Enter and “Ctrl + X”
  9. Make your script executable:
    chmod +x ./scripts/ldap-sync-script.sh
  10. Run your script:
    ./scripts/ldap-sync-script.sh

    (there should not be any output to the screen)

  11. Check the log file:
    less ./scripts-logs/ldap-sync.log

    If all looks well quit “less” by pressing “q”

  12. Now we are going to add a entry into the crontab for the Root user to run this script at regular intervals:
    crontab -e

    will open up the crontab file for you. If you are prompted to select an editor, do the sane thing and choose Nano!

  13. Enter the following on a new line at the end of your file:
    0 8,13 * * * /var/www/scripts/ldap-sync-script.sh >/dev/null 2>&1 #Moodle LDAP User Sync

    This will run the script at 8am and 1pm every day of the week

  14. Press “Ctrl +O”, Enter and “Ctrl + X” to save and quit Nano

Set up course defaults on your Moodle

We are now going to set up the course defaults in Moodle so our newly created courses are how we want. Teachers can always edit these settings after the courses are created.

  1. On your Moodle install navigate to: “Site Administration > Courses > Course default settings”
  2. The following settings are how I want our courses to default to, but feel free to adjust how you see fit. Any settings not mentioned here I have left to their default setting:
    1. Visible = Hide
    2. Format = Topics Format
    3. Course layout = Show one section per page
    4. Show activity reports = Yes
    5. Completion tracking = Yes
  3. Once you have adjusted your course default settings, click “Save changes” at the bottom of the page

Set up and test our connection between Moodle and our MSSQL Server

Now we have our Moodle server synchronising its LDAP memberships with AD, it is time get it talking to our MSSQL database to retrieve the courses and enrolments from iSAMS.

  1. Navigate to “Site Administration > Plugins > Enrolment > Manage enrol plugins” in your Moodle install
  2. Click the “Settings” link for the “External database” plugin (it will probably be greyed out)
  3. Enter the following settings (leaving all others as default):
    1. Database driver = mssql
    2. Database host = fqdn.your.mssql.server – As defined in step 2.2 in Part 2 of this guide
    3. Database user = Your DB User who has read access to your iSAMS-to-Moodle database
    4. Database password = Password for the above user
    5. Database name = iSAMS-to-Moodle (if you have followed my naming convention)
    6. Use sybase quotes = Yes
    7. Local user field = email
    8. Local role field = id
    9. Remote user enrolment table = VwMoodleEnrolData
    10. Remote course field = txtSetCode
    11. Remote user field = txtEmailAddress
    12. Remote role field = intRoleID
    13. External unenrol action = Disable course enrolment
      This will ensure that if a student leaves a group (or was incorrectly removed due to an error with the course sync from iSAMS) when they rejoin the course all their grades will still be available to them.
    14. Remote new courses table = VwMoodleCourseData
    15. New course full name field = txtFullName
    16. New course short name field = txtShortName
    17. New course ID number field = txtCourseID
    18. New course category field = intCategoryID
    19. Default new course category = (I specified “Unsorted courses” here, which is a category I made in Moodle specifically to hold any courses from the sync operation where the category ID is not found or does not match anything.)
  4. Click “Save changes”
  5. Navigate back to “Site Administration > Plugins > Enrolment > Manage enrol plugins” and click the “Test settings” link for “External database”
  6. All being well, you should see something similar to this: test-external-db-settings
  7. If you do not see this screen go back to your settings and adjust until you do. You can now activate your enrolment plugin!
  8. Click “Continue” to return to the “Manage enrol plugins” page, and click the “closed eye” symbol on the row for “External database”
  9. At this point you should also enable the “Course meta link” plugin. It should be fine to leave all the settings for this as default

Set up External database enrolment as a scheduled CRON Job

Now that we have the settings defined and tested for External database enrolment there are only really four things left to do:

  1. Perform the first run of the synchronisation script and check it works as expected
  2. Create another wrapper script for the Moodle sync script
  3. Set up another CRON job to run this enrolment at regular times
  4. Set up Log Rotate to handle rotating all log files in our scripts-logs directory

At this point I should stress that it would be wise to be carrying these steps out on a test install of your Moodle server. Only do this on your live Moodle once you are sure it is all working as expected!

Perform the first run of the sync script

To first test the sync script we need to connect to your Moodle server via SSH:

  1. Once logged in via SSH, elevate yourself to root:
    sudo -s

    and enter your password when prompted

  2. Move to the external database enrol plugin folder:
    cd /var/www/html/moodle/enrol/database/cli/
  3. Now we need to run the script as the web-server user, passing the “–verbose” option to it so we see all of the output:
    sudo -u www-data /usr/bin/php ./sync.php -v | less
  4. When the script finishes running you should see something like this:
    Starting course synchronisation...
      creating course: 20, Academic Extension - 10/AX1, Academic Extension - 10/AX1, 10/AX1, 6
      creating course: 21, Academic Extension - 10/AX2, Academic Extension - 10/AX2, 10/AX2, 6
      creating course: 22, Academic Extension - 10/AX3, Academic Extension - 10/AX3, 10/AX3, 6
      creating course: 23, Academic Extension - 10/AX4, Academic Extension - 10/AX4, 10/AX4, 6
      creating course: 24, Academic Extension - 11/AX1, Academic Extension - 11/AX1, 11/AX1, 6
      creating course: 25, Academic Extension - 11/AX2, Academic Extension - 11/AX2, 11/AX2, 6
    
    ................................................. 
    
     creating course: 446, Textiles Technology - 9/E/TT, Textiles Technology - 9/E/TT, 9/E/TT, 17
      creating course: 447, Textiles Technology - 9/F/TT, Textiles Technology - 9/F/TT, 9/F/TT, 17
      creating course: 448, Textiles Technology - 9/G/TT, Textiles Technology - 9/G/TT, 9/G/TT, 17
      creating course: 449, Textiles Technology - Staff Area, Textiles Technology - Staff Area, Stf/TextilesTechnology, 17
      creating course: 450, Theatre Studies - 12/B/TH, Theatre Studies - 12/B/TH, 12/B/TH, 18
      creating course: 451, Theatre Studies - 13/B/TH, Theatre Studies - 13/B/TH, 13/B/TH, 18
      creating course: 452, Theatre Studies - Staff Area, Theatre Studies - Staff Area, Stf/TheatreStudies, 18
    ...course synchronisation finished.
    Starting user enrolment synchronisation...
      enrolling: 566 ==> Academic Extension - 10/AX1 as editingteacher
      enrolling: 369 ==> Academic Extension - 10/AX1 as student
      enrolling: 388 ==> Academic Extension - 10/AX1 as student
      enrolling: 392 ==> Academic Extension - 10/AX1 as student
      enrolling: 368 ==> Academic Extension - 10/AX1 as student
      enrolling: 375 ==> Academic Extension - 10/AX1 as student
      enrolling: 389 ==> Academic Extension - 10/AX1 as student
      enrolling: 373 ==> Academic Extension - 10/AX1 as student
      enrolling: 380 ==> Academic Extension - 10/AX1 as student
    .............................................
      enrolling: 570 ==> Textiles Technology - 9/G/TT as editingteacher
      enrolling: 425 ==> Textiles Technology - 9/G/TT as student
      enrolling: 420 ==> Textiles Technology - 9/G/TT as student
      enrolling: 445 ==> Textiles Technology - 9/G/TT as student
      enrolling: 417 ==> Textiles Technology - 9/G/TT as student
      enrolling: 409 ==> Textiles Technology - 9/G/TT as student
      enrolling: 773 ==> Textiles Technology - 9/G/TT as student
      enrolling: 782 ==> Textiles Technology - 9/G/TT as student
      enrolling: 652 ==> Textiles Technology - Staff Area as editingteacher
      enrolling: 570 ==> Textiles Technology - Staff Area as editingteacher
      enrolling: 724 ==> Theatre Studies - 12/B/TH as editingteacher
      enrolling: 236 ==> Theatre Studies - 12/B/TH as student
      enrolling: 234 ==> Theatre Studies - 12/B/TH as student
      enrolling: 200 ==> Theatre Studies - 12/B/TH as student
      enrolling: 261 ==> Theatre Studies - 12/B/TH as student
      enrolling: 571 ==> Theatre Studies - 12/B/TH as editingteacher
      enrolling: 724 ==> Theatre Studies - 13/B/TH as editingteacher
      enrolling: 140 ==> Theatre Studies - 13/B/TH as student
      enrolling: 136 ==> Theatre Studies - 13/B/TH as student
      enrolling: 164 ==> Theatre Studies - 13/B/TH as student
      enrolling: 152 ==> Theatre Studies - 13/B/TH as student
      enrolling: 571 ==> Theatre Studies - 13/B/TH as editingteacher
      enrolling: 724 ==> Theatre Studies - Staff Area as editingteacher
      enrolling: 571 ==> Theatre Studies - Staff Area as editingteacher
    ...user enrolment synchronisation finished.
    

    Press “q” to quit Less

  5. At this point you should find that all of your courses have been created in Moodle and your users enrolled to them. Spend some time checking that they are as expected!

If all is well now we need to set up the regular CRON job to perform this in the background. This enrolment check is also performed at the point of login, so users should get their enrolments matched up very regularly. We are going to make another script like the ldap-sync-script and set up another CRON job for it.

Create the wrapper script

  1. Move to your scripts directory:
    cd /var/www/scripts
  2. Create your database enrolment script:
    nano ./db-enrol-script.sh
  3. Enter the following into your script (watch out for line breaks and change the directory names to match you set up!):
    #!/bin/bash
    date >>  /var/www/scripts-logs/db-enrol.log 2>&1
    sudo -u www-data /usr/bin/php /var/www/html/moodle/enrol/database/cli/sync.php -v >> /var/www/scripts-logs/db-enrol.log 2>&1
    echo "" >> /var/www/scripts-logs/db-enrol.log 2>&1
    echo "Purging all Caches..." >> /var/www/scripts-logs/db-enrol.log 2>&1
    sudo -u www-data /usr/bin/php /var/www/html/moodle/admin/cli/purge_caches.php >> /var/www/scripts-logs/db-enrol.log 2>&1
    echo "" >> /var/www/scripts-logs/db-enrol.log 2>&1
    date >>  /var/www/scripts-logs/db-enrol.log 2>&1
    echo "--------------------------------------------------" >> /var/www/scripts-logs/db-enrol.log 2>&1
  4. Save and exit Nano by pressing “Ctrl + O”, Enter and “Ctrl + X”
  5. Make your script executable:
    chmod +x ./db-enrol-script.sh
  6. Run your script:
    ./db-enrol-script.sh

    (there should not be any output to the screen)

  7. Check the log file:
    less ../scripts-logs/db-enrol.log

    If all looks well quit “less” by pressing “q”

Create the Scheduled CRON Job

  1. Edit Root’s crontab:
    crontab -e
  2. Enter the following to run the script at 3am every morning:
    0 3 * * * /var/www/scripts/db-enrol-script.sh >/dev/null 2>&1 #Moodle External DB Enrol Sync
  3. Press “Ctrl + O”, Enter and “Ctrl + X” to save and exit Nano

Set up Log Rotate to rotate our script logs

We will make use of the already defined Apache Log Rotate settings and just include our new logs directory in those settings.

  1. Move to the Log Rotate directory:
    cd /etc/logrotate.d/
  2. Open the apache2 configuration for editing:
    nano ./apache2
  3. Edit the first line of the configuration file adding “/var/www/scripts-logs/*.log” just before the “{“. My edited file now looks like this:
    /var/log/apache2/*.log /var/www/scripts-logs/*.log {
    weekly
    missingok
    rotate 52
    compress
    delaycompress
    notifempty
    create 640 root adm
    sharedscripts
    postrotate
    if /etc/init.d/apache2 status > /dev/null ; then \
    /etc/init.d/apache2 reload > /dev/null; \
    fi;
    endscript
    prerotate
    if [ -d /etc/logrotate.d/httpd-prerotate ]; then \
    run-parts /etc/logrotate.d/httpd-prerotate; \
    fi; \
    endscript
    }
  4. Press “Ctrl + O”, Enter and “Ctrl + X” to save and exit nano
  5. Type “exit” twice to close your SSH session

Final points

That is now pretty much everything configured. I would suggest now making some changes in a teachers and students course assignments in iSAMS and running the synchronisation on both the Moodle server and your iSAMS DB server to check they work as expected.

One last point is the activation of the “Course meta link enrolment” plug-in. The reason I suggested doing this was in case you have some departments who do not want a Moodle course for every individual class in iSAMS. Using this enrolment plug-in you could create, say a Year 7 Science Moodle course, and then enrol all of the auto-created iSAMS class courses into this new course. That way all enrolments (staff and students) will be bought into this new course, and any changes to the enrolments in iSAMS will still be reflected in the set up. You can read more about the “Course meta link enrolment” plug-in here.

2 thoughts on “iSAMS to Moodle Course Enrolment – Part 3

  1. ****** Update! ******
    A slight edit to the wrapper script for the database enrolment has been made. I have updated it in the blog above already and highlighted the text in red. Please update your scripts to match.

    I found that the teachers on the course list page were not reflecting the teachers enrolled in the courses if they were moved in iSAMS. Whilst they were correctly changing in the course enrolment side of things, the course display page was using cached files from Moodle.

    The edit to the script just calls the CLI version of the Moodle purge_caches script to clear all server caches out after running the database enrolment script.

    With this addition the course display page reflects the teacher movements correctly.

Leave a Reply

Your email address will not be published. Required fields are marked *