Course tokens plugin

This plugin lets you make single-use tokens for courses. Then anybody can use these tokens to create an account on your Moodle instance (if they don't already have one) and enroll in the course.

Status

This plugin is used in a preproduction installation.

Remaining issues before public 1.0.0 release are in Issue #49.

Supported Moodle versions:

Features

✋ ​Admin can generate tokens for course enrollment.

Only administrators have access to this page, where they can manually generate tokens for course enrollment. This allows for customized enrollment management within the system.

Secure API for automated course token creation

Course tokens can be generated securely via an API, which requires a valid secret key for authentication. This ensures that only authorized users can create tokens. By using a unique secret key, we protect the process from unauthorized access, making this solution more secure than traditional methods. This approach ensures both flexibility and enhanced security for administrators when managing token creation programmatically.

Required parameters:

1. secret_key: string (Here is how to generate one)
2. course_id: integer (The ID of the course for which tokens are being created.)
3. email: string (Email address of the user)
4. quantity: integer (Number of tokens)
5. firstname: string (First name of the user)
6. lastname: string (Last name of the user)

Optional parameters:

1. extra_json: JSON object (Additional data related to the token creation. Stored as a JSON string.)
2. group_account: string (Specifies the group or corporate account associated with the token.)

cURL example ith optional parameters (group_account and extra_json):

curl 'https://learn.pacificmedicaltraining.com/enrol/course_tokens/api-do-create-token.php' \
  --header "Content-Type: application/json" \
  --data-raw '{
    "secret_key": "secret_key",
    "course_id": 5,
    "email": "minicurl@example.com",
    "quantity": 1,
    "firstname": "John",
    "lastname": "Doe",
    "group_account": "Corporate Inc",
    "extra_json": {
      "department": "Sales",
      "reference_code": "ABC123",
      "notes": "Priority client"
    }
  }'

cURL example without the optional parameters (i.e., group_account and extra_json):

curl 'https://learn.pacificmedicaltraining.com/enrol/course_tokens/api-do-create-token.php' \
  --header "Content-Type: application/json" \
  --data-raw '{
    "secret_key": "secret_key",
    "course_id": 5,
    "email": "minicurl@example.com",
    "quantity": 1,
    "firstname": "John",
    "lastname": "Doe",
    "group_account": "",
    "extra_json": null
  }'

How to generate a secret key

Follow these steps to generate a secure secret_key for your plugin:

1. Create a file named key.php in the course_tokens directory.
2. Add the following code to key.php:

<?php
require_once('/var/www/vhosts/moodle/config.php');
require_login();
require_capability('moodle/site:config', context_system::instance());

// Set the secret key for the plugin
$plugin_name = 'course_token'; // Replace with your plugin's name
$secret_key = bin2hex(random_bytes(16)); // Generate a secure random key
set_config('secretkey', $secret_key, $plugin_name);

echo "Secret key for plugin '{$plugin_name}' has been set to: {$secret_key}";

3. Run the key.php file by accessing it in your browser or command line.

Example:

https://yourmoodlesite.com/enrol/course_tokens/key.php

4. The secret_key will be displayed on your screen. Save it securely, as it will be required for all API requests.

View tokens

The view_tokens.php page allows users to view and manage their course enrollment tokens. Users can see detailed information about each token, including its status, associated course, and usage details. For tokens marked as "Available," users can either enroll themselves in the course or enroll someone else using a simple form. The page dynamically updates token statuses, such as "In-progress," "Completed," or "Failed," based on course activity and exam results. This interface ensures a streamlined and user-friendly experience for managing course enrollments.

Tokens dashboard page

The file dashboard.php displays a user-friendly dashboard summarizing the availability and status of course tokens for the logged-in user. It fetches token data, groups it by course, and categorizes them into statuses such as "Available," "Assigned," "In-progress," "Completed," and "Failed." Users can assign tokens to themselves or others through modals with a simple form, and the status updates dynamically. The page uses AJAX for smooth token assignment and displays detailed course and token information in a structured, Bootstrap-styled table.

Users can view the "Token dashboard" on their dashboard page

This plugin allows users to add a Moodle block to their page that mirrors the functionality of the dashboard.php file. To create the block, simply run the following command after installing the plugin:

ln -s /enrol/course_tokens/block /blocks/

This will generate a "Course Tokens" block with the same features and information as the original dashboard page.

⚙️ Site administration page

Enable course tokens as an enrollment method by navigating to Site administration > Plugins > Enrol plugins > Course Tokens.

Quick start playground

🏃 Run a Moodle playground site with Course tokens on your own computer in under 5 minutes! Zero programming or Moodle experience required.

These instructions include code snippets that you will need to copy/paste into your command terminal. On macOS that would be Terminal.app, which is a software you already have installed.

1. Install a Docker system:

   1. On macOS we currently recommend OrbStack. This is the only software which can install Moodle in under 5 minutes. We would prefer if an open source product can provide this experince, but none such exists. See references below if you may prefer another option.
   2. On Windows (TODO: add open source recommendation)
   3. On Linux (TODO: add open source recommendation)

