====== moodle plugin ======

---- plugin ----
description: Integrate phpList with Moodle
author     : michiel  
type       : 
lastupdate : 2023/07/27 14:56
compatible : phpList 3.6.14 and up, Moodle 4.2
depends    : 
conflicts  : 
similar    : 
tags       : 

downloadurl: https://github.com/phpList/phplist-plugin-moodle/archive/refs/heads/main.zip
bugtracker : https://github.com/phpList/phplist3/issues
sourcerepo : https://github.com/phpList/phplist-plugin-moodle

----

===== Purpose =====

This plugin synchronises the users in Moodle with phpList. 

===== Installation =====

Install the plugin using the Plugin Manager and the download URL above, which points to latest version of the plugin. Refer to [[:Plugins]] on how to install plugins manually.

For this to work, Moodle and phpList need to use the same Database. phpList will create tables with the configured prefix, so there is no danger of wiping or changing Moodle data.

When you install it and activate it, it will start login authorisation from Moodle, instead of phpList, so read up on configuring first.

===== Examples/Usage =====

The plugin will only read Moodle data, not update it. It will run a sync once a day of the users. The time of the sync can be controlled in the phpList configuration for this plugin. In general you want to sync one time at night, so the best option is to set the hour for sync to be something like 6, which means it will run the sync before 6am. This assumes you run your queue with CLI and run it regularly.

To force an initial sync run, set the hour to 23.

The plugin will automatically create lists and list categories. 

The list categories are:

- Moodle role
- Moodle course: [name of the Course Category]

The lists that will be created are:

- Moodle role: [name of the role]
    these lists will be under the "Moodle role" category
- Moodle course: [name of the Course]
    these lists will be under their Course Category


Users who are on these courses and roles will be automatically added to the related lists.

### first and last name

If you want to synchronise the first and last name from Moodle, do the following:

- create the attributes in phpList for these values
- set the config to match the ID of the attributes.

After that, the first and last names of all users will also be synchronised and you can use them in your campaigns with [[:placeholders|placeholders]].


### data synchronisation

the plugin will map the following data from Moodle to phpList:


{| style=""
|+ column mapping
!
Moodle
!
phpList
|-
|
email
|
email
|-
|
confirmed
|
confirmed
|-
|
deleted
|
blacklisted
|-
|
policyagreed
|
optedin
|-
|
suspended
|
disabled
|}


===== Configuration =====

You need to add the following settings to your config file, for this to work:

<code>
- define('MOODLE_TABLE_PREFIX','mdl_'); // defaults to mdl_
- define('MOODLE_ADMIN_ROLE',1); // defaults to 1

* MOODLE_TABLE_PREFIX is obvious, you can find it in your Moodle config file.
* MOODLE_ADMIN_ROLE is the index of the role in Moodle that will be given access to phpList.
</code>

The "auth type" of the users who access phpList needs to be "manual".


Once activated the plugin has these config options:

{{:plugin:pasted:20230727-160513.png}}


===== Caveats =====

phpList will overwrite user data when it was changed in phpList. For example, if a users' email changes, it will be changed in phpList as well. So, making changes in phpList should be avoided. The system should be used solely for sending campaigns and statistics, but user data management should be done in Moodle.

Same with admins. Once Moodle takes control of authentication of phpList, there's no point in making changes to the admins in phpList.

Many other features in phpList are likely to be less useful, so make sure you know what you're doing.




===== Development =====

Many further features can be added over time. Contact [[https://www.catalyst-eu.net|Catalyst IT EU]] to get a quote for custom development.


=== Change Log ===

  * **2023/07/27 14:56**
    * Initial release

=== Known Bugs and Issues ===

This integration is a very low level, at database, integration. As a result, by not using Moodle's API, there is a good chance that things will break in future versions. 

This plugin is more a Proof of Concept, and further development will be needed to handle this more thoroughly.


=== ToDo/Wish List ===

At this stage there are no further plans for new features, but requests will be accepted.

Some issues that could be interesting to explore are:

* handling bounces and feeding this back to Moodle. 
* adding sync changes to the user history.






===== FAQ =====

===== Discussion =====

Discuss at the [[https://discuss.phplist.org/|phpList forums]].