MoodleDocs - User contributions [en]

Development:Local customisation

2011-04-07T20:51:06Z

Tdjones: /* Other /local/ customisation files */

{{Infobox Project
|name = Local customisations
|state = Implemented
|tracker = MDL-17376, MDL-16438
|discussion = http://moodle.org/mod/forum/discuss.php?d=126017 http://moodle.org/mod/forum/discuss.php?d=86903
|assignee = [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]], some parts were originally proposed and implemented in 1.9 by Penny Leach
}}
{{Moodle 2.0}}

The recommended way to add new functionality to Moodle is to create a new standard plugin (module, block, auth, enrol, etc.).The /local/ plugins are mostly suitable for things that do not fit standard plugins.

== Custom /local/ plugins ==

Local plugins are used in cases when no standard plugin fits, examples are:
* event consumers communicating with external systems
* custom definitions of web services and external functions
* applications that extend moodle at the system level (hub server, amos server, etc.)
* new database tables used in core hacks (discouraged)
* new capability definitions used in core hacks
* custom admin settings
* extending the navigation block with custom menus [http://moodle.org/mod/forum/discuss.php?d=170325&parent=753095]

=== Standard plugin features: ===
* /local/xxx/version.php - version of script (must be incremented after changes)
* /local/xxx/db/install.xml - executed during install (new version.php found)
* /local/xxx/db/install.php - executed right after install.xml
* /local/xxx/db/uninstall.php - executed during uninstallation
* /local/xxx/db/upgrade.php - executed after version.php change
* /local/xxx/db/access.php - definition of capabilities
* /local/xxx/db/events.php - event handlers and subscripts
* /local/xxx/db/messages.php - messaging registration
* /local/xxx/db/external.php - web services and external functions descriptions
* /local/xxx/lang/en/local_pluginname.php - language file

The ''xxx'' is used instead of your local plugin name, plugins of the same type are installed/upgraded in alphabetical order.

=== List of differences from normal plugins: ===
* always executed last during install/upgrade - guaranteed by order of plugins in <code>get_plugin_types()</code>
* are expected to use event handlers - events are intended for communication core-->plugins only, local plugins are the best candidates for event handlers
* can add admin settings to any settings page - loaded last when constructing admin tree
* do not need to have any UI - other plugins are usually visible somewhere
* some extra hooks (not implemented yet)

== /local/xxx/db/messages.php ==
Example File Structure:
<code php>
<?php

/**
* Defines message providers (types of messages being sent)
*
* @package mod-forum
* @copyright 1999 onwards Martin Dougiamas http://moodle.com
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

$messageproviders = array (

/// Ordinary single forum posts
'posts' => array (
)

);
</code>

== Other /local/ customisation files==

===Customised site defaults===

Different default site settings can be stored in file /local/defaults.php.
These new defaults are used during installation, upgrade and later are
displayed as default values in admin settings. This means that the content
of the defaults files is usually updated BEFORE installation or upgrade.

These customised defaults are useful especially when using CLI tools
for installation and upgrade.

Sample /local/defaults.php file content:
<code php>
<?php
$defaults['moodle']['forcelogin'] = 1; // new default for $CFG->forcelogin
$defaults['scorm']['maxgrade'] = 20; // default for get_config('scorm', 'maxgrade')
$defaults['moodlecourse']['numsections'] = 11;
$defaults['moodle']['hiddenuserfields'] = array('city', 'country');
</code>
First bracket contains string from column plugin of config_plugins table.
Second bracket is the name of setting. In the admin settings UI the plugin and
name of setting is separated by "|".

The values usually correspond to the raw string in config table, with the exception
of comma separated lists that are usually entered as real arrays.

Please note that not all settings are converted to admin_tree,
they are mostly intended to be set directly in config.php.

=== 2.0 pre-upgrade script===

You can use /local/upgrade_pre20.php script for any code that needs to
be executed before the main upgrade to 2.0. Most probably this will
be used for undoing of old hacks that would otherwise break normal
2.0 upgrade.

This file is just included directly, there does not need to be any
function inside. If the execution stops the script is executed again
during the next upgrade. The first execution of lib/db/upgrade.php
increments the version number and the pre upgrade script is not
executed any more.

== Customisations outside of /local/ directory==

=== Forced settings===

Sometimes it is useful to force some settings and prevent any changes of these settings via the standard admin UI. It is possible to hardcode these settings in config.php.

In case of course settings it is very simply, the values are assigned directly to $CFG properties. In case of plugins the values are specified in a multidimensional array in $CFG->force_plugin_settings.

Sample code in config.php
<code php>
$CFG->allowobjectembed = 0;
$CFG->forced_plugin_settings = array('page'=>array('displayoptions'=>5, 'requiremodintro'=>1), 'folder'=>'requiremodintro'=>1);
</code>

=== Local language customisations===

Moodle supports other type of local customisation of standard language
packs. If you want to create your own language pack based on another
language create new dataroot directory with "_local" suffix, for example
following file with content changes string "Login" to "Sign in":
moodledata/lang/en_local
<code php>
<?php
$string['login'] = 'Sign in';
</code>
See also https://docs.moodle.org/en/Language_editing

=== Custom script injection===

Very old customisation option that allows you to modify scripts by injecting
code right after the require 'config.php' call.

This setting is enabled by manually setting $CFG->customscripts variable
in config.php script. The value is expected to be full path to directory
with the same structure as dirroot. Please note this hack only affects
files that actually include the config.php!

; Examples:
* disable one specific moodle page without code modification
* alter page parameters on the fly

=== Direct code modifications===
This is usually the last resort, if possible do not do it. And if you still do it use some version control system (preferably git).

=== Direct database modifications===
Very strongly discouraged! Sometimes field lengths may be modified without side effects. Adding or removing of db fields will most probably cause major problems during future upgrades. New database tables should be added only from plugins.

== Local customisations in previous versions ==
Previous versions include only partial support for customisations in /local/ directory.

=== List of local customisations in 1.9.x: ===
* /local/cron.php - custom cron jobs
* /local/settings.php - custom admin settings
* /local/db/upgrade.php - general modifications
* /local/lang/* - custom strings
* /local/lib.php - local_delete_course()

=== Migration from old 1.9.x /local/: ===
* <code>local/*</code> needs to be copied to new directory
* <code>local/xxxx/db/install.php</code> is intended for first installation, originally everything was in upgrade.php
* events are used instead of hooks
* upgrade code needs to migrate old settings, events, etc. directly in core db tables - such as change component strings and capability names from db/install.php or manually before/after upgrade

==See also==

* [http://moodle.org/mod/forum/discuss.php?d=170325&parent=753095 Extending navigation block]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=86903 Local Customisations] forum discussion
* http://cvs.moodle.org/moodle/local/readme.txt?view=markup
* [[Local customisation (Moodle 1.9)]]

[[Category:Developer|Local customisation]]

Development:DML functions

2011-03-29T16:40:12Z

Tdjones: /* Inserting Records */

{{Moodle_2.0}}This page describes the functions available to access data in the Moodle database. You should '''exclusively''' use these functions in order to retrieve or modify database content because these functions provide a high level of abstraction and guarantee that your database manipulation will work against different RDBMSes.

Where possible, tricks and examples will be documented here in order to make developers' lives a bit easier. Of course, feel free to clarify, complete and add more information to this documentation. It will be welcome, absolutely!

== Main info ==

'''Important note:''' All the functions shown on this page are for use in '''Moodle 2.0 upwards''', where we changed the [[Development:DB layer 2.0|DB layer]] to support some new features. If you need information for previous Moodle version, take a look to the [[Development:DML functions - pre 2.0|DML functions - pre 2.0]] page. For a detailed reference of changes, see the [[Development:DB layer 2.0 migration docs|migration docs]].

* All the function calls on this page are public methods of the $DB global object, so you'll need to "import" it within your functions (not needed in global scripts) with one simple:
<code php>global $DB;</code>
* All the $table parameters in the functions are meant to be the table name ''without'' prefixes.
<code php>$user = $DB->get_record('user', array('id'=>'1');</code>
* When using the xxx_sql() functions, table names must be enclosed between curly braces.
<code php>$user = $DB->get_record_sql('SELECT * FROM {user} WHERE id = ?', array(1));</code>
* All the $conditions parameters in the functions are arrays of fieldname=>fieldvalue elements.
<code php>$user = $DB->get_record('user', array('firstname'=>'Martin', 'lastname'=>'Dougiamas'));</code>
* All the $params parameters in the functions are arrays of values used to fill placeholders in SQL statements. Both the question mark and named placeholders can be used. Note that named params '''must be unique''' even if the value passed is the same.
<code php>
/// Question mark placeholders:
$DB->get_record_sql('SELECT * FROM {user} WHERE firstname = ? AND lastname = ?',
array('Martin', 'Dougiamas'));

/// Named placeholders:
$DB->get_record_sql('SELECT * FROM {user} WHERE firstname = :firstname AND lastname = :lastname',
array('firstname'=>'Martin', 'lastname'=>'Dougiamas'));
</code>

== The functions ==

===Seeing how many records match a given criteria===
<code php>
o $DB->count_records($table, array $conditions=null)
/// Count the records in a table where all the given conditions met.
o $DB->count_records_select($table, $select, array $params=null, $countitem="COUNT('x')")
/// Count the records in a table which match a particular WHERE clause.
o $DB->count_records_sql($sql, array $params=null)
/// Get the result of a SQL SELECT COUNT(...) query.
</code>

===Seeing if one record exists===
<code php>
o $DB->record_exists($table, array $conditions=null)
/// Test whether a record exists in a table where all the given conditions met.
o $DB->record_exists_select($table, $select, array $params=null)
/// Test whether any records exists in a table which match a particular WHERE clause.
o $DB->record_exists_sql($sql, array $params=null)
/// Test whether a SQL SELECT statement returns any records.
</code>

===Getting a single record===
<code php>
o $DB->get_record($table, array $conditions, $fields='*', $ignoremultiple=false)
/// Get a single database record as an object where all the given conditions met.
o $DB->get_record_select($table, $select, array $params=null, $fields='*', $ignoremultiple=false)
/// Get a single database record as an object which match a particular WHERE clause.
o $DB->get_record_sql($sql, array $params=null)
/// Get a single database record as an object using a SQL statement.
</code>

===Getting an array of records===
<code php>
o $DB->get_records($table, array $conditions=null, $sort='', $fields='*', $limitfrom=0, $limitnum=0)
/// Get a number of records as an array of objects where all the given conditions met.
o $DB->get_records_select($table, $select, array $params=null, $sort='', $fields='*', $limitfrom=0, $limitnum=0)
/// Get a number of records as an array of objects which match a particular WHERE clause.
o $DB->get_records_sql($sql, array $params=null, $limitfrom=0, $limitnum=0)
/// Get a number of records as an array of objects using a SQL statement.
o $DB->get_records_menu($table, array $conditions=null, $sort='', $fields='*', $limitfrom=0, $limitnum=0)
/// Get the first two columns from a number of records as an associative array where all the given conditions met.
o $DB->get_records_select_menu($table, $select, array $params=null, $sort='', $fields='*', $limitfrom=0, $limitnum=0)
/// Get the first two columns from a number of records as an associative array which match a particular WHERE clause.
o $DB->get_records_sql_menu($sql, array $params=null, $limitfrom=0, $limitnum=0)
/// Get the first two columns from a number of records as an associative array using a SQL statement.
o $DB->get_records_list($table, $field, array $values, $sort='', $fields='*', $limitfrom='', $limitnum='')
/// Get a number of records as an array of objects where one field match one list of values.
</code>

===Getting a particular field value from one record===
<code php>
o $DB->get_field($table, $return, array $conditions)
/// Get a single field value from a table record where all the given conditions met.
o $DB->get_field_select($table, $return, $select, array $params=null)
/// Get a single field value from a table record which match a particular WHERE clause.
o $DB->get_field_sql($sql, array $params=null)
/// Get a single field value (first field) using a SQL statement.
</code>

===Getting a particular field value from various records===

<code php>
o $DB->get_fieldset_select($table, $return, $select, array $params=null)
/// Selects records and return values of chosen field as an array which match a particular WHERE clause.
o $DB->get_fieldset_sql($sql, array $params=null)
/// Selects records and return values (first field) as an array using a SQL statement.
</code>

===Setting a particular field in the database===
<code php>
o $DB->set_field($table, $newfield, $newvalue, array $conditions=null)
/// Set a single field in every table record where all the given conditions met.
o $DB->set_field_select($table, $newfield, $newvalue, $select, array $params=null)
/// Set a single field in every table record which match a particular WHERE clause.
</code>

===Deleting Records===
<code php>
o $DB->delete_records($table, array $conditions=null)
/// Delete the records from a table where all the given conditions met.
o $DB->delete_records_select($table, $select, array $params=null)
/// Delete one or more records from a table which match a particular WHERE clause.
</code>

===Inserting Records===
<code php>
o $DB->insert_record($table, $dataobject, $returnid=true, $bulk=false)
/// Insert a record into a table and return the "id" field if required.
</code>
====Example(s)====
<code php>
$record = new stdClass();
$record->name = 'overview';
$record->displayorder = '10000';
$DB->insert_record('quiz_report', $record);
</code>

===Updating Records===
<code php>
o $DB->update_record($table, $dataobject, $bulk=false)
/// Update a record in a table.
</code>

===Using Recordsets===

Where the number of records to be retrieved from DB is high, the '''get_records_xxx()''' functions above are far from optimal, because they load all the records in memory at the same time. Under those circumstances, it is highly recommended to use these '''get_recordset_xxx()''' functions instead, which use one nice mechanism to iterate over all the target records and save a lot of memory.

Only one thing is '''absolutely important''': Don't forget to close the recordsets after using them! (This will free up a lot of resources in the RDBMS).

Here is the general way to iterate over records using the '''get_recordset_xxx()''' functions:

<code php>
if ($rs = $DB->get_recordset(....) {
foreach ($rs as $record) {
/// Do whatever you want with this record
}
$rs->close(); /// Don't forget to close the recordset!
}
</code>

And this is the list of available functions (100% paired with the get_records_xxx() above):
<code php>
o $DB->get_recordset($table, array $conditions=null, $sort='', $fields='*', $limitfrom=0, $limitnum=0)
/// Get a number of records as a moodle_recordset where all the given conditions met.
o $DB->get_recordset_select($table, $select, array $params=null, $sort='', $fields='*', $limitfrom=0, $limitnum=0)
/// Get a number of records as a moodle_recordset which match a particular WHERE clause.
o $DB->get_recordset_sql($sql, array $params=null, $limitfrom=0, $limitnum=0);
/// Get a number of records as a moodle_recordset using a SQL statement.

o $DB->get_recordset_list($table, $field='', $values='', $sort='', $fields='*', $limitfrom='', $limitnum='')
/// Get a number of records as a moodle_recordset where one field matches one list of values.
</code>

===Delegated transactions===

* Please note some databases do not support transactions (such as the MyISAM MySQL database engine), however all server administrators are strongly encouraged to migrate to databases that support transactions (such as the InnoDB MySQL database engine).
* Previous versions supported only one level of transaction. Since Moodle 2.0, the DML layer emulates delegated transactions that allow nesting of transactions.
* Transactions should not be used much in Moodle core; they are intended for various plugins such as web services, enrol and auth plugins.
* Some subsystems (such as messaging) do not support transactions because is it is not possible to rollback in external systems.

A transaction is started by:
<code php>
$transaction = $DB->start_delegated_transaction();
</code>

and finished by:
<code php>
$transaction->allow_commit();
</code>

Usually a transaction is rolled back when an exception is thrown. <code>$transaction->rollback($ex);</code> must be used very carefully because it might break compatibility with databases that do not support transactions. Transactions cannot be used as part of expected code flow; they can be used only as an emergency protection of data consistency.

See more details in [[Development:DB layer 2.0 delegated transactions]] or MDL-20625.

===Helper Functions===

In order have real cross-db compatibility, there are some helper functions used to build SQL fragments based on the DB Moodle is running. Using them we'll avoid conditional queries here and there and have those "incompatibilities" fixed once and for ever.
<code php>
o $DB->sql_bitand($int1, $int2)
/// Returns the SQL text to be used in order to perform one bitwise AND
/// operation between 2 integers.
o $DB->sql_bitnot($int1)
/// Returns the SQL text to be used in order to perform one bitwise NOT
/// operation with 1 integer.
o $DB->sql_bitor($int1, $int2)
/// Returns the SQL text to be used in order to perform one bitwise OR
/// operation between 2 integers.
o $DB->sql_bitxor($int1, $int2)
/// Returns the SQL text to be used in order to perform one bitwise XOR
/// operation between 2 integers.

o $DB->sql_null_from_clause()
/// Returns the FROM clause required by some DBs in all SELECT statements.

o $DB->sql_ceil($fieldname)
/// Returns the correct CEIL expression applied to fieldname.
o $DB->sql_ilike()
/// Returns the proper SQL to do LIKE in a case-insensitive way.
o $DB->sql_length($fieldname)
/// Returns the SQL text to be used to calculate the length in characters of one expression.
o $DB->sql_modulo($int1, $int2)
/// Returns the SQL text to be used in order to calculate module - remainder after division
o $DB->sql_position($needle, $haystack)
/// Returns the SQL for returning searching one string for the location of another.
/// Note: If using placeholders BOTH in $needle and $haystack, they MUST be named placeholders.
o $DB->sql_substr($expr, $start, $length=false)
/// Returns the proper substr() SQL text used to extract substrings from DB.
/// Note: This fuction has changed in Moodle 2.0 and now at least 2 params are mandatory.
/// Note: Now it returns the whole SQL text to be used instead of only the function name.

o $DB->sql_cast_char2int($fieldname, $text=false)
/// Returns the SQL to be used in order to CAST one CHAR column to INTEGER.
o $DB->sql_cast_char2real($fieldname, $text=false)
/// Returns the SQL to be used in order to CAST one CHAR column to REAL number.

o $DB->sql_compare_text($fieldname, $numchars=32)
/// Returns the SQL text to be used to compare one TEXT (clob) column.
/// with one VARCHAR column.
o $DB->sql_order_by_text($fieldname, $numchars=32)
/// Returns the SQL text to be used to order by one TEXT (clob) column.

o $DB->sql_concat()
/// Returns the proper SQL to do CONCAT between the elements passed.
o $DB->sql_concat_join($separator="' '", $elements=array())
/// Returns the proper SQL to do CONCAT between the elements passed using one separator.
o $DB->sql_fullname($first='firstname', $last='lastname')
/// Returns the proper SQL to concatenate $firstname and $lastname.

o $DB->sql_isempty($tablename, $fieldname, $nullablefield, $textfield)
/// Returns the proper SQL to know if one field is empty.
o $DB->sql_isnotempty($tablename, $fieldname, $nullablefield, $textfield)
/// Returns the proper SQL to know if one field is not empty.
o $DB->sql_empty()
/// Returns the empty string char used by every supported DB.
</code>

==See also==

* [[Development:DML exceptions|DML exceptions]]: New DML code is throwing exceptions instead of returning false if anything goes wrong
* [[Development:DML drivers|DML drivers]]: Database drivers for new DML layer
* [[Development:DML functions - pre 2.0|DML functions - pre 2.0]]: '''(deprecated!)''' For information valid before Moodle 2.0.
* [[Development:DDL functions|DDL functions]]: Where all the functions used to handle DB objects ([[wikipedia:Data_Definition_Language|DDL]]) are defined.
* [[Development:DB layer 2.0 examples|DB layer 2.0 examples]]: To see some code examples using various DML functions.
* [[Development:DB layer 2.0 migration docs|DB layer 2.0 migration docs]]: Information about how to modify your code to work with the new Moodle 2.0 DB layer.
* [[Development:DTL functions|DTL functions]]: Exporting, importing and moving of data stored in SQL databases

[[Category:DB]]
[[Category:XMLDB]]

MNet

2011-02-01T21:45:58Z

Tdjones: /* Using it */

The network feature allows a Moodle administrator to establish a link with another Moodle, and to share some resources with the users of that Moodle. This features was introduced in Moodle 1.8.

==Overview==
The initial release of MNet is bundled with a Authentication Plugin, which makes single-sign-on between Moodles possible. A user with the username jody logs in to her Moodle server as normal, and clicks on a link that takes her to a page on another Moodle server. Normally, she would have only the privileges of a guest on the remote Moodle, but behind the scenes, single-sign-on has established a fully authenticated session for Jody on the remote site.

'''WARNING:''' MNet requires the use of '''xmlrpc'''. Please go to your phpinfo page if you are interested in using this and search for --with-xmlrpc. If your php has not been compiled with xmlrpc then you need to address that first! At present it appears that PEAR xmlrpc will not work.
[[Image:Administration Block Users Authentication MoodleNetwork.jpg|thumb|MNet setting in ''Admin > User > Authentication > Moodle Network]]

==Security==
The MNet feature requires that your server has the '''Curl''' and '''OpenSSL''' extensions installed. When you install or upgrade to Moodle 1.8, your system will generate a new OpenSSL certificate for encrypted communication with other Moodles, and will thereafter rotate encryption keys on a monthly basis (approx).

Communication takes place over an XML-RPC transport, and the XML-RPC documents are wrapped first in an XMLDSIG (XML digital signature) envelope, and then in an XMLENC (XML encryption) envelope. The encryption all happens within PHP, and does not require an https (Apache SSL) server.

References:
*[http://www.w3.org/TR/xmldsig-core/ XML Digital Signatures]
*[http://www.w3.org/TR/xmlenc-core/ XML Encryption]

A special mode can be enabled which would allow a machine with a specified IP address to make calls to the XML-RPC layer without using either encryption or signature envelopes. This mode is provided to enable Moodle to communicate with other software systems in which the integration of signatures and encryption might be prohibitively difficult. It is not envisioned that unencrypted inter-Moodle networking will ever be enabled.

==Peer to Peer Network==

This is the basic layout of the system. It can be very useful to run one Moodle per faculty or departments, each with its own user management, and yet permit users to roam across the Moodle installs... subject to permissions of course.

===Setup===

The instructions will cover 2 Moodle installations: MoodleA and MoodleB. Both are installed correctly and have never had a Moodle Network configuration.

Note: If you experience problems, ensure debugging is turned on in ''Site Administration > Server > Debugging''. Extra diagnostic messages may be displayed (particularly from Moodle 1.9.2)

For Moodle 2.0, you need to enable Networking (under the Site Administration > Advanced Features menu). This will add the "Networking" menu to the Site Administration menu.

# Get them to talk to each other
## Ensure ''Admin > Server > Environment'' indicates you have curl installed
## If MoodleA and MoodleB are hosted in the same domain, ensure they have a different cookie prefix. Note that changing the cookie prefix will log you out! You can change the cookie prefix via ''Admin > Server > Session Handling''.
## On both, go to ''Admin > Network > Settings'' and turn Networking ON.
## On MoodleA go to ''Admin > Network > Peers'' - put the URL of MoodleB under "Add New Host" and click Add. The URL should include the directory where your Moodle code is located, for example ''www.mymoodle.org/moodle''.
## Do the equivalent on MoodleB.
# Get user roaming going
## (Although discussion exists about removing this setting, it is still required as of 2.0.1) [http://moodle.org/mod/forum/discuss.php?d=141491] ). On both servers:
### For 2.0, go to ''Administration > Plugins > Authentication > Manage authentication''. Enable ''MNet Authentication'' by clicking the 'enable' icon.
### For 1.9, go to ''Administration > Users > Authentication > Manage authentication'' and enable Moodle Network authentication plugin. Click on 'Settings' and enable auto_add_remote_users.''
## On MoodleA go to ''Admin > Networking > (Manage) Peers'', click on 'MoodleB', and click on 'Services'. Enable SSO-IDP(SSO Identity Provider) publish and subscribe, and SSO-SP(SSO Service Provider) publish and subscribe.
## Do the equivalent on MoodleB. (By both publishing and subscribing you allow users to move freely between the two servers. By only publishing or subscribing between servers you create a one way traversal)
## On both, go to ''Admin > Users > Permissions > Define Roles'', only roles that have "Roam to a remote Moodle moodle/site:mnetlogintoremote" will be allowed to roam. Grant the privilege as appropriate.
### eg. enabling for ''Authenticated user'' allows any authenticated user to roam between servers.
## On both servers, go to the homepage, and add the 'Network Servers' block.
## To test, it is recommended to use a different browser (even on a different machine) that is logged in to neither. Login to MoodleA with a non-administrator account that has the permissions to roam. You should see the Network Servers block, and clicking on it you should go to MoodleB with a newly autocreated account.
# Get remote enrolments going -- this is optional. It allows an administrator of MoodleB to enrol users that are "native" to MoodleB in remote courses in MoodleA, and viceversa.
## On both, go to ''Site administration > Plugins > Enrolments > Manage enrol plugins'' in 2.0 onwards or ''Administration > Courses > Enrolments'' pre-2.0 and enable Moodle Network enrolment plugin (click Save). Click on 'Edit' and enable 'allow_allcourses' or select some courses or categories to be remotely enrolled.
## On the server you want to receive enrolments:
### For 2.0, go to ''Site administration > Plugins > Enrolments > Manage enrol plugins''. Enable ''MNet remote enrolments'' by clicking the 'enable' icon. (For ''MNet remote enrolments'' settings info see [[MNet_remote_enrolments|MNet remote enrolments]])
### For 1.9, go to ''Administration > Users > Authentication > Manage authentication'' and enable Moodle Network authentication plugin. Click on 'Settings' and enable auto_add_remote_users.''
## On MoodleA go to ''Admin > Network > Peers'', click on 'MoodleB', and click on 'Services'. Enable Enrolment publish and/or subscribe.
## Do the equivalent on MoodleB.
## On every course you want to allow enrolments into:
### Enter course and go to ''Settings -> Course administration -> Users -> Enrolment methods''
### From ''Add method'' drop-down select ''MNet remote enrolments''
### On the new screen select the ''Remote host'' you want to allow enrolments from, the Role for the enrolled users, and click save. (Note: you can only add a single ''MNet remote enrolments'' method per course.)

===Using it===
# For 1.9: in MoodleA go to ''Admin > Networking > Enrolments''. You will see MoodleB listed. Click on MoodleB and you will see a list of courses that MoodleB offers for remote enrolment. Select the course you want, and then enroll the users you want to that course.
# For 2.0: in MoodleA go to ''Admin > Networking > Remote enrolments client''. You will see MoodleB listed. Click on ''Edit enrolments'' button beside MoodleB and you will see a list of courses that MoodleB offers for remote enrolment. Click 'Edit enrolments'', select the users you want to enroll, and then click Add to enroll them in the course.

==Connecting to a Mnet hub==
A Mnet hub (do not confuse it with the [[Community hub]] project of Moodle 2.0) is a Moodle server that is configured to accept connections from other Moodle servers, and to provide a set of services to users of these other servers. This guideline will direct you to connect to a Mnet hub, assess the services it has to offer, and enable those services for your users.

===Setup===
# Get talking to the Hub
## Ensure that the ''Admin > Server > Environment'' page indicates you have curl and openssl installed
## Go to ''Admin > Network > Settings'' and turn Networking on
## Go to ''Admin > Network > Peers'' and enter the URL of Mnet Hub under "Add New Host". Click Add
## The host details for the Mnet Hub should appear with the Site Name field already populated. Click Save changes
## The details will be written to your database and two new tabs will appear in this window: 'Services' and 'Logs'. Click Services
##A list of services will appear, each with a checkbox for 'publish' and 'subscribe'. Check the checkboxes for any services you want to publish or subscribe to

===Using it===
If the Mnet Hub has already enabled a service for you, there will be a tick alongside the appropriate checkbox, for example: if the Hub is publishing Moodle Networked Enrolment, then a tick will appear alongside the subscribe checkbox for this service. Note that in order to enable some functionality, prominently single-sign-on, you may have to publish a service, e.g. the Identity Provider service. The Mnet Hub will access this service on your Moodle, asking it to authenticate your users.
# Enable Roaming
## Subscribe to SSO (Service Provider) by checking the box
## Publish SSO (Identity Provider) by checking the box
## Click Save changes
## Go to ''Admin > Users > Permissions > Define Roles'', and grant the capability Roam to a remote Moodle moodle/site:mnetlogintoremote to an appropriate role
## Go to ''Administration > Plugins > Authentication > Manage authentication'' in 2.0 onwards or ''Administration > Users > Authentication > Manage authentication'' in 1.9 and enable the Moodle Network authentication plugin
## Go to your homepage, turn on editing, and add the 'Network Servers' block
## Using a different web-browser, log on as a non-admin user who inhabits the role you granted the roaming capability to
## Note that the Mnet Hub is listed in the Network Servers block on the homepage. Click on the link to that server
## Some of your user details will be transferred to the Mnet Hub server, and a browsing session will be started for you as if you had logged on there directly
# Enable Networked Enrolment
## Return to the web browser you've been using as the site administrator
## Go to ''Admin > Network > Peers'' and click on the entry for the Mnet Hub.
## Click on the Services tab
## Subscribe to Moodle Networked Enrolment
## Go to ''Site administration > Plugins > Enrolments > Manage enrol plugins'' in 2.0 onwards or ''Administration > Courses > Enrolments'' pre-2.0 and enable the Moodle Network enrolment plugin. Click Save changes
## Click on edit to view the details for networked enrolments.
## Go to ''Admin > Networking > Enrolments'' to see a list of Moodle servers that offer this service to you
## Click on a server name to view a list of courses that the server offers to your users
## Click on a course name, to view a list users that you can enrol in this course
## Enrol users
## Profit!

==Running a Mnet hub==
A Mnet hub is a regular Moodle site that runs in a special mode. As a Moodle Administrator, when you add another Moodle site to your list of network peers, your Moodle will contact that site to find out what it is called, and to request its public key for encrypted communication. Normally, the remote server will simply provide this information without making any record of the transaction.

A Mnet hub is different. As soon as you add an entry for a Mnet hub to your system, the Mnet hub will create an entry for your server in its list of hosts, and may immediately begin to offer services to the users of your site.

This section will guide you to set up a Mnet hub, and select services to offer to all comers.

===Setup===
# Enable Networking
## Ensure that the ''Admin > Server > Environment'' page indicates you have curl and openssl installed
## Go to ''Admin > Network > Settings'' and turn Networking on
## Go to ''Admin > Network > Peers'' and tick the checkbox for Register all hosts. Click on Save Changes
## On the same page, the first entry in your list of hosts should be All hosts. Click this link
## Click on Services and enable any services you want to offer to all comers

==See also==

* [[Moodle Network FAQ]]
* [[Development:Moodle Network|Moodle Network development notes]]
* Using Moodle [http://moodle.org/mod/forum/view.php?id=6976 MNet forum]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=92749 Examples of how people are using Moodle networks] forum discussion

[[Category:Authentication]]
[[Category:Enrolment]]
[[Category:MNet]]

[[fr:Réseau Moodle]]
[[ja:Moodleネットワーク]]
[[es:Red Moodle]]
[[cs:Síťové služby]]

MNet

2011-02-01T21:45:24Z

Tdjones: /* Setup */

The network feature allows a Moodle administrator to establish a link with another Moodle, and to share some resources with the users of that Moodle. This features was introduced in Moodle 1.8.

==Overview==
The initial release of MNet is bundled with a Authentication Plugin, which makes single-sign-on between Moodles possible. A user with the username jody logs in to her Moodle server as normal, and clicks on a link that takes her to a page on another Moodle server. Normally, she would have only the privileges of a guest on the remote Moodle, but behind the scenes, single-sign-on has established a fully authenticated session for Jody on the remote site.

'''WARNING:''' MNet requires the use of '''xmlrpc'''. Please go to your phpinfo page if you are interested in using this and search for --with-xmlrpc. If your php has not been compiled with xmlrpc then you need to address that first! At present it appears that PEAR xmlrpc will not work.
[[Image:Administration Block Users Authentication MoodleNetwork.jpg|thumb|MNet setting in ''Admin > User > Authentication > Moodle Network]]

==Security==
The MNet feature requires that your server has the '''Curl''' and '''OpenSSL''' extensions installed. When you install or upgrade to Moodle 1.8, your system will generate a new OpenSSL certificate for encrypted communication with other Moodles, and will thereafter rotate encryption keys on a monthly basis (approx).

Communication takes place over an XML-RPC transport, and the XML-RPC documents are wrapped first in an XMLDSIG (XML digital signature) envelope, and then in an XMLENC (XML encryption) envelope. The encryption all happens within PHP, and does not require an https (Apache SSL) server.

References:
*[http://www.w3.org/TR/xmldsig-core/ XML Digital Signatures]
*[http://www.w3.org/TR/xmlenc-core/ XML Encryption]

A special mode can be enabled which would allow a machine with a specified IP address to make calls to the XML-RPC layer without using either encryption or signature envelopes. This mode is provided to enable Moodle to communicate with other software systems in which the integration of signatures and encryption might be prohibitively difficult. It is not envisioned that unencrypted inter-Moodle networking will ever be enabled.

==Peer to Peer Network==

This is the basic layout of the system. It can be very useful to run one Moodle per faculty or departments, each with its own user management, and yet permit users to roam across the Moodle installs... subject to permissions of course.

===Setup===

The instructions will cover 2 Moodle installations: MoodleA and MoodleB. Both are installed correctly and have never had a Moodle Network configuration.

Note: If you experience problems, ensure debugging is turned on in ''Site Administration > Server > Debugging''. Extra diagnostic messages may be displayed (particularly from Moodle 1.9.2)

For Moodle 2.0, you need to enable Networking (under the Site Administration > Advanced Features menu). This will add the "Networking" menu to the Site Administration menu.

# Get them to talk to each other
## Ensure ''Admin > Server > Environment'' indicates you have curl installed
## If MoodleA and MoodleB are hosted in the same domain, ensure they have a different cookie prefix. Note that changing the cookie prefix will log you out! You can change the cookie prefix via ''Admin > Server > Session Handling''.
## On both, go to ''Admin > Network > Settings'' and turn Networking ON.
## On MoodleA go to ''Admin > Network > Peers'' - put the URL of MoodleB under "Add New Host" and click Add. The URL should include the directory where your Moodle code is located, for example ''www.mymoodle.org/moodle''.
## Do the equivalent on MoodleB.
# Get user roaming going
## (Although discussion exists about removing this setting, it is still required as of 2.0.1) [http://moodle.org/mod/forum/discuss.php?d=141491] ). On both servers:
### For 2.0, go to ''Administration > Plugins > Authentication > Manage authentication''. Enable ''MNet Authentication'' by clicking the 'enable' icon.
### For 1.9, go to ''Administration > Users > Authentication > Manage authentication'' and enable Moodle Network authentication plugin. Click on 'Settings' and enable auto_add_remote_users.''
## On MoodleA go to ''Admin > Networking > (Manage) Peers'', click on 'MoodleB', and click on 'Services'. Enable SSO-IDP(SSO Identity Provider) publish and subscribe, and SSO-SP(SSO Service Provider) publish and subscribe.
## Do the equivalent on MoodleB. (By both publishing and subscribing you allow users to move freely between the two servers. By only publishing or subscribing between servers you create a one way traversal)
## On both, go to ''Admin > Users > Permissions > Define Roles'', only roles that have "Roam to a remote Moodle moodle/site:mnetlogintoremote" will be allowed to roam. Grant the privilege as appropriate.
### eg. enabling for ''Authenticated user'' allows any authenticated user to roam between servers.
## On both servers, go to the homepage, and add the 'Network Servers' block.
## To test, it is recommended to use a different browser (even on a different machine) that is logged in to neither. Login to MoodleA with a non-administrator account that has the permissions to roam. You should see the Network Servers block, and clicking on it you should go to MoodleB with a newly autocreated account.
# Get remote enrolments going -- this is optional. It allows an administrator of MoodleB to enrol users that are "native" to MoodleB in remote courses in MoodleA, and viceversa.
## On both, go to ''Site administration > Plugins > Enrolments > Manage enrol plugins'' in 2.0 onwards or ''Administration > Courses > Enrolments'' pre-2.0 and enable Moodle Network enrolment plugin (click Save). Click on 'Edit' and enable 'allow_allcourses' or select some courses or categories to be remotely enrolled.
## On the server you want to receive enrolments:
### For 2.0, go to ''Site administration > Plugins > Enrolments > Manage enrol plugins''. Enable ''MNet remote enrolments'' by clicking the 'enable' icon. (For ''MNet remote enrolments'' settings info see [[MNet_remote_enrolments|MNet remote enrolments]])
### For 1.9, go to ''Administration > Users > Authentication > Manage authentication'' and enable Moodle Network authentication plugin. Click on 'Settings' and enable auto_add_remote_users.''
## On MoodleA go to ''Admin > Network > Peers'', click on 'MoodleB', and click on 'Services'. Enable Enrolment publish and/or subscribe.
## Do the equivalent on MoodleB.
## On every course you want to allow enrolments into:
### Enter course and go to ''Settings -> Course administration -> Users -> Enrolment methods''
### From ''Add method'' drop-down select ''MNet remote enrolments''
### On the new screen select the ''Remote host'' you want to allow enrolments from, the Role for the enrolled users, and click save. (Note: you can only add a single ''MNet remote enrolments'' method per course.)

===Using it===

==Connecting to a Mnet hub==
A Mnet hub (do not confuse it with the [[Community hub]] project of Moodle 2.0) is a Moodle server that is configured to accept connections from other Moodle servers, and to provide a set of services to users of these other servers. This guideline will direct you to connect to a Mnet hub, assess the services it has to offer, and enable those services for your users.

===Setup===
# Get talking to the Hub
## Ensure that the ''Admin > Server > Environment'' page indicates you have curl and openssl installed
## Go to ''Admin > Network > Settings'' and turn Networking on
## Go to ''Admin > Network > Peers'' and enter the URL of Mnet Hub under "Add New Host". Click Add
## The host details for the Mnet Hub should appear with the Site Name field already populated. Click Save changes
## The details will be written to your database and two new tabs will appear in this window: 'Services' and 'Logs'. Click Services
##A list of services will appear, each with a checkbox for 'publish' and 'subscribe'. Check the checkboxes for any services you want to publish or subscribe to

===Using it===
If the Mnet Hub has already enabled a service for you, there will be a tick alongside the appropriate checkbox, for example: if the Hub is publishing Moodle Networked Enrolment, then a tick will appear alongside the subscribe checkbox for this service. Note that in order to enable some functionality, prominently single-sign-on, you may have to publish a service, e.g. the Identity Provider service. The Mnet Hub will access this service on your Moodle, asking it to authenticate your users.
# Enable Roaming
## Subscribe to SSO (Service Provider) by checking the box
## Publish SSO (Identity Provider) by checking the box
## Click Save changes
## Go to ''Admin > Users > Permissions > Define Roles'', and grant the capability Roam to a remote Moodle moodle/site:mnetlogintoremote to an appropriate role
## Go to ''Administration > Plugins > Authentication > Manage authentication'' in 2.0 onwards or ''Administration > Users > Authentication > Manage authentication'' in 1.9 and enable the Moodle Network authentication plugin
## Go to your homepage, turn on editing, and add the 'Network Servers' block
## Using a different web-browser, log on as a non-admin user who inhabits the role you granted the roaming capability to
## Note that the Mnet Hub is listed in the Network Servers block on the homepage. Click on the link to that server
## Some of your user details will be transferred to the Mnet Hub server, and a browsing session will be started for you as if you had logged on there directly
# Enable Networked Enrolment
## Return to the web browser you've been using as the site administrator
## Go to ''Admin > Network > Peers'' and click on the entry for the Mnet Hub.
## Click on the Services tab
## Subscribe to Moodle Networked Enrolment
## Go to ''Site administration > Plugins > Enrolments > Manage enrol plugins'' in 2.0 onwards or ''Administration > Courses > Enrolments'' pre-2.0 and enable the Moodle Network enrolment plugin. Click Save changes
## Click on edit to view the details for networked enrolments.
## Go to ''Admin > Networking > Enrolments'' to see a list of Moodle servers that offer this service to you
## Click on a server name to view a list of courses that the server offers to your users
## Click on a course name, to view a list users that you can enrol in this course
## Enrol users
## Profit!

==Running a Mnet hub==
A Mnet hub is a regular Moodle site that runs in a special mode. As a Moodle Administrator, when you add another Moodle site to your list of network peers, your Moodle will contact that site to find out what it is called, and to request its public key for encrypted communication. Normally, the remote server will simply provide this information without making any record of the transaction.

A Mnet hub is different. As soon as you add an entry for a Mnet hub to your system, the Mnet hub will create an entry for your server in its list of hosts, and may immediately begin to offer services to the users of your site.

This section will guide you to set up a Mnet hub, and select services to offer to all comers.

===Setup===
# Enable Networking
## Ensure that the ''Admin > Server > Environment'' page indicates you have curl and openssl installed
## Go to ''Admin > Network > Settings'' and turn Networking on
## Go to ''Admin > Network > Peers'' and tick the checkbox for Register all hosts. Click on Save Changes
## On the same page, the first entry in your list of hosts should be All hosts. Click this link
## Click on Services and enable any services you want to offer to all comers

==See also==

* [[Moodle Network FAQ]]
* [[Development:Moodle Network|Moodle Network development notes]]
* Using Moodle [http://moodle.org/mod/forum/view.php?id=6976 MNet forum]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=92749 Examples of how people are using Moodle networks] forum discussion

[[Category:Authentication]]
[[Category:Enrolment]]
[[Category:MNet]]

[[fr:Réseau Moodle]]
[[ja:Moodleネットワーク]]
[[es:Red Moodle]]
[[cs:Síťové služby]]

MNet

2011-02-01T21:24:00Z

Tdjones: /* Setup */

The network feature allows a Moodle administrator to establish a link with another Moodle, and to share some resources with the users of that Moodle. This features was introduced in Moodle 1.8.

==Overview==
The initial release of MNet is bundled with a Authentication Plugin, which makes single-sign-on between Moodles possible. A user with the username jody logs in to her Moodle server as normal, and clicks on a link that takes her to a page on another Moodle server. Normally, she would have only the privileges of a guest on the remote Moodle, but behind the scenes, single-sign-on has established a fully authenticated session for Jody on the remote site.

'''WARNING:''' MNet requires the use of '''xmlrpc'''. Please go to your phpinfo page if you are interested in using this and search for --with-xmlrpc. If your php has not been compiled with xmlrpc then you need to address that first! At present it appears that PEAR xmlrpc will not work.
[[Image:Administration Block Users Authentication MoodleNetwork.jpg|thumb|MNet setting in ''Admin > User > Authentication > Moodle Network]]

==Security==
The MNet feature requires that your server has the '''Curl''' and '''OpenSSL''' extensions installed. When you install or upgrade to Moodle 1.8, your system will generate a new OpenSSL certificate for encrypted communication with other Moodles, and will thereafter rotate encryption keys on a monthly basis (approx).

Communication takes place over an XML-RPC transport, and the XML-RPC documents are wrapped first in an XMLDSIG (XML digital signature) envelope, and then in an XMLENC (XML encryption) envelope. The encryption all happens within PHP, and does not require an https (Apache SSL) server.

References:
*[http://www.w3.org/TR/xmldsig-core/ XML Digital Signatures]
*[http://www.w3.org/TR/xmlenc-core/ XML Encryption]

A special mode can be enabled which would allow a machine with a specified IP address to make calls to the XML-RPC layer without using either encryption or signature envelopes. This mode is provided to enable Moodle to communicate with other software systems in which the integration of signatures and encryption might be prohibitively difficult. It is not envisioned that unencrypted inter-Moodle networking will ever be enabled.

==Peer to Peer Network==

This is the basic layout of the system. It can be very useful to run one Moodle per faculty or departments, each with its own user management, and yet permit users to roam across the Moodle installs... subject to permissions of course.

===Setup===

The instructions will cover 2 Moodle installations: MoodleA and MoodleB. Both are installed correctly and have never had a Moodle Network configuration.

Note: If you experience problems, ensure debugging is turned on in ''Site Administration > Server > Debugging''. Extra diagnostic messages may be displayed (particularly from Moodle 1.9.2)

For Moodle 2.0, you need to enable Networking (under the Site Administration > Advanced Features menu). This will add the "Networking" menu to the Site Administration menu.

# Get them to talk to each other
## Ensure ''Admin > Server > Environment'' indicates you have curl installed
## If MoodleA and MoodleB are hosted in the same domain, ensure they have a different cookie prefix. Note that changing the cookie prefix will log you out! You can change the cookie prefix via ''Admin > Server > Session Handling''.
## On both, go to ''Admin > Network > Settings'' and turn Networking ON.
## On MoodleA go to ''Admin > Network > Peers'' - put the URL of MoodleB under "Add New Host" and click Add. The URL should include the directory where your Moodle code is located, for example ''www.mymoodle.org/moodle''.
## Do the equivalent on MoodleB.
# Get user roaming going
## (Although discussion exists about removing this setting, it is still required as of 2.0.1) [http://moodle.org/mod/forum/discuss.php?d=141491] ). On both servers:
### For 2.0, go to ''Administration > Plugins > Authentication > Manage authentication''. Enable ''MNet Authentication'' by clicking the 'enable' icon.
### For 1.9, go to ''Administration > Users > Authentication > Manage authentication'' and enable Moodle Network authentication plugin. Click on 'Settings' and enable auto_add_remote_users.''
## On MoodleA go to ''Admin > Networking > (Manage) Peers'', click on 'MoodleB', and click on 'Services'. Enable SSO-IDP(SSO Identity Provider) publish and subscribe, and SSO-SP(SSO Service Provider) publish and subscribe.
## Do the equivalent on MoodleB. (By both publishing and subscribing you allow users to move freely between the two servers. By only publishing or subscribing between servers you create a one way traversal)
## On both, go to ''Admin > Users > Permissions > Define Roles'', only roles that have "Roam to a remote Moodle moodle/site:mnetlogintoremote" will be allowed to roam. Grant the privilege as appropriate.
### eg. enabling for ''Authenticated user'' allows any authenticated user to roam between servers.
## On both servers, go to the homepage, and add the 'Network Servers' block.
## To test, it is recommended to use a different browser (even on a different machine) that is logged in to neither. Login to MoodleA with a non-administrator account that has the permissions to roam. You should see the Network Servers block, and clicking on it you should go to MoodleB with a newly autocreated account.
# Get remote enrolments going -- this is optional. It allows an administrator of MoodleB to enrol users that are "native" to MoodleB in remote courses in MoodleA, and viceversa.
## On both, go to ''Site administration > Plugins > Enrolments > Manage enrol plugins'' in 2.0 onwards or ''Administration > Courses > Enrolments'' pre-2.0 and enable Moodle Network enrolment plugin (click Save). Click on 'Edit' and enable 'allow_allcourses' or select some courses or categories to be remotely enrolled.
## On the server you want to receive enrolments:
### For 2.0, go to ''Site administration > Plugins > Enrolments > Manage enrol plugins''. Enable ''MNet remote enrolments'' by clicking the 'enable' icon. (For ''MNet remote enrolments'' settings info see [[MNet_remote_enrolments|MNet remote enrolments]])
### For 1.9, go to ''Administration > Users > Authentication > Manage authentication'' and enable Moodle Network authentication plugin. Click on 'Settings' and enable auto_add_remote_users.''
## On MoodleA go to ''Admin > Network > Peers'', click on 'MoodleB', and click on 'Services'. Enable Enrolment publish and/or subscribe.
## Do the equivalent on MoodleB.
## On every course you want to allow enrolments into:
### Enter course and go to ''Settings -> Course administration -> Users -> Enrolment methods''
### From ''Add method'' drop-down select ''MNet remote enrolments''
### On the new screen select the ''Remote host'' you want to allow enrolments from, the Role for the enrolled users, and click save. (Note: you can only add a single ''MNet remote enrolments'' method per course.)
## To use:
### For 1.9: in MoodleA go to ''Admin > Networking > Enrolments''. You will see MoodleB listed. Click on MoodleB and you will see a list of courses that MoodleB offers for remote enrolment. Select the course you want, and then enroll the users you want to that course.
### For 2.0: in MoodleA go to ''Admin > Networking > Remote enrolments client''. You will see MoodleB listed. Click on ''Edit enrolments'' button beside MoodleB and you will see a list of courses that MoodleB offers for remote enrolment. Click 'Edit enrolments'', select the users you want to enroll, and then click Add to enroll them in the course.

===Using it===

==Connecting to a Mnet hub==
A Mnet hub (do not confuse it with the [[Community hub]] project of Moodle 2.0) is a Moodle server that is configured to accept connections from other Moodle servers, and to provide a set of services to users of these other servers. This guideline will direct you to connect to a Mnet hub, assess the services it has to offer, and enable those services for your users.

===Setup===
# Get talking to the Hub
## Ensure that the ''Admin > Server > Environment'' page indicates you have curl and openssl installed
## Go to ''Admin > Network > Settings'' and turn Networking on
## Go to ''Admin > Network > Peers'' and enter the URL of Mnet Hub under "Add New Host". Click Add
## The host details for the Mnet Hub should appear with the Site Name field already populated. Click Save changes
## The details will be written to your database and two new tabs will appear in this window: 'Services' and 'Logs'. Click Services
##A list of services will appear, each with a checkbox for 'publish' and 'subscribe'. Check the checkboxes for any services you want to publish or subscribe to

===Using it===
If the Mnet Hub has already enabled a service for you, there will be a tick alongside the appropriate checkbox, for example: if the Hub is publishing Moodle Networked Enrolment, then a tick will appear alongside the subscribe checkbox for this service. Note that in order to enable some functionality, prominently single-sign-on, you may have to publish a service, e.g. the Identity Provider service. The Mnet Hub will access this service on your Moodle, asking it to authenticate your users.
# Enable Roaming
## Subscribe to SSO (Service Provider) by checking the box
## Publish SSO (Identity Provider) by checking the box
## Click Save changes
## Go to ''Admin > Users > Permissions > Define Roles'', and grant the capability Roam to a remote Moodle moodle/site:mnetlogintoremote to an appropriate role
## Go to ''Administration > Plugins > Authentication > Manage authentication'' in 2.0 onwards or ''Administration > Users > Authentication > Manage authentication'' in 1.9 and enable the Moodle Network authentication plugin
## Go to your homepage, turn on editing, and add the 'Network Servers' block
## Using a different web-browser, log on as a non-admin user who inhabits the role you granted the roaming capability to
## Note that the Mnet Hub is listed in the Network Servers block on the homepage. Click on the link to that server
## Some of your user details will be transferred to the Mnet Hub server, and a browsing session will be started for you as if you had logged on there directly
# Enable Networked Enrolment
## Return to the web browser you've been using as the site administrator
## Go to ''Admin > Network > Peers'' and click on the entry for the Mnet Hub.
## Click on the Services tab
## Subscribe to Moodle Networked Enrolment
## Go to ''Site administration > Plugins > Enrolments > Manage enrol plugins'' in 2.0 onwards or ''Administration > Courses > Enrolments'' pre-2.0 and enable the Moodle Network enrolment plugin. Click Save changes
## Click on edit to view the details for networked enrolments.
## Go to ''Admin > Networking > Enrolments'' to see a list of Moodle servers that offer this service to you
## Click on a server name to view a list of courses that the server offers to your users
## Click on a course name, to view a list users that you can enrol in this course
## Enrol users
## Profit!

==Running a Mnet hub==
A Mnet hub is a regular Moodle site that runs in a special mode. As a Moodle Administrator, when you add another Moodle site to your list of network peers, your Moodle will contact that site to find out what it is called, and to request its public key for encrypted communication. Normally, the remote server will simply provide this information without making any record of the transaction.

A Mnet hub is different. As soon as you add an entry for a Mnet hub to your system, the Mnet hub will create an entry for your server in its list of hosts, and may immediately begin to offer services to the users of your site.

This section will guide you to set up a Mnet hub, and select services to offer to all comers.

===Setup===
# Enable Networking
## Ensure that the ''Admin > Server > Environment'' page indicates you have curl and openssl installed
## Go to ''Admin > Network > Settings'' and turn Networking on
## Go to ''Admin > Network > Peers'' and tick the checkbox for Register all hosts. Click on Save Changes
## On the same page, the first entry in your list of hosts should be All hosts. Click this link
## Click on Services and enable any services you want to offer to all comers

==See also==

* [[Moodle Network FAQ]]
* [[Development:Moodle Network|Moodle Network development notes]]
* Using Moodle [http://moodle.org/mod/forum/view.php?id=6976 MNet forum]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=92749 Examples of how people are using Moodle networks] forum discussion

[[Category:Authentication]]
[[Category:Enrolment]]
[[Category:MNet]]

[[fr:Réseau Moodle]]
[[ja:Moodleネットワーク]]
[[es:Red Moodle]]
[[cs:Síťové služby]]

Activity completion

2010-12-02T18:33:46Z

Tdjones:

{{Moodle 2.0}}Activity completion is a new feature in Moodle 2.0 and is found under the advanced settings of most activities. This feature allows the teacher to make student entry into the activity conditional upon meeting standards of completion by another activity.

For example, a teacher will set a Quiz to be dependent upon the student completing a specific Lesson or Assignment activity.

:Note: When it was under development activity completion was called [[Conditional activities]] and there were contributed modules in pre 2.0 Moodles called [[Activity locking]].

==Enabling activity completion==

To use activity completion, the following settings must be enabled:
* By an administrator by checking the ''"Enable completion tracking"'' and ''"Enable conditional availability"'' checkboxes in ''Site Administration > [[Advanced features]]''.
* By an administrator/instructor by selecting ''"Enabled, control via completion and activity settings"'' option in drop-down box for ''"Completion tracking"'' under ''"Student progress"'' area in the ''"Course administration" > "Edit settings"'' page.

After the above settings are enabled, an Activity completion section will appear for teachers on the edit activity page.

Essentially this asks the teacher what is necessary for this activity to be considered complete. It is found in the activity setting's "'''Activity completion'''" This condition can then be checked in the restrict condition area in another activity setting (see restrict availability condition above).

==Require view==

When this option is turned on, students have to view the activity in order to complete it.

* In most cases, clicking the link is enough to 'view' the activity.
* You should usually not turn on the 'view' condition if you have other requirements - this makes extra work for the server and it's unlikely that a student could meet any other conditions without viewing the activity.

==Require grade==

When this option is turned on, students have to get a grade on the activity in order to complete it. For example, a quiz would be marked completed as soon as the user submits it.

It does not matter how well the student did. Getting any grade will mark the activity completed.

It is possible to distinguish between 'pass' and 'fail' grades so that the activity becomes 'completed, passed' or 'completed, not passed' instead of just 'completed'. These results show a different icon and alternative text.

To set this up, you need to specify the pass value for this activity's individual grade:

# Go to the course gradebook by clicking the 'Grades' link on the course administration block.
# From the 'Choose an action' dropdown, pick 'Categories and items'.
# Click the Edit icon next to the grade item for this activity.
# Turn on 'Show Advanced'.
# Type a grade value (e.g. 5.0) in the 'Grade to pass' box.

Once you have done this, anybody submitting the quiz will receive either the pass or fail completion icon. If the quiz can be taken multiple times, the completion icon will automatically update whenever the grade does.

There is one limitation: this only works if grades are immediately visible to students. The grade must be neither permanently hidden, nor hidden until a certain date. If a grade is hidden then only the standard 'completed' state will be displayed - even once the hidden date has passed.

==Locked completion options==

If at least one person has completed an activity, completion options are 'locked'. This is because changing these options may result in unexpected behaviour.

If somebody has ticked an activity as manually completed, and you then set it to automatic completion, the activity will become unticked - very confusing for the student who had already ticked it!

It is best not to unlock options unless you are sure it won't cause problems - for example, if you know that students don't have access to the course yet, so it will only be staff who have marked the activity completed when testing.

===What happens when you unlock===

Once you unlock options and then click 'Save changes', all completion information for the activity will be deleted and, if possible, regenerated according to the new settings.

* If the new completion option is manual, everyone will be set to 'not completed' regardless of any previous setting.
* If it is automatic then, depending on the options chosen, the system may or may not be able to construct a correct current value for everyone.
** The 'viewed' requirement will not work - even if a student has viewed the activity before, it will not be marked completed until they view it again.
** Most other options will be recalculated successfully.

If you change completion options while a student is logged in, they may not see the changes for some minutes.

==See also==

* [http://www.youtube.com/watch?v=G6vjgfMae8U Activity completion in Moodle 2.0 video]
* [[Course completion]]
* [[Conditional activities]]
* [[Activity locking]]

[[Category:Completion]]