2. Create a Moodle testing folder. You will use this to test this plugin, but you could also mix in other plugins onto the same system if you like.

   cd ~/Developer
   mkdir moodle-playground && cd moodle-playground

3. Install the latest version of Moodle:

   # Visit https://moodledev.io/general/releases to find the latest release, like X.Y.
   
   export BRANCH=MOODLE_X0Y_STABLE # update X and Y here to match the latest release version
   git clone --depth=1 --branch $BRANCH git://git.moodle.org/moodle.git

   ℹ️ If you see the error "fatal: Remote branch MOODLE_X0Y_STABLE not found in upstream origin", please reread instruction in the code comment and try again.

   These instructions include a workaround for Moodle issue MDL-83812.

4. Install the Course tokens plugin into your Moodle playground:

   git clone https://github.com/fulldecent/moodle-enrol_course_tokens.git moodle/enrol/course_tokens

5. Get and run Moodle Docker container (instructions adapted from moodle-docker instructions):

   git clone https://github.com/moodlehq/moodle-docker.git
   cd moodle-docker # You are now at ~/Developer/moodle-playground/moodle-docker
   
   export MOODLE_DOCKER_WWWROOT=../moodle
   export MOODLE_DOCKER_DB=pgsql
   bin/moodle-docker-compose up -d
   bin/moodle-docker-wait-for-db
   
   cp config.docker-template.php $MOODLE_DOCKER_WWWROOT/config.php
   bin/moodle-docker-compose exec webserver php admin/cli/install_database.php --agree-license --fullname="Docker moodle" --shortname="docker_moodle" --summary="Docker moodle site" --adminpass="test" --adminemail="admin@example.com" --adminuser='admin'

   ℹ️ If you see the error "Database tables already present; CLI installation cannot continue", please follow the "teardown" instructions below and then try again.

   ℹ️ If you see the error "!!! Site is being upgraded, please retry later. !!!", and "Error code: upgraderunning…", please ignore the error and proceed.

   These instructions include a workaround for moodle-docker issue #307.

6. 🌞 Now play with your server at http://localhost:8000

   1. Click the top-right to login.
   2. Your username is admin and your password is test.

   ℹ️ If you see a bunch of stuff and "Update Moodle database now", then click that button and wait. On a M1 Mac with 8GB ram, we saw this take 5 minutes for the page to finish loading.

7. To completely kill your playground so that next time you will start with a blank slate:

   bin/moodle-docker-compose down --volumes --remove-orphans
   colima stop

If you have any further questions about the playground setup, customizing it or other error messages, please see moodle-docker documentation and contact that team.

Install

Install the Course tokens on your quality assurance or production server the same way as on the playground:

1. git clone https://github.com/fulldecent/moodle-enrol_course_tokens.git enrol/course_tokens

2. Load your website in the browser to set up plugins.

Updating JavaScript

You only need these instructions if you contribute changes to this Course toknes plugin, specifically the functionality in JavaScript.

This project uses asynchronous module definition (AMD) to compile JavaScript. This improves performance of modules and is a best practice for Moodle modules [CITATION NEEDED].

1. Install Node (we recommend using nvm)

   1. See the required version in your package.json file:

      cd ~/Developer/moodle-playground/moodle/enrol/course_tokens
      cat ../../package.json | grep '"node"'

2. Install a Node package manager (we recommend Yarn Berry).

   corepack enable
   

3. Install packages

   yarn install

4. Run the Grunt script to rebuild the AMD module

   yarn exec grunt amd

The end result is that your files in amd/build will be updated, assuming you have made changes to your files in amd/source.

Do commit these built artifacts in your repository (do not gitignore the amd/build directory). Yes, this is a violation of DRY principle. This is called "production mode" and it is a documented best practice for Moodle modules [CITATION NEEDED].

Contributing

Please send PRs to our main branch.

References

1. This module is built based on best practices documented in moodle-local_plugin_template.
2. Setting up Docker
   1. We would prefer an open-source-licensed Docker implementation that runs at native speed on Mac, Linux and Windows. For Mac, you may prefer to install Colima which is open source but about 5x slower than the OrbStack recommended above.
3. Setting up playground
   1. If you require a few courses and users to test your plugin, you may want to look at the generator tool.
4. Continuous integration
   1. This plugin uses the Moodle CI suite recommended by Catalyst
   2. Perhaps we would prefer the CI suite provided by Moodle, but their approach does not allow you to set it once and forget it.
   3. If you face issues with CI during the build, refer to the Catalyst README for troubleshooting tips.
5. JavaScript modules in Moodle. For best practices on how to use JavaScript modules in Moodle, including the use of AMD for asynchronous loading, check the Moodle JavaScript Modules Documentation. We recommend including the amd/build folder in your repo with your build files. This is not DRY, it is "production mode". Examples of other Moodle modules recommending this best practice are h5p plugin, attendance plugin.