Skip to main content

Upgrading to v20

Important information regarding the upgrade to Level Up XP and Level Up XP+ 20. For more information about the release itself, please refer to the release notes instead.

Log migration​

A new log table was introduced in XP 20 which requires the data from previous log tables to be migrated.

info

The migration of logs is important to prevent situations where previously earned points could be earned again, and to prevent the complete disappearance of any log from the user interface.

What is migrated?​

Log entries are migrated from:

  • block_xp_log to block_xp_logs.
  • local_xp_log to block_xp_logs (for XP+)

The records are not deleted from their original tables, they are copied to the new table.

Default behaviour (automatic migration)​

By default, migration is automatically enabled and run by an ad-hoc task that:

  1. Runs in batches.
  2. Stops when configured limits are reached.
  3. Re-schedules itself for a later run when there is still work to do.

This allows large sites to progressively migrate data over multiple runs.

Migration settings​

info

To avoid any unexpected behaviour, always set the migration settings before upgrading your Moodle site.

The configuration settings are:

  • logmigrationenabled: Whether automatic migration is enabled, defaults to true.
  • logmigrationruninterval: Delay in seconds betweeh runs of the adhoc task, defaults to 60s.
  • logmigrationbatchsize: Number of records inserted per batch, defaults to 5,000.
  • logmigrationmaxitems: Maximum number of records migrated per run, defaults to 100,000.
  • logmigrationmaxruntime: Maximum runtime per run in seconds, defaults to 10 minutes.

You can override the migration settings in your config.php file, example:

$CFG->forced_plugin_settings = [
  'block_xp' => [
    'logmigrationruntinterval' => 5 * 60, // Re-schedules every 5 minutes.
    'logmigrationmaxruntime' => 5 * 60, // Runs for up to 5 minutes.
  ],
];

Disable automatic migration​

To disable automatic migration, set this before upgrading your Moodle site:

$CFG->forced_plugin_settings = [
  'block_xp' => [
    'logmigrationenabled' => 0,
  ],
];

When disabled, automatic task-based migration will not run. The migration will have to be run manually from CLI.

warning

If you disable automatic migration and XP+ is not upgraded at the same time as XP, the migration will have to be run again when XP+ is upgraded.

Run migration manually from CLI​

Use the CLI script:

php [public/]blocks/xp/cli/migrate_logs.php

By default, it runs in check-only mode and reports pending migrations.

To execute migration:

php [public/]blocks/xp/cli/migrate_logs.php --execute

To change batch size:

php [public/]blocks/xp/cli/migrate_logs.php --execute --batchsize=10000
info

It is safe to run the script multiple times, only records that have not been migrated yet will be processed.

Action rules and event rules coexisting​

XP 20 introduces action rules, the new preferred way to award points for learner activity. As part of this upgrade, XP automatically replaces the default event rules with equivalent action rule defaults on sites where the defaults were not customised.

If your site has customised the default event rules at the admin level, this automatic migration does not apply. In that case, new courses will have both your custom event rules and the new action rule defaults active at the same time, which may result in points being awarded from both.

If this applies to your site, we recommend reviewing the situation and taking one of the following approaches:

  • Keep using event rules: if you want to continue with your existing event rules, remove the action rule defaults in the admin settings so they are not added to new courses.
  • Migrate to action rules: if you prefer to switch to action rules, clear your custom default event rules at the admin level so that new courses only use action rules going forward. You may also want to remove event rules from existing courses.

Note that using both event rules and action rules at the same time is perfectly valid. Just be mindful that both can award points for the same learner actions, so it is worth checking that the combination behaves as intended.