Totara flavours

Introduction

Flavours are a way to define a set of features and settings. Flavours can set defaults and also enforce settings so that they cannot be changed in the interface anymore.

For a flavour to take effect it needs to be activated (either via a config flag in the config.php or via a CLI script) and enforced. Enforcing a flavour can be done via a CLI script or in the Features overview by an admin.

There can only be one flavour active at a time.

How to define flavours

Each flavour has its own subplugin within the totara_flavour plugin.

Definition

The flavour needs to implement its own definition class and can override different methods to customise the settings and behaviour.

namespace flavour_example;

defined('MOODLE_INTERNAL') || die();

/**
 * This is the definition file for an example flavour.
 *
 * This flavour allows for everything, but doesn't necessarily turn everything on.
 *
 * @package flavour_example
 */
class definition extends \totara_flavour\definition {

    /**
     * This is the minimum you need to override.
     *
     * @return string
     */
    public function get_component() {
        return 'flavour_example';
    }

}

Default settings

You can override the load_default_settings() method to provide defaults which will override the existing site default settings.

/**
 * Returns an array of setting defaults that differ for this flavour.
 *
 * This method is using the same format as /local/defaults.php
 * described in /local/readme.txt file.
 *
 * NOTE: NULL value means ask user during installation or upgrade.
 *
 * @return array[]
 */
protected function load_default_settings() {
    return [
        '' => [   // global settings / feature
            'catalogtype' => 'totara' // enable grid catalogue by default
            'totara_job_allowmultiplejobs' => 1,
            'enablegoals' => advanced_feature::ENABLED,
        ],
        'totara_competency' => [   // plugin specific settings
            'continuous_tracking' => 1
        ]
    ];
}

Enforced settings

You can override the load_enforced_settings() method to provide defaults which will be applied once this flavour gets activated. Those settings cannot be changed in the interface anymore once the flavour is active and enforced.

/**
 * Returns an array of enforced settings for this flavour.
 *
 * This method is using the same format as /local/defaults.php
 * described in /local/readme.txt file.
 *
 * NOTE: it is not possible to enforce NULL value.
 *
 * @return array[]
 */
protected function load_enforced_settings() {
    return [
        '' => [  // global settings / feature
            'enableportfolios' => advanced_feature::DISABLED,
            'audiencevisibility' => 1,
            'enablelegacyprogramassignments' => advanced_feature::DISABLED,
        ],
        'moodlecourse' => [   // plugin specific settings
            'visiblelearning' => 1 // Enrolled users and members of the selected audiences
        ]
    ];
}

Prohibited settings

By default all enforced settings are automatically prohibited, meaning they are shown as disabled in the features overview. There is an advanced option to override the load_prohibited_settings() method to let you make modifications to the default behaviour. Normally this is not required but can be implemented as follows:

/**
 * Returns an array of setting defaults that are prohibited by this flavour,
 * by default it is the list of enforced settings.
 *
 * @return array[]
 */
protected function load_prohibited_settings() {
    $settings = parent::load_prohibited_settings();
    return array_merge_recursive($settings, [
        '' => [    // add additional ones
            ...
        ]
    ]);
}

Active flavour notice

If the flavour defines the following strings in its language file this will show up on the environment check page on installation and upgrades. The activenoticeinfo text does support markdown.

$string['activenoticetitle'] = 'Example flavour';
$string['activenoticeinfo'] = 'This text can be defined by the flavour and shows up on installation and upgrades.';

Additional upgrade steps

The method additional_upgrade_steps() can be overridden to implement additional steps on every upgrade. This method is called on every upgrade if the flavour is active.

/**
 * Executes any flavour specific upgrade steps.
 *
 * This is executed for the current active flavour
 * during each upgrade.
 *
 * @return void
 */
public function additional_upgrade_steps() {
    // Add your post install steps here.
    return;
}

Additional activation steps

The method additional_activation_steps() can be overridden to implement additional steps on activation. This method is called only once when the flavour is being activated.

/**
 * Executes any flavour specific post activation steps.
 *
 * This is called also during installation and upgrade
 * when $CFG->forceflavour activated the first time.
 *
 * @return void
 */
 public function additional_activation_steps() {
     // Add your post install steps here.
     return;
}

How to use flavours

CFG flags

Set the $CFG→forceflavour to the flavour you want to enable and enforce. This will lock in the flavour and it can only be changed by changing the same config flag again. 

$CFG->forceflavour = 'example';

After setting the flag you need to either enforce the flavour by clicking the Enforce flavour button in the Feature overview interface or execute the CLI script server/totara/flavour/cli/enforce_current.php.

Installation and upgrades automatically enforce the flavour set by this flag, so it is possible to set the config flag before installation to have it active from the start.

If no flavour is provided the system will default to the Learn flavour.

CLI scripts

There are two scripts which can be called from the command line, one to activate a flavour (and enforce it as well) and one to enforce the current flavour.

# Activate a flavour
php server/totara/flavour/cli/activate_flavour.php --activate=example

# List all available flavours
php server/totara/flavour/cli/activate_flavour.php --list 

# Show active flavour name
php server/totara/flavour/cli/activate_flavour.php --show

# Enforce the current flavour making sure all settings are applied
php server/totara/flavour/cli/enforce_current.php

Changing flavours

If a customer adjusts their subscription to include a different set of products, you may want to change the flavour on an existing site.

Changing to a more fully featured flavour

If you switch from a more limited flavour to one with more features (for example, switching from Learn to Learn and Perform) you will need to manually enable the new features that you want to use. This can be done by navigating to Quick-access menu > Configure features then clicking on the settings link for the product you want to use. Settings that were previously displayed as locked will now be available.

Changing to a more restricted flavour

If you switch from a flavour with more features to one with fewer features (for example, switching from Learn, Perform and Engage to just Learn) some functionality that was previously enabled will now be unavailable.

If you run the command line script to set the new flavour this will happen automatically.

If you modify $CFG→forceflavour in your config.php you will need to manually enforce the flavour. Visit Quick-access menu > Configure Features > Feature overview ({site-url}/totara/flavour/view.php). You will see something like this:

The red rows indicate features that are currently enabled but are not available in this flavour.

Click Enforce current flavour and it will change to this:

When you view the features that are no longer available you'll get a message indicating that they are locked:

Upgrading a pre-13 site

If you are upgrading a site from Totara Learn 12 or below to Totara 13+, we recommend that you set your flavour in your config.php file before you upgrade. This will ensure the new functionality is automatically enabled following the upgrade. See these instructions for more details.